code-documentation

此技能为软件项目中的技术文档管理提供了强大的框架。专为开发人员、技术写作人员和 AI 代理设计，确保项目文档保持一致、可读且实时。通过遵守结构化模板，用户可以减少入职期间的认知负荷并提高代码库的可维护性。该工具执行“将文档保留在代码附近”的原则，促进更好的开发者体验与更可靠的知识共享。

• 标准化 README 模板，包含快速入门、安装、使用方式、配置表与贡献指南。

• 支持 JSDoc/TSDoc 注释，从源代码生成清晰的 API 参考文档。

• 支持 OpenAPI 与 Swagger 规范，用于记录 RESTful 端点与请求/响应模式。

• 架构决策记录 (ADR) 模板，用于追踪技术决策、背景、原理与影响。

• 行内注释准则，用于区分解释“为什么”（业务逻辑、权宜之计）与“是什么”（显而易见的代码块）。

• 组件级文档标准，用于管理模块、数据流与外部依赖关系。

• 将此技能整合至 CI/CD 管道或开发工作流中，以强制执行微服务或代码库间的一致性。

• 优先编写示例而非详尽的解释，以保持文档的实用性。

• 采用渐进式揭露：为新手提供简洁的 README 快速入门，并链接至更深度的 API 参考以满足资深用户需求。

• 务必将技术文档与实现代码保存在同一个存储库中，以确保更新与功能变更同步。

• 避免冗余注释；专注于捕捉设计意图、HACK、TODO 以及从函数签名中无法直接看出的复杂业务规则。

• 利用基于 Markdown 的 ADR 来维护项目演进的历史记录，这对于长期架构稳定性至关重要。