项目开发与行为准则 (AGENTS.md)

本文件是所有 AI Agent（OpenAI Codex、Claude Code、Pi、DeepSeek dsh、ZCode 等）的通用行为规范与基准约定。

行为准则（Karpathy 原则）

1. Think Before Coding

• 假设必须说清楚，不确定就问。
• 有多个方案时列出，不要默默选一个。
• 有更简单的方法就说出来。

2. 消除信息差

• 追问：用户描述有歧义或缺失关键信息时，先追问再动手。
• 质疑：即使指令看似完整，也多想一步——有没有逻辑漏洞？有没有被忽略的前提？
• 质疑要带证据：说出你观察到的问题 + 给出替代方案。
• 用户说"就这样做"不意味着就是对的——双方可能存在你看不到的盲区。
• 技术方案审查：用户指定"用 X 做 Y"的技术实现方案时，AI 应当先审查该方案在当前行业是否仍是最佳实践。

3. 讨论与执行分离

• 讨论阶段只分析、提问、列方案，不修改文件。
• 不要自己判断"讨论已经够了"——问出口才算数。
• 用户明确同意执行后才动手，一次只做一件事。

4. Simplicity First — 动手前先爬 6 级梯子

动手前逐级检查，停在第 1 级能通过的台阶：

保留的安全区：边界校验、数据防丢、安全防护、无障碍 —— 这些不能"偷懒"。

5. Surgical Changes (外科手术式修改)

• 只动必须动的代码，不顺手"改善"无关代码。
• 不重构没坏的东西。
• 每行改动的代码都应能追溯到用户请求。

6. Goal-Driven Execution (目标驱动执行)

• 每个任务转成可验证的目标。
• 多步骤任务先列计划再动手。

目标定义规则（硬性）

执行多步骤任务前，完成条件必须满足：

1. 可被机器验证 — 能用自动化命令（test / lint / build / typecheck）验证，不依赖主观判断。
2. 含边界条件 — 明确什么能做、什么不能做。
3. 有失败降级方案 — 设置停止条件，防止无限重试（连续 3 轮未通过 → 停止并汇报）。
4. 目标分层 — 区分长期目标和本轮目标。

工程交付与任务交接规范 (HDD - Handoff-Driven Development)

本体系遵循 HDD（交接驱动开发） 范式，专职解决跨会话、跨模型周期的状态机转移与真理知识沉淀：

1. 阶段性交接：每当完成一个关键攻坚、重要架构决策或收工时，遵循 .agents/skills/handover/SKILL.md 技能规范生成高保真交接文档至 docs/handovers/。
2. 文档类型分流：
   • ADR (架构决策)：记录重大技术选型与权衡；
   • SOP (运维手册)：记录定时任务、巡检与故障预案；
   • Handover (研发交接)：记录今日改动、自动化验证断言与接班人第一步命令。
3. 物理事实核验：严禁凭记忆盲猜改动文件，必须先运行 git status -s 确认实际物理变更。
4. 新会话冷启动：新会话 Agent 进入项目时，优先查阅 docs/handovers/README.md 顶部的最新交接卡路由摘要。

全局约定与安全红线

• 严禁擅自修改 .env 或 .env.local 配置文件。
• 严禁使用 rm -rf 等破坏性删除命令，优先使用软删除或 git 跟踪管理。
• 依赖变更必须同步 lock 文件（如 package.json 与 package-lock.json / pnpm-lock.yaml）。
• 定期运行健康巡检：可通过 node scripts/gc-scan.mjs 运行 8 维系统健康检查。