Three-tier system for documenting code patterns to optimize token usage
This skill inherits all available tools. When active, it can use any tool Claude has access to.
Optimize token usage and ensure consistency by documenting code patterns once instead of repeatedly exploring codebases.
When implementing features in existing codebases, agents typically:
Inefficiency: Repeating exploration wastes tokens and risks inconsistency.
Solution: Extract patterns once using a three-tier documentation system, then reference docs instead of re-exploring.
File: systems/{system}/architecture-patterns.md
Purpose: Explain WHY patterns exist and WHAT the rules are.
Contents:
Example: VioletDashboard's API Proxy Pattern explains why all backend calls must go through Next.js API routes.
File: systems/{system}/reference-implementations.md
Purpose: Point to specific EXAMPLES in the actual codebase.
Contents:
Example: Points to pages/api/merchants/[merchantId]/index.ts:16-36 as the canonical PUT handler example.
File: systems/{system}/code-snippets.md
Purpose: Provide COPY-PASTABLE starting points.
Contents:
Example: Full template for a Redux thunk ready to adapt for any CRUD operation.
Read Tier 1 (Architecture Patterns) first
Look up Tier 2 (Reference Implementation)
Copy Tier 3 (Code Snippet)
Implement
If documented patterns are outdated or incomplete:
last_verified metadata in all docs| Benefit | Description |
|---|---|
| Token Efficiency | Read small pattern docs (~2k tokens) instead of large code files (10k+ tokens) |
| Consistency | All implementations follow the same patterns |
| Onboarding | New developers/agents learn patterns quickly |
| Maintainability | Update patterns in one place |
| Speed | No repeated exploration for common tasks |
To document a new system (e.g., VioletConnect, MerchantService):
# Create file
touch systems/{system}/architecture-patterns.md
Document:
Template:
---
last_verified: YYYY-MM-DD
verified_against: {System} @ {branch} ({commit})
maintainer: architect
---
# {System} Architecture Patterns
## Pattern 1: {Pattern Name}
### Rule
**{Mandatory requirement}**
### Why
- {Reason 1}
- {Reason 2}
### Implementation
```code example```
## Reference Implementations
| Pattern | Reference File | What It Demonstrates |
|---------|---------------|---------------------|
| ... | ... | ... |
touch systems/{system}/reference-implementations.md
Document:
touch systems/{system}/code-snippets.md
Document:
In CLAUDE.md or system-specific section:
### Reference Documentation
- [Architecture Patterns](systems/{system}/architecture-patterns.md)
- [Reference Implementations](systems/{system}/reference-implementations.md)
- [Code Snippets](systems/{system}/code-snippets.md)
VioletDashboard has all three tiers in prism-brain:
Tier 1: systems/violet-dashboard/architecture-patterns.md
Tier 2: systems/violet-dashboard/reference-implementations.md
pages/api/merchants/[merchantId]/index.ts - CRUD API routesredux/thunks/merchant.ts - Async Redux operationscomponents/Form/MainAppSettings/index.tsx - Form patternsTier 3: systems/violet-dashboard/code-snippets.md
Result: Implementing new features requires ~2k tokens (reading docs) vs 10k+ tokens (exploring code).
All three tier files should include:
---
last_verified: YYYY-MM-DD
verified_against: {System} @ {branch} ({commit or "extracted from live code"})
related_specs:
- product/specs/{feature}/
maintainer: {role}
---
This enables staleness detection and trust signals.
This skill is informational - read it to understand the three-tier system. Then create/update the three files in your brain repo's systems/{system}/ directory.