用途:为 Python、TypeScript/JavaScript、C#/.NET 代码库提供统一的编码规范与文档标准,适用于编写新代码文件或函数时参照。
主要能力:
- 双层文档:每个非平凡代码元素需包含外部注释/头(定义上方可快速浏览的说明)与内部 docstring(定义内部的详细文档)。
- 文件头:每个源文件以描述其用途的头部开始。Python 使用特定格式的文档字符串,含 Purpose、Layer、Usage、Related;plugins/ 中的 CLI 工具使用扩展格式(含 Usage Examples、CLI Arguments、Key Functions、Script Dependencies),完整黄金模板见 references/header_templates.md。TypeScript/JavaScript 与 C#/.NET 各有对应头部格式。
- 函数文档:Python 使用 Google 风格 docstring 加类型提示(Args/Returns/Raises);TypeScript 使用 JSDoc(@param、@returns、@throws);C# 使用 XML 文档注释。
- 命名约定:Python 函数/变量 snake_case、类 PascalCase、常量 UPPER_SNAKE_CASE;TS/JS 函数/变量 camelCase、类 PascalCase、常量 UPPER_SNAKE_CASE;C# 公共成员 PascalCase,私有字段用 _camelCase 前缀。
- 代码质量阈值:函数超过 50 行提取辅助函数;嵌套 3 层以上重构;注释解释为什么而非做什么;TODO 格式为 // TODO(#123): description。
- Python 模块组织:按 init.py、models.py、services.py、repositories.py、utils.py、constants.py 划分。
- 工具清单集成:plugins/ 中所有 Python 脚本须登记到 plugins/tool_inventory.json,新增或修改后运行 python plugins/tool-inventory/scripts/manage_tool_inventory.py add --path "plugins/path/to/script.py" 与 python plugins/tool-inventory/scripts/manage_tool_inventory.py audit。
- 预提交检查清单:文件有正确头部、脚本已登记、audit 显示 0 个未跟踪脚本。
- 清单模式(ADR 097):.agent/learning/ 清单使用含 title、description、files(每项含 path、note)的简单模式。
使用方式:在编写或修改代码时按对应语言套用上述规范;创建或修改工具脚本后运行登记与审计命令。
限制:资料未提供安装步骤、收费、价格与平台信息。