mcpField
A
adr-code-traceability

adr-code-traceability

github.com/terrylica开发2144 次安装今天更新
代码仓库

关于 adr-code-traceability

一项为代码添加 Architecture Decision Record 引用的参考技能，提供引用位置指南及 Python、TypeScript、Rust 和 Go 的模式。它帮助开发者将实现选择关联到相关决策，同时避免为每项改动添加注释。

主要功能

  1. 01按语言提供引用模式
  2. 02文件头与行内注释指南
  3. 03引用位置决策树
  4. 04ADR 注释示例
  5. 05无需添加引用的情况

适用场景

  1. 01将新文件关联到 ADR
  2. 02说明不明显的实现选择
  3. 03实现过程中补充决策背景
  4. 04避免过度添加 ADR 注释

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/terrylica/cc-skills --skill adr-code-traceability

安装后在 Claude Code 中输入/adr-code-traceability确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
evolution-log.md
language-patterns.md
placement-guidelines.md

详细介绍

ADR 代码可追溯性

在代码中添加架构决策记录（ADR）引用，以便追溯决策。提供特定语言的模式和放置指南。

自我演进的技能：此技能会在使用过程中不断改进。如果指令有误、参数发生偏移，或需要采用变通方法，请立即修复此文件，不要延后。仅针对真实且可复现的问题进行更新。

何时使用此技能

  • 作为 ADR 实施的一部分创建新文件
  • 记录不明显的实现选择
  • 用户提到“ADR 可追溯性”“代码引用”或“记录决策”
  • 在 /itp:go 第 1 阶段向代码中添加决策背景

快速参考

引用格式
ADR: {adr-id}

路径推导：ADR: 2025-12-01-my-feature → /docs/adr/2025-12-01-my-feature.md

语言模式（摘要）
语言新文件头部行内注释
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

完整示例请参阅语言模式。

放置决策树

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

详细指南请参阅放置指南。

示例

新文件（Python）
"""
Redis cache adapter for session management.

ADR: 2025-12-01-redis-session-cache
"""

class RedisSessionCache:
    ...
行内注释（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 });

不要为以下情况添加引用

  • 每一行改动（仅在有助于追溯时添加）
  • 微小改动（格式调整、修正错别字）
  • 标准模式（广为人知的惯用写法）
  • 测试文件（除非测试方法是 ADR 中的决策）

参考文档

故障排除

问题原因解决方案
找不到 ADR路径格式错误使用相对于仓库根目录的路径
引用未显示注释语法错误检查对应语言的注释格式
引用过多文档记录过度仅在有助于追溯时添加
ADR 链接已过时ADR 已重命名更新路径，使其与当前 ADR 文件名一致
Hook 提醒很烦人此改动没有 ADR添加行内 ADR 注释或创建新的 ADR

执行后反思

此技能完成后，请在结束前检查：

  1. 命令是否成功？ — 如果没有，请修复导致失败的指令或错误表。
  2. 参数或输出是否发生变化？ — 如果底层工具的接口发生偏移，请更新用法示例和参数表，使其保持一致。
  3. 是否需要采用变通方法？ — 如果你不得不临时调整（使用不同的标志、增加额外步骤），请更新此 SKILL.md，确保下次调用时无需采用相同的变通方法。

仅在问题真实且可复现时进行更新，不要基于猜测更新。

评论

支持 Markdown