home / skills / terrylica / cc-skills / adr-code-traceability
This skill helps you embed architecture decision records in code for traceability by applying language-specific ADR patterns and placement guidelines.
npx playbooks add skill terrylica/cc-skills --skill adr-code-traceabilityReview the files below or copy the command above to add this skill to your agents.
---
name: adr-code-traceability
description: Add ADR references to code for traceability. TRIGGERS - ADR traceability, code reference, document decision in code.
---
# 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](./references/language-patterns.md) 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](./references/placement-guidelines.md) for detailed guidance.
---
## Examples
### New File (Python)
```python
"""
Redis cache adapter for session management.
ADR: 2025-12-01-redis-session-cache
"""
class RedisSessionCache:
...
```
### Inline Comment (TypeScript)
```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](./references/language-patterns.md) - Python, TS, Rust, Go patterns
- [Placement Guidelines](./references/placement-guidelines.md) - 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 |
This skill adds Architecture Decision Record (ADR) references into source code to preserve decision traceability between design documents and implementation. It provides language-specific comment and header patterns, a clear placement decision flow, and rules for when to skip adding references. Use it to make architectural rationale discoverable in code without cluttering routine edits.
The skill inspects a code change and determines whether to insert an ADR reference based on file creation status and whether the change is non-obvious. It applies language-specific templates for new-file headers and inline comments (TypeScript, Python, Go, Rust) and derives ADR document paths from a standard ADR ID format. It also enforces exclusions for trivial edits, tests, and well-known patterns to avoid over-documenting.
How should ADR IDs map to document files?
Use the ADR ID as the filename slug (e.g. ADR: 2025-12-01-my-feature → docs/adr/2025-12-01-my-feature.md).
When should I skip adding a reference?
Skip when changes are trivial (formatting, typos), follow standard idioms, or are in test files unless the test approach itself is an ADR decision.