architecture-check
Skill9 starsChanged 3 months agoMITView on GitHub
Validate module boundaries, check for architectural drift, and suggest fitness function tests. Compares actual code structure against ARCHITECTURE.md.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- takayoshitoyoda05/claude-ml-templatetheir own version, first seen Oct 20, 2026
- nhat092005/skillstheir own version, first seen Oct 13, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- nhat092005/skills★ 1same name
- takayoshitoyoda05/claude-ml-template★ 1same name
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 repository56 other files it gives its agents.
- .claude/agents/CLAUDE.mdCLAUDE.md
- .claude/hooks/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- .claude/prompts/CLAUDE.mdCLAUDE.md
- .claude/rules/CLAUDE.mdCLAUDE.md
- .claude/skills/CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- vision/CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- scaffold/llms.txtllms.txt
- backlog-reviewSkill
- bootstrapSkill
- brainstormSkill
- buildSkill
- claude-sense-checkSkill
- code-qualitySkill
- commitSkill
- continueSkill
- custom-hooksSkill
- dashboardSkill
- debug-sessionSkill
- deploySkill
- discoverSkill
- doctorSkill
- fix-issueSkill
- framework-upgradeSkill
- handoffSkill
- help-meSkill
- ideateSkill
- lanesSkill
- manual-testSkill
- merge-downSkill
- merge-upSkill
- optimizeSkill
- parallel-workSkill
- performance-checkSkill
- phase-reviewSkill
- pr-statusSkill
- quality-checkSkill
- quickstartSkill
- refine-loopSkill
- researchSkill
- retrospectiveSkill
- security-auditSkill
- skill-createSkill
- skill-evalSkill
- sprint-endSkill
- sprint-startSkill
- story-cycleSkill
- testing-cycleSkill
- test-validatorSkill
- UAT-cycleSkill
- undo-workSkill
- uninstallSkill
- weekly-maintenanceSkill
- wrap-upSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 8 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 28
If ARCHITECTURE.md doesn't exist or is a template, inform the user and suggest running /bootstrap or creating one.
- Distinctive: line 36
If the Module Map section contains explicit Dependency Rules (MUST/NEVER statements), use those as the primary validation criteria rather …
- Very specific: line 71
If the Module Map section contains Dependency Rules (MUST/NEVER/MAY statements):
- Distinctive: line 75
Verify with import analysis: scan actual imports in the subject modules
- Distinctive: line 82
Read the Update Triggers section.
- Distinctive: line 100
Check consistency: do all endpoints use the documented authentication method?
- Very specific: line 101
If an API spec file exists (openapi.yaml, asyncapi.yaml, etc.): verify it is referenced in the API documentation header
- Distinctive: line 109
If it references a file: verify the file still exists and the described condition is still present
- Distinctive: line 110
If it references a pattern: grep for it
- Very specific: line 116
Read docs/reference/GROUND_RULES.md.
- Distinctive: line 121
Check the Exception Log — any violation covered by a non-expired exception is compliant.
- Distinctive: line 126
If significant architectural changes are found (new dependency, pattern deviation across 3+ files, deviation from an accepted ADR), …
- Very specific: line 180
ADR-to-ground-rule promotion: If docs/adr/ contains 2+ accepted ADRs addressing the same architectural concern (e.g., repeated boundary …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
architecture-check
You are a software architect validating that the codebase adheres to its documented architecture.
1. Load Architecture Documentation
Read:
docs/architecture/ARCHITECTURE.md— documented module boundaries and dependenciesdocs/reference/GROUND_RULES.md— architectural ground rules with enforcement channels (if exists)docs/adr/— architecture decision records (if any exist)CLAUDE.md— architecture one-liner
If ARCHITECTURE.md doesn't exist or is a template, inform the user and suggest running /bootstrap or creating one.
2. Validate Module Boundaries
Apply the architectural_impact reasoning tool from .claude/skills/story-cycle/references/reasoning-tools.md to assess module boundaries systematically.
For each documented module/layer:
If the Module Map section contains explicit Dependency Rules (MUST/NEVER statements), use those as the primary validation criteria rather than inferring boundaries from the diagram alone.
Import Analysis
Scan imports to check for violations:
- No cross-layer imports — e.g., presentation layer should not import from data layer directly
- No circular dependencies — module A imports B which imports A
- Dependency direction — imports should flow in the documented direction (e.g., handlers → services → repositories, not reversed)
# Example: Find imports across boundaries
# grep -r "from data_layer" presentation_layer/
# grep -r "import.*handler" repository_layer/Boundary Check
For each module:
- Does it only depend on modules it's allowed to depend on?
- Are there any "reaching across" imports that skip layers?
- Are shared types/interfaces in the right location?
3. Check for Architectural Drift
Compare the actual code structure against ARCHITECTURE.md:
- New modules — code directories not documented in ARCHITECTURE.md
- Missing modules — documented modules that don't exist (yet or anymore)
- Changed responsibilities — modules doing things outside their documented scope
- Undocumented dependencies — imports between modules not shown in the architecture
3.5. Validate Dependency Rules
If the Module Map section contains Dependency Rules (MUST/NEVER/MAY statements):
For each rule:
- Parse the rule into:
[subject] [MUST/NEVER/MAY] [action] [target] - Verify with import analysis: scan actual imports in the subject modules
- Report violations with file:line evidence
Example: Rule "Controllers MUST only call services" → grep controller directory for imports outside the services layer.
3.7. Check Update Triggers
Read the Update Triggers section. For each trigger, check if recent changes match:
LAST_VERIFIED=$(grep -oP 'Last Verified: \K[\d-]+' docs/architecture/ARCHITECTURE.md 2>/dev/null)
if [ -n "$LAST_VERIFIED" ]; then
git log --since="$LAST_VERIFIED" --name-only --pretty=format: | sort -u | head -30
fiCompare changed files against trigger conditions (new top-level directories, new data stores, changed API boundaries). Flag any matches as "Architecture doc may be stale."
3.7b. Validate API Documentation Currency (if API project)
<IF condition="docs/reference/API_DOCUMENTATION.md exists and has populated Operations section (not just template placeholders)">- Grep for route/endpoint definitions in the codebase (framework-specific:
@app.route,router.get,@RequestMapping,func (h *Handler), etc.) - Compare discovered endpoints against documented Operations in
docs/reference/API_DOCUMENTATION.md - Flag: undocumented endpoints (in code but not in docs), stale documentation (in docs but removed from code)
- Check consistency: do all endpoints use the documented authentication method? Do error responses follow the documented error format?
- If an API spec file exists (
openapi.yaml,asyncapi.yaml, etc.): verify it is referenced in the API documentation header
Report findings in the output under ### API Documentation Currency.
</IF>
3.8. Validate Known Landmines
For each entry in the Known Landmines section:
- If it references a file: verify the file still exists and the described condition is still present
- If it references a pattern: grep for it
- Flag entries that appear to be resolved (file removed, pattern no longer present)
3.9. Validate Ground Rules
<IF condition="docs/reference/GROUND_RULES.md exists and has GR-NNN rules">
Read `docs/reference/GROUND_RULES.md`. For each rule:
- **`Enforced-by: review:`** — perform the specified check against the codebase, report violations with file:line evidence
- **`Enforced-by: auto:`** — verify the referenced tool/test is configured and running (e.g., ArchUnit test exists, dependency-cruiser config present). Flag unconfigured enforcement as "enforcement gap"
- **`Enforced-by: ai:`** — check that recent changes don't violate the ai instructionCheck the Exception Log — any violation covered by a non-expired exception is compliant.
</IF>
4. Auto-Generate ADR (if drift detected)
If significant architectural changes are found (new dependency, pattern deviation across 3+ files, deviation from an accepted ADR), generate a draft ADR using the project's template format:
---
status: proposed
date: {today}
decision-makers: []
tags: [{relevant domain tags}]
rejected-options: []
supersedes: {ADR-NNNN if deviating from existing ADR, else null}
superseded-by: null
linked-ground-rules: []
confidence: medium
---
# ADR-NNNN: {Imperative title describing the drift}
## Context
{Describe the detected drift — what changed in the code, what prior decision
(if any) it deviates from, and what forces drove the change. 2-4 sentences
based on evidence from the codebase.}
## Decision
**We will {accept the drift as the new standard / revert to the documented architecture / update documentation to match}.**
{1-2 sentences expanding. Flag as `status: proposed` for human review.}
## Alternatives Considered
### ✅ {The detected approach} (Selected)
- **Why chosen:** {what evidence in the codebase supports this direction}
### ❌ {The prior documented approach}
- **Why rejected:** {what changed that made the prior approach insufficient}
- **Reconsider when:** {conditions under which the original approach would be better}
## Consequences
- **Positive:** {what the drift improves}
- **Negative:** {what risk or cost the drift introduces}
- **Operational:** {what the team must now do differently}
## Compliance
{Suggest a concrete check — grep pattern, test, or review instruction —
to verify this decision is followed going forward.}Save to docs/adr/NNNN-short-title.md (sequential 4-digit number). Update the Index table in docs/adr/README.md.
Also check existing ADRs for staleness: For each confidence: low ADR, check whether its Reconsider when conditions have been met. Flag any that need review.
ADR-to-ground-rule promotion: If docs/adr/ contains 2+ accepted ADRs addressing the same architectural concern (e.g., repeated boundary violations, recurring dependency decisions), suggest promoting it to a ground rule in docs/reference/GROUND_RULES.md with a back-reference to the ADR. Recurring decisions indicate a missing principle.
5. Suggest Fitness Function Tests
For each architectural rule, suggest a test that can be automated:
| Rule | Fitness Function Test |
| No circular dependencies | Import cycle detection script |
| Layer isolation | Import direction validation |
| Module size limits | File/line count per module |
| API surface area | Public export counting |
Output Format
## Architecture Check - [Date]
### Module Boundary Validation
| Module | Dependencies OK | Violations |
|--------|-----------------|------------|
| [name] | YES/NO | [list] |
### Architectural Drift
- [Drift item]: [Documented vs Actual]
### Suggested ADRs
- [NNNN-short-title]: [Brief reason] (status: proposed, confidence: [level])
### ADR Staleness Review
- [ADR-NNNN]: [Reconsider-when condition met? Yes/No — action needed]
### Ground Rules Compliance
| Rule | Level | Status | Evidence |
|------|-------|--------|----------|
| [GR-NNN: name] | MUST/SHOULD | PASS/FAIL/ENFORCEMENT GAP | [file:line or tool status] |
### API Documentation Currency
- [Undocumented endpoints / Stale docs / Consistent — or "N/A (no API detected)"]
### Fitness Function Suggestions
- [Test description]: [What it validates]
### Recommendations
1. [Most important action]
2. [Second priority]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.

