skills.rest
terrylica
terrylicaCOMMUNITY
Explore all skills by this author →
GitHub

adr-code-traceability

Add ADR references to code with language-specific comment patterns.

62|10|Updated Dec 4, 2025
Search Tags:#code quality#developer experience#software architecture#ADR#traceability#code documentation#decision log
One-click install
npx skills add https://github.com/terrylica/cc-skills --skill adr-code-traceability
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: adr-code-traceability
Source: https://github.com/terrylica/cc-skills/tree/main/plugins/itp/skills/adr-code-traceability
Command: npx skills add https://github.com/terrylica/cc-skills --skill adr-code-traceability

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Code often lacks context, making it hard for developers to understand the "why" behind non-obvious implementation choices. This skill ensures that architectural decisions are directly traceable from the code, reducing cognitive load and onboarding time.

Core Features & Use Cases

  • Language-Specific Reference Patterns: Provides standardized comment formats for Python, TypeScript, Rust, and Go to link code directly to ADRs.
  • Intelligent Placement Guidelines: Guides on when to add references (new files, non-obvious choices) and when to skip them (trivial changes, standard patterns).
  • Automated Decision Context: Embeds the rationale for critical code sections, making future maintenance and debugging significantly easier.
  • Use Case: When implementing a complex algorithm or a specific architectural pattern, use this skill to add a comment linking to the relevant ADR, allowing any future developer to instantly understand the decision-making process.

Quick Start

Add an ADR reference to the new Python file 'my_feature.py'. The ADR ID is '2025-12-01-my-feature'.

Frequently Asked Questions about adr-code-traceability

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I link code to architectural decisions so developers understand the 'why'?▼

Add ADR references directly to your code using language-specific comment formats. This skill provides standardized patterns for Python, TypeScript, Rust, and Go that embed decision context at the file or implementation level, making the rationale instantly visible to any developer reviewing the code.

What's the best way to document non-obvious implementation choices in code?▼

Reference the relevant ADR using inline or file-header comments tailored to your language. This skill guides placement—add references for complex algorithms and architectural patterns, skip them for trivial changes—ensuring decision traceability without clutter.

Can I automatically trace code back to the decisions that drove it?▼

Yes. This skill embeds ADR references directly into code comments, creating a direct link from implementation to decision. Future developers can instantly navigate from any code section to the architectural decision that justified it.

Does this work with Python, TypeScript, Rust, and Go?▼

Yes. The skill provides language-specific reference patterns and comment formats for all four languages, including file-header and inline-comment guidelines tailored to each language's syntax and conventions.

When should I add ADR references to code?▼

Add references when creating new files as part of an ADR implementation or documenting non-obvious choices. Skip them for standard patterns and trivial changes. The skill includes intelligent placement guidelines to help you decide.

How do I derive the correct ADR path to reference in code?▼

This skill provides ADR path derivation rules for consistent referencing. It ensures you format and locate the ADR ID correctly so links remain valid and traceable across your codebase.

Related Skills

Explore More Software Engineering Skills→
subroh0508subroh0508
18

adr-author

Drafts numbered ADRs and updates the index with cross-links and eligibility checks.

Community
Advanced
rickardprickardp
2

blueprint:validate

Audit codebases for spec, ADR, and pattern compliance with a structured report.

Community
Advanced
hhellbuschhhellbusch
7

cross-link

Detect related documents lacking inbound links and recommend link placements.

Community
Intermediate
volodchenkovvolodchenkov
2

documentation-discipline

Guide developers on documenting code, APIs, and design decisions.

Community
Basic