architecture-guidelines
System architecture: modules, project structure, ADRs, and testing. Use when designing or reviewing systems.
architecture
guidelines
SKILL.md.claude/skills/architecture-guidelines
GitHubArchitecture Guidelines
How packages and services are structured, composed, tested and documented as decisions.
Always
- Domain logic and its port types live together in
domain/; adapters live inadapters/. Noports/directory. - Callers import adapters explicitly and pass them in. No string-selected adapters, no convenience factories, no dynamic imports inside a package.
- Library code reaches the runtime through
@eserstack/standards/cross-runtime, neverDeno.*. - Every option has a safe default; add an option only for a named case; no positional booleans.
- Request ids and trace state travel in the request context, never as extra parameters.
- Unit tests with fakes for logic, integration tests for adapters; failure paths tested; coverage never drops.
- Validator and codebase-tool design lives in
pkg/@eserstack/codebase/AGENTS.md - A lasting architectural decision gets an ADR in
docs/adr/.
References
| File | Read when |
|---|---|
| hexagonal-architecture.md | Structuring a package, adding an adapter, adding options, flags or env vars |
| testing.md | Deciding what and how to test, choosing the runner, coverage |
| adrs.md | Recording an architectural decision |