🇺🇸English
ADR Code Traceability
Add Architecture Decision Record references to code for decision traceability. Provides language-specific patterns and placement guidelines.
When to Use This Skill
- Creating new files as part of an ADR implementation
- Documenting non-obvious implementation choices
- User mentions "ADR traceability", "code reference", "document decision"
- Adding decision context to code during
/itp:go Phase 1
Quick Reference
Reference Format
ADR: {adr-id}
Path Derivation : ADR: 2025-12-01-my-feature → /docs/adr/2025-12-01-my-feature.md
Language Patterns (Summary)
| Language | New File Header | Inline Comment |
|---|
| Python | """...\n\nADR: {adr-id}\n""" | # ADR: {adr-id} - reason |
| TypeScript | /** ... \n * @see ADR: {adr-id} */ | // ADR: {adr-id} - reason |
| Rust | //! ...\n//! ADR: {adr-id} | // ADR: {adr-id} - reason |
| Go | // Package ... \n// ADR: {adr-id} | // ADR: {adr-id} - reason |
See Language Patterns for complete examples.
Placement Decision Tree
Is this a NEW file created by the ADR?
├── Yes → Add reference in file header
└── No → Is the change non-obvious?
├── Yes → Add inline comment with reason
└── No → Skip ADR reference
See Placement Guidelines for detailed guidance.
Examples
New File (Python)
"""
Redis cache adapter for session management.
ADR: 2025-12-01-redis-session-cache
"""
class RedisSessionCache:
...
Inline Comment (TypeScript)
// ADR: 2025-12-01-rate-limiting - Using token bucket over sliding window
// for better burst handling in our use case
const rateLimiter = new TokenBucketLimiter({ rate: 100, burst: 20 });
Do NOT Add References For
- Every line touched (only where traceability adds value)
- Trivial changes (formatting, typo fixes)
- Standard patterns (well-known idioms)
- Test files (unless test approach is an ADR decision)
Reference Documentation
- Language Patterns - Python, TS, Rust, Go patterns
- Placement Guidelines - When and where to add
Troubleshooting
| Issue | Cause | Solution |
|---|
| ADR not found | Wrong path format | Use relative path from repo root |
| Reference not showing | Comment syntax wrong | Check language-specific comment format |
| Too many references | Over-documenting | Only add where traceability adds value |
| Outdated ADR link | ADR was renamed | Update path to match current ADR filename |
| Hook reminder annoying | No ADR for this change | Add inline ADR comment or create new ADR |
Weekly Installs
65
Repository
terrylica/cc-skills
GitHub Stars
24
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode62
gemini-cli61
codex60
cursor59
github-copilot59
amp58
