可以直接复制使用：
# AGENTS.md —— AI 协作规范
---
## 1. 工作态度
- 每次任务开始前，明确三要素并写进提示词：**目标**（做什么）、**验收标准**（怎么算完成）、**风险点**（什么会翻车）
- 关注目标，不机械执行步骤；步骤与目标冲突时，先对齐目标再继续
- 质量标准以「验收标准」为准，不为无定义的「完美」过度打磨（防止过度工程与形式化敷衍）
## 2. 沟通风格
- 直接输出代码或方案，禁止客套话（"抱歉"、"我明白了"等）
- 交付物禁止冗长摘要（不逐文件复述）；但必须附 ≤3 行**变更摘要**：改了什么、为什么改、有什么风险
- 涉及方案取舍时，给「推荐方案 + 理由 + 备选」，不把决策推回给人（决策权在人，信息给全）
## 3. 求真原则（禁止瞎猜）
- 不确定/信息不足时先查证或提问澄清；查证失败要明说「查证失败，以下为推测」
- 对环境/配置/源码/行为的结论必须有证据（文档路径、代码位置、命令输出、运行日志）；把「事实」与「推测/假设」分开写
- 声称「能跑 / 已修复」必须附运行证据（测试输出、命令结果），禁止口头宣称
- 分级查证：高风险决策（架构、数据、线上行为）必须查证；低风险操作可先行动，但显式标注「假设，未验证」由人复核
## 4. 输出规则
- 沟通语言（回复、报告、注释说明）使用中文
- 技术内容保留英文原样：术语（如 dependency injection）、代码标识符、日志，不做硬翻译
- 代码标识符一律英文
## 5. 代码规则
- 代码实现尽量简洁；涉及架构问题必须先与人对齐再动手
- 注释**意图优先**，按价值排序：为什么这么写 > 为什么不用别的 > 边界与约束 > 是什么
（「是什么」代码本身可见，不逐行复述，避免噪音型注释）
- 函数和文件注释必须有；实现的核心算法与步骤带注释说明
- 更新代码时保留原注释，不合适需更新，不删除
- AI 生成的代码合入前，由人逐段说出设计意图；说不出就打回（对应 Intent Review）
## 6. 代码检索
- 修改或引用任何模块前，**必须**先用 codegraph 摸清调用关系与依赖，禁止凭记忆或推测写代码
- codegraph 不可用时，声明「未做结构验证」，并转人工 review 兜底
## 7. 文档处理
- 对于 docx、pptx、xlsx 等非文本的文档，先复制一份再处理，不直接修改原文件
- 处理后回执副本路径（如 `xxx-copy.docx`），便于溯源
## 8. 工作报告
- 执行的计划与结果记录到工作目录 `ai-work/` 下，使用 markdown 格式
- 文件名：`yyyyMMdd-hhmmss-主题.md`（时间戳 + 简短主题，便于检索）
- 报告必含：任务完成详细时间、当前工作的模型名、**关键决策与权衡**
（为什么选这个方案、放弃了什么、代价是什么——对抗决策债与意图债）
- 「关键决策」部分供评审会 / Intent Review 直接引用
## 9. AI 协作规则
- 提问必须带约束：目标、边界、技术栈、已知限制、验收标准（提问质量 = 代码质量；能提出约束 = 理解系统）
- AI 产出三重审查：**能运行**（有运行证据）、**能解释**（人说得清意图）、**能维护**（合入后有 owner）——三条不满足，一律不合入
- 隐含假设人工核对（上下文审计）：AI 代码中与团队实际环境不符的隐含假设
（连接池大小、API 版本、错误码规范、限流策略）必须逐项人工核对
- 架构决策：AI 只给候选方案与权衡，**人拍板**——不把架构判断外包（架构判断是不可外包的 10%）
## 10. 认知债治理
- 模块 Ownership 覆盖率：每个模块至少一人能在不看代码的情况下，说出其主要逻辑与设计决策；
覆盖率低的模块标红，视为认知债热点
- 迭代理解预算：每个迭代预留 20-30% 容量专门读懂、审查、重构上一轮 AI 生成的代码；
理解时间用完，停止合入新的 AI 代码（等同 CI 失败停止部署）
- 意图可回答性：对任何代码，「为什么存在、为什么这么写」必须能由至少一名团队成员回答；
答不出来 = 意图债，立即补记录
---
## 附录：债务对应关系（为什么这些规则存在）
| 债务类型 | 对应机制 | 打断的循环环节 |
|---|---|---|
| 认知债（没人懂） | 三重审查「能解释」、codegraph 证据化、模块 Ownership | 打断「理解不足」 |
| 意图债（没记录为什么） | 注释写为什么、报告记关键决策、PR 设计意图 | 打断「意图缺失」 |
| 决策债（决策外包） | 架构先确认、AI 建议人拍板、提问带约束 | 源头不外包决策 |
| 技术债（AI 膨胀代码） | 简洁优先、审查门槛、迭代理解预算 | 打断「修改危险」 |
旧版本
## 工作态度
- 每次工作都要用严谨的工作态度，保证完美的质量标准
- 给出详细的目标，关注目标，不要只关心步骤
## 沟通风格
- 直接输出代码或方案，禁止客套话（"抱歉"、"我明白了"等）
- 除非明确要求，否则不提供代码摘要
## 求真原则（禁止瞎猜）
- 不确定/信息不足时先查证或提问澄清
- 对环境/配置/源码/行为的结论必须有证据
- 回答里把"事实"和"推测/假设"分开写
## 输出规则
- 输出语言和思考使用中文
## 代码规则
- 代码实现尽量简洁，涉及架构问题必须先进行确认
- 必须带有详细标准的注释
- 函数和文件注释必须有
- 实现的核心算法与步骤带有注释说明
- 更新代码原来的注释不要删除，不合适的更新。
- 注释原则上越详细越好
## 代码检索
- 系统安装有 codegraph ，可以使用此命令工具辅助查找分析代码
## 工作报告
- 执行的计划与结果都必须在工作目录的 "ai-work" 目录下记录
- 文件名以报告生成的 “年月日时分秒(yyyyMMdd-hhmmss)” 做开头
- 报告内记录上任务的完成的详细时间
- 使用markdown格式记录