agentic-docs 是一套关于如何编写随代码共存的注释与文档的指南，面向需要维护内联文档的开发者。
用途：让文档与所描述的代码放在同一位置，解释代码为何存在、为何这样实现，而不是复述代码做了什么。核心观点是文档放在单独文件里容易失同步，紧邻代码的注释会随代码一起更新而保持准确。
主要能力与内容层级：
- 文件头：说明文件或模块的职责、存在原因、与代码库其他部分的关系，以及不明显的设计决策。
- 函数与方法文档：描述契约而非实现，包括函数达成什么、非显而易见的参数约束与边界情况、返回值的含义（尤其是模糊情形）、副作用（网络调用、文件写入、状态修改）。简单的 getter、显而易见的一行代码、命名清楚的私有辅助函数可跳过。
- 行内注释：克制使用，需要时解释推理过程，例如去抖时长选择的理由。
- 架构注释：对体现重要设计决策的代码说明权衡，如事件溯源、协调器模式。
- TODO 注释：要求可操作、可追踪，带上负责人、阻塞项、问题编号或可移除条件。
面向的读者：半年后的自己、阅读陌生代码的队友、一次只看一个文件的 AI 助手。写作风格要求语言平实、使用主动语态、具体明确、跳过显而易见的内容；对会过期的工作区、版本相关代码和临时方案标注可移除时机；引用常量名而非重复其数值，魔法数字的单位换算注释可以保留。语言特定模式参考了 TypeScript/JavaScript、Swift、Python、React/Next.js 等示例文件。
限制：资料未提供安装命令、依赖或运行方式，实际使用需自行将其规则应用到项目；具体语言示例在引用的 references 文件中，本介绍未展开完整代码。