0-hexagonal — Claude Code rule: what it does, how to install
The 0-hexagonal rule splits each context into four layers and keeps dependencies pointed inward. Use it when reviewing TypeScript architecture.
MIT ★ 571 updated 2026-10-29
.claude/rules/0-hexagonal.mdWhat 0-hexagonal does
The rule targets src/contexts/**/*.ts and src/runtime/**/*.ts. It separates context code into domain/, application/, and infrastructure/: the domain contains entities, value objects, pure transformations, and capabilities; the application layer coordinates use cases; infrastructure handles port implementations and I/O.
Interfaces live in domain/ports/ or kernel/ports/, while adapters belong in infrastructure/ and receive a port through the constructor. import-rules-bite.arch.test.ts and ports-are-called.arch.test.ts check architectural boundaries, with import and global restrictions defined in biome.json. Since process is rejected in domain/ and application/, those layers must access it through a port.
What it helps with
- split a context into four layers
- keep dependencies pointed toward the domain
- move I/O behind adapters
- check import boundaries
- match each adapter to one port
Example prompts for the agent
- Review
src/contexts/orders/**/*.tsagainst 0-hexagonal and list layer violations. - Run an architecture review on
src/runtime/**/*.ts; find directprocessaccess and port violations. - Check that every adapter in
infrastructure/implements one port and receives it through its constructor.
How to install 0-hexagonal
Manually: put the files in place
.claude/rules/0-hexagonal.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/0-hexagonal.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/0-hexagonal.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/0-hexagonal.mdManually: put the files in place
.clinerules/0-hexagonal.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about 0-hexagonal
How do I install 0-hexagonal in Claude Code?
Save the rule as .claude/rules/0-hexagonal.md.
What does 0-hexagonal do?
It defines four layers inside a context, keeps dependencies directed inward, and separates ports from their adapters. It also sets architectural checks for imports and port usage.
Why is process blocked in domain/ and application/?
The restriction is configured in biome.json. Code in those layers must use a port instead of accessing the environment directly, while I/O stays in infrastructure.
Source text
0-hexagonal.md · MIT
--- description: Apply inside a context; four layers, dependencies pointing inward, one adapter per port. paths: - "src/contexts/**/*.ts" - "src/runtime/**/*.ts" --- # Layers Inside a Context Which context owns a concept is `0-contexts.md`. ## Layers - `domain/`: entities, value objects, pure transforms, capabilities. No I/O. - Validate an invariant at construction. - `domain/ports/`: interfaces only. - `application/`: one class per use case, orchestration only. - Never branch on the targeted tool; read its capability class. - `infrastructure/`: port implementations and every piece of I/O. - Dependencies point inward; `biome.json` holds one `noRestrictedImports` override per layer. - `biome.json`'s `noRestrictedGlobals` refuses `process` in `domain/` and `application/`; take a port. - `import-rules-bite.arch.test.ts` fails a pattern naming a vanished directory. ## Ports and adapters - One context: `domain/ports/`. Two: `kernel/ports/`. - Name an adapter `*Adapter`, in `infrastructure/`; `runtime/` for a kernel port. - An adapter does I/O and format translation only. - Inject through the constructor, typed as the port. - One adapter, one port; `FileAdapter` is recorded debt. - A port declares no uncalled method (`ports-are-called.arch.test.ts`, empty baseline). - `CLIOutput` implements the kernel `Logger` from `presentation/output.ts`.
© ai-driven-dev · MIT · ai-driven-dev/framework