Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill adr-code-traceability -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/adr-code-traceability/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/adr-code-traceability/

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

Similar skills

SKILL.md skills catalog →

From the same set79

The whole set →
plotext-financial-chart plotext-financial-chart builds pure text financial line charts for Markdown files using plotext. It helps display price paths directly in GitHub documentation without external images. CX Codex +1 146installs latex-setup The latex-setup skill sets up and verifies LaTeX on macOS, then configures Skim and SyncTeX. It supports Mac preparation and TeX package troubleshooting. CX Codex +1 146installs adaptive-wfo-epoch adaptive-wfo-epoch sets how many epochs to train on each walk-forward fold, ranking candidates by walk-forward efficiency rather than one fixed number for the whole run. CX Codex +1 146installs log-reader log-reader reads MetaTrader 5 log files and Print() output straight from UTF-16LE daily logs without checking the Experts tab manually. CX Codex +1 145installs mlflow-python mlflow-python is a Claude Code skill for logging backtest parameters and metrics in MLflow, searching experiment runs, and retrieving metric history via the Python API. CX Codex +1 139installs code-clone-assistant code-clone-assistant detects duplicate code using PMD CPD and Semgrep, guides refactoring of DRY violations. Catches both exact clones and similar patterns. CX Codex +1 139installs article-extractor article-extractor downloads technical articles and documentation from mql5.com for reference or training datasets. Useful for collecting MQL5 code examples by URL or author. CX Codex +1 138installs glossary-management glossary-management is a Claude Code skill that maintains a terminology glossary and connects it to Vale. It runs for glossary edits, term additions, validation, and sync requests. CX Codex +1 138installs

Project sponsors

Companies that keep this analytics open