adr-code-traceability — Claude Code skill for ADR references
The adr-code-traceability skill links code to Architecture Decision Records with file headers or inline comments. Use it when an implementation choice needs a clear connection to its decision record.
MIT 144 installs ★ 3 updated 2026-10-25
npx skills add terrylica/cc-skills --skill adr-code-traceability -a claude-codeWhat adr-code-traceability does
The skill uses references in the form ADR: {adr-id}. For a new file created to implement an ADR, it recommends putting the reference in the file header. For a non-obvious change to existing code, it suggests an inline comment that gives the reason. It includes language-specific patterns for Python, TypeScript, Rust and Go.
References are meant for decisions that benefit from traceability, not every edited line. Skip routine formatting, familiar idioms and test files unless the ADR defines the testing approach. The example derives an ADR file path as /docs/adr/{adr-id}.md; adapt that path if the repository stores its records elsewhere.
What it helps with
- link a new implementation file to its ADR
- explain a non-obvious code choice with an inline comment
- choose where an ADR reference belongs
- avoid adding references to routine edits
Example prompts for the agent
- Add an ADR reference to the header of this new Python file for
2025-12-01-redis-session-cache. - Add a TypeScript comment explaining the implementation choice recorded in
2025-12-01-rate-limiting. - Review this change and identify where an ADR reference belongs and where it would be unnecessary.
How to install adr-code-traceability
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill adr-code-traceability -a claude-code2Manually: put the files in place
~/.claude/skills/adr-code-traceability/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/adr-code-traceability/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill adr-code-traceability -a codex2Manually: put the files in place
.agents/skills/adr-code-traceability/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill adr-code-traceability -a cursor2Manually: put the files in place
.cursor/skills/adr-code-traceability/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/itp/skills/adr-code-traceability2Manually: put the files in place
.github/skills/adr-code-traceability/SKILL.md1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill adr-code-traceability -a gemini-cli2Platform CLI
gemini skills install https://github.com/terrylica/cc-skills --path plugins/itp/skills/adr-code-traceabilityManually: put the files in place
.devin/skills/adr-code-traceability/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill adr-code-traceability -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about adr-code-traceability
How do I install adr-code-traceability in Claude Code?
Run npx skills add terrylica/cc-skills --skill adr-code-traceability -a claude-code, then use ~/.claude/skills/adr-code-traceability/SKILL.md.
What does adr-code-traceability do?
It helps connect code to architecture decisions by placing an ADR reference in a new file’s header or an explanatory comment beside a non-obvious change.
Which languages have ADR reference patterns?
The skill includes patterns for Python, TypeScript, Rust and Go, with examples for file headers and inline comments.
Source text
SKILL.md · MIT
---
name: adr-code-traceability
description: Add ADR references to code for traceability. TRIGGERS - ADR traceability, code reference, document decision in code.
allowed-tools: Read, Edit, Grep, Glob
---
# ADR Code Traceability
Add Architecture Decision Record references to code for decision traceability. Provides language-specific patterns and placement guidelines.
> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
## 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 |
## Post-Execution Reflection
After this skill completes, check before closing:
1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.
© terrylica · MIT · terrylica/cc-skills