From ce951b692300d9f8d96af1ef01142748b4ea2bc0 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 19 Apr 2026 14:08:30 -0500 Subject: feat: architecture skill suite — design, decide, document, evaluate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four chained Claude Code skills covering the full architecture lifecycle: arch-design Intake (stakeholders, scale, quality attributes, constraints) → candidate paradigms with honest trade-off analysis → recommendation + open-decision list → .architecture/brief.md arch-decide ADR creation and management. Five template variants (MADR, Nygard, Y-statement, lightweight, RFC). Lifecycle, review process, adr-tools automation. Forked from wshobson/agents (MIT). LICENSE preserved. arch-document Full arc42-structured documentation (12 sections) from brief + ADRs + codebase. Dispatches to c4-analyze / c4-diagram for Context, Building Block, Runtime, Deployment diagrams. arch-evaluate Audits implementation against stated architecture. Framework-agnostic checks (cyclic deps, stated-layer violations, public API drift, forbidden deps) run on any language. Opportunistically invokes language-specific linters when configured (dependency-cruiser for TS, import-linter for Python, go vet + depguard for Go). Never installs tooling. Supporting docs at docs/architecture/: - README.md suite overview, install steps, per-language linter install commands (Python import-linter, TS dependency-cruiser, Go golangci-lint, Java ArchUnit future, C/C++ IWYU future), typical flow through the chain - v2-todo.org deferred features (auto-gen linter configs, ArchUnit, CI mode, DDD aggregate boundaries, visual dep graphs, retroactive layering inference) Makefile SKILLS extended with the four new entries; make install symlinks them to ~/.claude/skills/ alongside existing skills. Landscape: arch-decide fills the well-covered ADR bucket by adopting the strongest community offering rather than reinventing. arch-design and arch-evaluate fill gaps where no general-purpose skill existed. arch-document fills the arc42 gap (C4 diagrams already covered by sibling skills). --- docs/architecture/README.md | 359 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 359 insertions(+) create mode 100644 docs/architecture/README.md (limited to 'docs/architecture/README.md') diff --git a/docs/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 0000000..e09efb0 --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,359 @@ +# Architecture Suite + +Four chained Claude Code skills for the full architecture lifecycle: **design**, **decide**, **document**, **evaluate**. Paradigm-agnostic (supports layered, hexagonal, microservices, event-driven, CQRS, DDD, and others). Language-aware (framework-agnostic checks work everywhere; language-specific linters augment when configured). + +## The Chain + +``` + ┌─────────────────┐ + New project → │ arch-design │ → .architecture/brief.md + └────────┬────────┘ + │ + (for each open decision) + │ + ▼ + ┌─────────────────┐ + │ arch-decide │ → docs/adr/NNNN-*.md + └────────┬────────┘ + │ + (when ready to formalize) + │ + ▼ + ┌─────────────────┐ + │ arch-document │ → docs/architecture/*.md + └────────┬────────┘ (dispatches to c4-analyze, c4-diagram) + │ + (once code exists, periodically) + │ + ▼ + ┌─────────────────┐ + │ arch-evaluate │ → .architecture/evaluation-YYYY-MM-DD.md + └─────────────────┘ +``` + +Skills are standalone — invoke any one directly. The flow above is the canonical path; you can enter at any point if the prerequisite artifacts already exist. + +## What Each Skill Does + +### [arch-design](../../arch-design/SKILL.md) + +Elicits the architecture: intake (stakeholders, scale, team, timeline), quality-attribute prioritization, constraints, then proposes 2-4 candidate paradigms with honest trade-off analysis. Picks one with rationale. Lists open decisions that become ADRs. + +**Output:** `.architecture/brief.md` + +### [arch-decide](../../arch-decide/SKILL.md) + +Records significant technical decisions as ADRs. Five template variants (MADR, Nygard, Y-statement, lightweight, RFC). Covers ADR lifecycle (proposed / accepted / deprecated / superseded), review checklist, and `adr-tools` automation. + +**Output:** `docs/adr/NNNN-.md`, plus an index at `docs/adr/README.md`. + +**Forked from [wshobson/agents](https://github.com/wshobson/agents) — MIT.** + +### [arch-document](../../arch-document/SKILL.md) + +Produces full arc42-structured documentation from the brief + ADRs + codebase. All twelve arc42 sections. Dispatches to `c4-analyze` (for code-present systems) and `c4-diagram` (for textual descriptions) for the diagrams in sections 3, 5, 6, and 7. + +**Output:** `docs/architecture/01-introduction.md` through `12-glossary.md`, plus diagrams under `docs/architecture/diagrams/`. + +### [arch-evaluate](../../arch-evaluate/SKILL.md) + +Audits the codebase against the brief + ADRs. Four framework-agnostic checks (cyclic deps, stated-layer violations, public API drift, forbidden deps). Opportunistically invokes language-specific linters if they're already configured in the repo. + +**Output:** `.architecture/evaluation-YYYY-MM-DD.md` + +## Installation + +These skills live in this rulesets repo alongside the other skills (`debug`, `add-tests`, `c4-analyze`, etc.). Install globally once: + +```bash +make -C ~/code/rulesets install +``` + +This symlinks every skill (including the four `arch-*`) into `~/.claude/skills/`. Any Claude Code session on this machine will see them. + +To uninstall: + +```bash +make -C ~/code/rulesets uninstall +``` + +To check install state: + +```bash +make -C ~/code/rulesets list +``` + +## Optional: Language-Specific Linters + +`arch-evaluate` works without any external tooling — its framework-agnostic checks cover cycles, layer violations, API drift, and forbidden deps on any language Claude can read. **Installing the linters below is optional** and augments those checks with dedicated tooling: faster on large codebases, CI-friendly, and precise. + +Install only the ones you need for your active languages. + +### Python — import-linter + +Declarative import contracts. Config in `.importlinter` or `[tool.importlinter]` in `pyproject.toml`. + +```bash +pipx install import-linter +# or: pip install --user import-linter +# or (in a uv-managed project): uv add --dev import-linter +``` + +Verify: + +```bash +lint-imports --help +``` + +Example config (`.importlinter`): + +```ini +[importlinter] +root_package = myapp + +[importlinter:contract:layers] +name = Core layers +type = layers +layers = + myapp.presentation + myapp.application + myapp.domain + myapp.infrastructure + +[importlinter:contract:framework_isolation] +name = Domain isolation +type = forbidden +source_modules = + myapp.domain +forbidden_modules = + django + fastapi +``` + +### TypeScript / JavaScript — dependency-cruiser + +Rich import analysis with a JS config file. The de-facto standard for TS architectural linting. + +```bash +npm install --save-dev dependency-cruiser +# or globally: npm install -g dependency-cruiser +``` + +Verify: + +```bash +npx dependency-cruiser --version +``` + +Generate an initial config: + +```bash +npx dependency-cruiser --init +``` + +Then edit `.dependency-cruiser.cjs` to encode your architecture. Example rule: + +```javascript +module.exports = { + forbidden: [ + { + name: 'domain-no-infrastructure', + severity: 'error', + from: { path: '^src/domain' }, + to: { path: '^src/infrastructure' }, + }, + ], + options: { tsPreCompilationDeps: true, tsConfig: { fileName: 'tsconfig.json' } }, +}; +``` + +### Go — golangci-lint (with depguard) + +`go vet` (part of the stdlib) covers built-in checks. `depguard` (via golangci-lint) enforces import rules. + +```bash +# macOS +brew install golangci-lint + +# Linux / anywhere with Go +go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest +``` + +Verify: + +```bash +golangci-lint --version +go vet ./... +``` + +Example `.golangci.yml`: + +```yaml +linters: + disable-all: true + enable: + - depguard + +linters-settings: + depguard: + rules: + domain: + list-mode: lax + files: + - "$all" + - "!**/infrastructure/**" + deny: + - pkg: "github.com/yourorg/yourapp/infrastructure" + desc: "domain must not depend on infrastructure" +``` + +### Java — ArchUnit (v2+) + +Test-driven: architectural rules live in JUnit tests. Not invoked by `arch-evaluate` in v1. + +**Maven:** + +```xml +<dependency> + <groupId>com.tngtech.archunit</groupId> + <artifactId>archunit-junit5</artifactId> + <version>1.3.0</version> + <scope>test</scope> +</dependency> +``` + +**Gradle:** + +```groovy +testImplementation 'com.tngtech.archunit:archunit-junit5:1.3.0' +``` + +Example rule (`src/test/java/archtest/LayerRules.java`): + +```java +@AnalyzeClasses(packages = "com.yourorg.yourapp") +class LayerRules { + @ArchTest + static final ArchRule layered = + layeredArchitecture().consideringAllDependencies() + .layer("Presentation").definedBy("..presentation..") + .layer("Application").definedBy("..application..") + .layer("Domain").definedBy("..domain..") + .whereLayer("Presentation").mayNotBeAccessedByAnyLayer() + .whereLayer("Application").mayOnlyBeAccessedByLayers("Presentation") + .whereLayer("Domain").mayOnlyBeAccessedByLayers("Application", "Presentation"); +} +``` + +Then run `mvn test` or `gradle test`. + +### C / C++ — include-what-you-use (v2+) + +Checks each source file's `#include` discipline. Not invoked by `arch-evaluate` in v1; listed for completeness. + +```bash +# macOS +brew install include-what-you-use + +# Arch Linux +sudo pacman -S include-what-you-use + +# Ubuntu/Debian +sudo apt install iwyu +``` + +Integrate via CMake: + +```cmake +set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE include-what-you-use) +``` + +Verify: + +```bash +include-what-you-use --version +``` + +## Typical Flow + +### New project + +```bash +# 1. Shape the architecture +# In Claude Code: +/arch-design +# Answer intake questions, rank quality attributes, review candidates. +# Output: .architecture/brief.md + +# 2. Record each open decision +/arch-decide +# Once per significant decision. Output: docs/adr/0001-*.md, 0002-*.md, etc. + +# 3. Formalize (when ready) +/arch-document +# Generates all twelve arc42 sections + diagrams. +# Output: docs/architecture/*.md + +# 4. Audit (once code exists) +/arch-evaluate +# Report at .architecture/evaluation-YYYY-MM-DD.md +``` + +### Existing project with no architecture docs + +```bash +# 1. Retroactively capture +/arch-design # reconstruct the brief from what exists +/arch-decide # write ADRs for past decisions (date them honestly) +/arch-document # produce current-state arc42 docs + +# 2. Audit against the reconstructed intent +/arch-evaluate +``` + +### Continuous + +- Re-run `/arch-evaluate` periodically (on PR, before release, monthly) +- Every significant new decision → `/arch-decide` +- Brief or ADR changes → `/arch-document` to refresh + +## Where Things Land + +``` +<project-root>/ +├── .architecture/ +│ ├── brief.md ← arch-design +│ └── evaluation-YYYY-MM-DD.md ← arch-evaluate +├── docs/ +│ ├── adr/ +│ │ ├── README.md ← arch-decide (index) +│ │ └── NNNN-<title>.md ← arch-decide +│ └── architecture/ +│ ├── README.md ← arch-document (index) +│ ├── 01-introduction.md … ← arch-document +│ ├── 12-glossary.md +│ └── diagrams/ ← arch-document (via c4-*) +│ ├── context.svg +│ ├── container.svg +│ └── runtime-<scenario>.svg +``` + +## Dependencies Between Skills + +- `arch-decide` is standalone; nothing required from the others +- `arch-document` reads the brief and ADRs; without them, it stubs sections as TODO +- `arch-evaluate` requires the brief; without it, the skill stops and tells the user to run `arch-design` +- `arch-document` dispatches to `c4-analyze` (if code exists) and `c4-diagram` (otherwise) — both live in this same rulesets repo + +## Versioning and Deferred Work + +v1 covers the four core skills with the chain above. The deferred feature list — CI integration, auto-generated linter configs, ArchUnit integration, DDD aggregate boundaries, etc. — is tracked at [`v2-todo.org`](v2-todo.org). + +## Licensing + +- `arch-design`, `arch-document`, `arch-evaluate` — part of this rulesets repo +- `arch-decide` — forked from [wshobson/agents](https://github.com/wshobson/agents), **MIT**. See `arch-decide/LICENSE`. + +## Contributing / Modifying + +These are personal skills; fork as needed. If you change a skill and want to re-sync the global install symlink, re-run `make -C ~/code/rulesets install`. Symlinks point back at this repo, so edits propagate without re-install. -- cgit v1.2.3