adr-code-traceability
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseADR Code Traceability
ADR代码可追溯性
Add Architecture Decision Record references to code for decision traceability. Provides language-specific patterns and placement guidelines.
在代码中添加架构决策记录（ADR）引用，以实现决策可追溯性。本文提供了特定语言的模式和放置指南。
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 Phase 1
/itp:go
- 在实现ADR的过程中创建新文件时
- 记录非显而易见的实现选择时
- 用户提及“ADR可追溯性”、“代码引用”、“记录决策”时
- 在第一阶段为代码添加决策上下文时
/itp:go
Quick Reference
快速参考
Reference Format
引用格式
ADR: {adr-id}Path Derivation: →
ADR: 2025-12-01-my-feature/docs/adr/2025-12-01-my-feature.mdADR: {adr-id}路径推导： →
ADR: 2025-12-01-my-feature/docs/adr/2025-12-01-my-feature.mdLanguage Patterns (Summary)
语言模式（摘要）
| Language | New File Header | Inline Comment |
|---|---|---|
| Python | | |
| TypeScript | | |
| Rust | | |
| Go | | |
See Language Patterns for complete examples.
| 语言 | 新文件头部格式 | 行内注释格式 |
|---|---|---|
| Python | | |
| TypeScript | | |
| Rust | | |
| Go | | |
查看语言模式获取完整示例。
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 referenceSee Placement Guidelines for detailed guidance.
这是由ADR创建的新文件吗？
├── 是 → 在文件头部添加引用
└── 否 → 该更改是否非显而易见？
├── 是 → 添加带有原因的行内注释
└── 否 → 跳过ADR引用查看放置指南获取详细说明。
Examples
示例
New File (Python)
新文件（Python）
python
"""
Redis cache adapter for session management.
ADR: 2025-12-01-redis-session-cache
"""
class RedisSessionCache:
...python
"""
Redis cache adapter for session management.
ADR: 2025-12-01-redis-session-cache
"""
class RedisSessionCache:
...Inline Comment (TypeScript)
行内注释（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 });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)
- 每一行修改都添加（仅在可追溯性能带来价值时添加）
- 微小更改（格式调整、拼写修正）
- 标准模式（众所周知的惯用写法）
- 测试文件（除非测试方法是ADR决策的一部分）
Reference Documentation
参考文档
- Language Patterns - Python, TS, Rust, Go patterns
- Placement Guidelines - When and where to add
- 语言模式 - Python、TS、Rust、Go模式
- 放置指南 - 添加的时机和位置
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 |
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 找不到ADR | 路径格式错误 | 使用相对于仓库根目录的路径 |
| 引用未显示 | 注释语法错误 | 检查特定语言的注释格式 |
| 引用过多 | 过度文档化 | 仅在可追溯性能带来价值时添加 |
| ADR链接过时 | ADR已重命名 | 更新路径以匹配当前ADR文件名 |
| Hook提醒烦人 | 此更改没有对应的ADR | 添加行内ADR注释或创建新的ADR |