hexagonal-architecture
Skill15 starsChanged 5 months agoMITView on GitHub
Decide WHERE new code goes and WHO may know about whom, before writing it — vigiles is hexagonal (domain, app, adapters, root), and the recurring failure is generic code that names a specific implementation (a rule id, a harness, a group) or an inner layer that imports an outer one. Use before adding a module, a registry or list of things, a type or field named after one thing, a config key derived from a set, or a function that needs "all the rules / all the harnesses"; and whenever a reviewer says "wrong dependency direction", "core knows about X", or "hexagonal". NOT a general architecture essay — it is this repo's map plus the questions that catch the mistake.
25 other projects use a version of this.
Adopted by
Most recently taken up by
- ralvarez-ai/ralvaskillstheir own version, first seen Nov 16, 2026
- Rojios/everything-claude-codetheir own version, first seen Nov 8, 2026
- Lukk17/agent-standardstheir own version, first seen Nov 7, 2026
- pankaj-mahaur/Agent-Daemontheir own version, first seen Nov 6, 2026
- nledford/engineering-review-boardtheir own version, first seen Nov 3, 2026
- sandlada/skill-hexagonal-architecturetheir own version, first seen Oct 25, 2026
Used with
Projects with it also use layered-architecture, domain-driven-design and 3 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
dkprogSkilllayered-architecture
Apply when structuring a backend service, creating new modules, or deciding where to place business logic. Ensures separation into transport, domain, and data access layers with correct dependency direction.
Also in 3 projects that use this
jarrodmedranoSkilldomain-driven-design
This skill should be used whenever domain modeling is taking place. It provides specialized guidance for type-driven and data-driven design based on Rich Hickey and Scott Wlaschin's principles. The skill helps contextualize current modeling within the existing domain model, identifies inconsistencies, builds ubiquitous language, and creates visualizations (Mermaid, Graphviz/DOT, ASCII diagrams) to communicate domain concepts clearly. Use this skill when designing types, modeling business domains, refactoring domain logic, or ensuring domain consistency across a codebase.
Also in 4 projects that use this
harrissohail6Skillclean-architecture
Clean architecture and SOLID principles. Auto-activates when designing systems or refactoring code structure.
Also in 3 projects that use this
GoogleSkillimprove-codebase-architecture
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
Also in 3 projects that use this
GoogleSkillgrill-me
A relentless interview to sharpen a plan or design.
Also in 3 projects that use this
Other versions25 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 25
- rrezartprebreza/spring-boot-skills★ 360same name
- yamcodes/arkenv★ 151same name
- Fmarzochi/EGC★ 61same name
- fatonh/symfony-skills★ 35same name
- nledford/engineering-review-board★ 11same name
- gongyijie85/dsh-ecc★ 8same name
- ralvarez-ai/ralvaskills★ 4same name
- kayaman/skills★ 3same name
- ankhorage/devtools★ 2same name
- ffsshhttiikk/opencode-agents-skills★ 2same name
15 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository24 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- examples/CLAUDE.mdCLAUDE.md
- src/CLAUDE.mdCLAUDE.md
- add-a-linterSkill
- audience-checkSkill
- audit-feedback-loopSkill
- code-qualitySkill
- deep-researchSkill
- dogfood-cliSkill
- enforce-rules-formatSkill
- generate-logoSkill
- landing-siteSkill
- pr-to-lint-ruleSkill
- review-docsSkill
- screenshotSkill
- ship-a-featureSkill
- verify-docs-findableSkill
- pr-to-lint-ruleSkill
- adopt-specSkill
- debug-my-harnessSkill
- edit-specSkill
- linter-docsSkill
- strengthenSkill
- test-harnessSkill
The file
We split this skill into the rules it gives an agent
4 rules. 0 are common, 2 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 24 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 48
All four happened in one PR (#387) and were caught by the owner, not by a check:
- Very specific: line 85
Who builds the set?: Only a composition root (src/cli{,-main}.ts, a package entry in src/entries/, and the browser demo's entry for the …
- Distinctive: line 87
What does the type system have to carry?: When core stops importing the set, typed things that depended on it (the config type, a union of …
- Very specific: line 91
Which check holds it?: Every answer above needs a mechanism — a boundaries element and policy, a name fence like no-harness-names, a type, …
“Common” is measured: kept by at least 6 in 10 of the 24 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Hexagonal architecture in vigiles
One rule decides everything below: dependencies point inward. The inner layer defines what it needs (a port: an interface or a type); outer code implements it; one composition root picks the implementations and hands them in. An inner file never imports, names or lists an outer thing — not by import, not by string, not by type name.
The map (what eslint.config.mjs enforces today)
| layer | where | may import | knows about |
| domain | src/core/ | domain, pure libraries | nothing outside itself |
| app | src/*.ts (scan, score, report, runners) | domain, other app files | ports, never a concrete adapter |
| adapter | src/adapters/<harness>/, src/host/ | domain only | its own harness (host: the machine) only |
| rule | src/rules/<id>.ts | domain only | its own id and nothing else |
| ruleset | src/rules/{index,groups}.ts | rules, domain | every rule and group — the set the root reads |
| io | src/{adapters/*,host}/*.io.ts | + I/O modules | the outside world |
| root | src/cli{,-main}.ts, src/entries/*.ts | anything | everything — the only places that wire |
| tests | src/**/*.test.ts | anything | — |
Held by boundaries/dependencies (layers() in packages/eslint-config/index.mjs, with
the rules/ruleset file categories for the rule layer), local/no-harness-names (no
file spells a harness other than its own adapter's), local/no-rule-ids (no file spells a
rule id but the rule's own module, its test and the set), local/no-group-names (no
generic file names a rule group) and local/no-kit-names (rule-proof's generic files spell
no linter kit).
src/host/ is the adapter for the MACHINE — files and processes no harness owns (rule-proof
runs another repository's linter). It is not a harness: HARNESS_NAMES and the adapter
contract read src/adapters only. A package entry that needs an adapter (vigiles/rule-proof)
is served from src/entries/<name>.ts, a composition root — an app barrel may not import an
adapter, and the old barrels that do (claude-code.ts, eval.ts) are grandfathered, not a model.
Harnesses are the worked example of doing it right: core declares the five ports
(HarnessDialect, PluginLayout, HarnessRuntime, HookProtocol, ModelMock), each
src/adapters/<harness>/ implements them, and only the root (and the testing barrels that
default to one) chooses which adapter runs. Adding a harness = one new directory + one
registration at the root; core does not change. Copy this shape for anything else that
comes in many kinds — lint rules, report renderers, linter catalogs.
The mistakes this skill exists for
All four happened in one PR (#387) and were caught by the owner, not by a check:
- An inner file lists the outer things.
EXPERIMENTAL_RULES = ["skill-resource-resolves"]insrc/core/. A list of implementations is knowledge about the outside. It belongs to the outer layer (or is DERIVED from the implementations' own declarations). - The "registry" lives in core and imports implementations. Moving a list into one file inside core does not fix (1); it only concentrates it. The set of implementations is assembled OUTSIDE core and passed IN — as a parameter or through a port.
- A type, field or function is named after one implementation or category.
ExperimentalFinding,AuditReport.experimental,ScanReport.experimental["<rule id>"]. Being in a group is a fact about a rule TODAY, not what a finding IS. Generic code gets a generic type (Finding,ungraded), and the category is a FIELD read at run time. - A per-implementation default restated in generic code.
"<rule id>": severitySchema.default(false)in the config schema. The rule declares its own default; the schema is BUILT from the declarations (buildConfigSchema(rules)), not written next to them.
Again in PR #415 (2026-11-02), with this skill LOADED before the code was written: rule-proof
supported two linters and its steps file branched on reading.linter === "eslint" 30 times,
one 600-line domain file held both linters plus the Node install, and the io adapter wired the
public object. Lint caught only the I/O placement; the owner's "show me the architecture"
caught the rest. The fix was the harness shape again — a ProofKit port, one kit module per
linter, kits/index.ts as the only list, src/entries/rule-proof.ts as the root — plus the
no-kit-names fence. Reading the questions is not answering them: write question 2's table.
Questions to answer before writing the code
- Who knows about whom? Draw the arrows. Any arrow from
src/core(or app) to a specific implementation is wrong. - Adding one more of these — how many files change? Target: the new module + one line
in the outer list the root reads. If a generic file would also change, the design leaks.
Write the answer down BEFORE the code, in the PR body, as a row per kind of thing:
kind → where the list is → files that change for one more. TWO of something already counts as "many kinds": two is when theif (x.kind === "a") … else …gets written. - Does any generic file spell the name of one implementation (id string, type name, field name, enum member)? If yes, move that knowledge into the implementation.
- Is a category a list somewhere, or a field of the thing? It must be a field; lists
are derived (
rules.filter(r => r.group === g)). - Who builds the set? Only a composition root (
src/cli{,-main}.ts, a package entry insrc/entries/, and the browser demo's entry for the site). Core functions take it as an argument. - What does the type system have to carry? When core stops importing the set, typed things that depended on it (the config type, a union of ids) become generics over the set, exported from the outer layer or the root. That is the cost; pay it, do not route around it by importing inward-out.
- Which check holds it? Every answer above needs a mechanism — a
boundarieselement and policy, a name fence likeno-harness-names, a type, or a planted-violation test. A rule held only by this text will be broken by the next agent (prose is not policy). A new family of implementations gets its own name fence, built oneslint-rules/no-foreign-names.mjs(a dozen lines —no-kit-names.mjsis the smallest example): the names read from the family's directory ineslint.config.mjs, the fence on the generic files only, and planted cases ineslint-rules/fences.corpus.test.tsthat fire on a generic file and stay quiet in the implementation, the set and the root.boundariesstops the IMPORT of an implementation; only a name fence stops the BRANCH on its name, which imports nothing.
What is not a violation
- The composition root importing and wiring everything. That is its job — though even the root spells no rule id: it picks a rule off the set by a property of the rule.
- An implementation naming itself (an adapter spelling its own harness; a rule module its own id) and its own tests.
- Detectors in
src/core. A pure function that resolves a path or parses frontmatter is a domain capability; the POLICY around it (id, group, default, how to present) is what lives outside. - Grandfathered sites recorded in
eslint-suppressions.json. The count may only go down; a new one is an error. Grandfathering is for old code, never for the change you are making.
Where this is decided and recorded
- Layers and policies:
layers()inpackages/eslint-config/index.mjs, wired ineslint.config.mjs. - Harness fence:
eslint-rules/no-harness-names.mjs(its header says why). - Root
CLAUDE.md→ Architecture section (compiled fromCLAUDE.md.spec.ts). - The rule layer (landed in PR #387): core declares the port (
src/core/rule.ts), a rule is a modulesrc/rules/<id>.ts,src/rules/groups.tsis the group record andsrc/rules/index.tsthe set; the roots (src/cli-main.ts,site/src/demo/runAudit.ts,scripts/build-config-schema.mjs) hand it toconfigFor/initPolicyOf/applyRules. Fences: therules/rulesetboundaries categories,local/no-rule-ids,local/no-group-names,local/frame-mintonFilteredScan, andno-restricted-syntaxon.ungradedin the scorers — planted violations ineslint-rules/fences.corpus.test.tsandpackages/eslint-config/index.test.ts. 35 rules are still rows insrc/rules/index.tsand old spellings are grandfathered; moving them and reaching zero is #390.docs/contributing/rules.md#rules-are-an-outer-layerhas the invariant table.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

