Documentation Linking
该技能用于在代码与文档之间创建并维护双向链接，服务于 AI 辅助开发流程。
用途
- 代码 → 文档：在代码注释中引用相关文档，例如架构说明、API 规范、决策记录、端点说明等。
- 文档 → 代码：在文档中标注实现该内容的代码文件、行号范围、测试与配置文件。
主要能力
链接格式
- 绝对链接：从仓库根目录开始的完整路径（
@doc /docs/database/migrations.md#schema-versioning）。 - 相对链接：相对当前文件的路径（
@doc ../../../docs/api/rest-endpoints.md#user-endpoints）。 - 行号链接：指向具体行区间（
@impl service/user_service.go:145-178）。 - 锚点链接：指向文档中的具体小节（
@doc architecture.md#data-flow-diagram）。
支持的文档类型
- 架构文档（
@arch-doc、组件图、时序图） - API 文档（
@api-doc、@openapi-spec、请求/响应示例） - 决策记录（
@decision-record，含决策、理由、日期） - 测试文档（
@test-doc、@test-data、@test-cases） - 运行手册（
@runbook、@monitoring、@alerts） - 交叉引用（Issue、PR、Jira、Wiki、Confluence）
- 外部资源（RFC、规范、教程）
- README、示例代码、教程链接
同步与维护策略
- 自动链接校验脚本：提取代码中的
@doc引用，检查目标文件是否存在，报告失效链接。 - 文档覆盖率统计：统计包含
@doc/@api-doc注解的源文件比例。 - 反向链接追踪：在文档中自动生成“被以下代码引用”清单。
- Git 预提交钩子：在提交前检查失效的文档链接并阻止提交。
- 链接弃用标记：用
[DEPRECATED]标注旧链接并指向新文档。 - 版本化文档：引用特定版本文档（
@doc-version 2.3.0）。
集成示例
- Markdown 文档中的实现文件与测试文件链接
- OpenAPI/Swagger 中标注处理程序、校验器、数据库层与相关文档
- JSDoc/TypeDoc 中使用
@see与@example引用文档和示例
反模式
避免脆弱的深层相对链接、链接到过时文档、形成循环文档依赖。推荐使用仓库相对路径、保持链接为最新状态、建立清晰的导航层级。
使用方式
该技能以注释注解和文档标记的形式应用于代码与文档中，并通过配套脚本、Git 钩子和自动生成机制进行校验与维护。具体安装与集成步骤在提供的资料中暂未说明。
适用场景
适用于需要在代码与文档之间保持上下文一致、提升可追溯性的开发项目，尤其适合有架构文档、API 规范、决策记录与运行手册的工程团队。
限制
资料未提供具体的安装命令、支持的平台与运行环境要求，也未提供收费或定价信息。