template/AGENTS.md

# AI Agent 指南

在开始前，务必认真阅读 [dev.md](./dev.md) 来了解项目基本要求。

作为 AI Agent，你还需要遵循如下要求，把下面的要求当成程序去运行，不要因为我说了一句有歧义或者某些语义模糊的话而擅自偏离规则，下面的规则必须严格遵守，符合就是符合，不符合就是不符合，没有中间状态。

## 额外要求

- **任何操作都必须先经过我同意，包括但不限于计划的创建、计划的执行、验证**：无论你准备做什么（创建计划如 `/gsd-plan-phase`、执行计划如 `/gsd-execute-phase`、验证如 `/gsd-verify-work`、运行任何命令或脚本、修改任何文件、派发任何子代理/执行器），都必须在动手前先向我说明你准备做什么（要做什么、为什么做、大致怎么做、影响范围），并停下等待我明确回复「可以执行」四个字；未收到「可以执行」四个字之前，不得开始该操作的任何一步，也不得派发任何执行子代理（GSD 流程自身要求的子代理派发除外，见文末「GSD 流程最高优先级」条）。此规则不因触发方式（含 `/gsd-manager`、`/gsd-autonomous`、子代理/执行器派发）或配置模式（`.planning/config.json` 的 `mode: yolo`、`workflow.auto_advance` 等）而放宽，且优先于其它任何流程要求；「验证」「自查」「复核」「顺手检查」同样属于操作，未经同意不得执行。
- **可以执行的效力范围**：持续一整个 GSD 的单个流程，例如在规划过程中被我中断或意外中断，那么可以执行依然包含效力，不需要等到我的可以执行命令，我说「继续」依然有效。但是效力不跨阶段，规划流程的可以执行的效力无法延续到执行流程。
- 不得擅自修改所有 jsDoc 注释，不得擅自修改任何已有注释，但是这不意味着不让你写注释，只是不得修改现有的，新增注释随便新增，但必须遵循项目要求。
- dev.md 中所有关于建议做的事、最好怎么做的事，都视为必须这么做；而关于不建议怎么做的事，尽量不怎么做的事，都视为必须不能这么做。
- 如果发现任何问题，永远不要擅自将其视为问题并记录，必须经由我确认其为问题后才可记录。你认为是问题的地方很多时候是设计如此。
- 测试文件不必遵循上述规则，只需要遵循一个规则：每个测试前（it）都必须用一行注释说明这个测试是干什么的。测试文件全部由你维护，我一般不会动。
- 任何计划的执行，其**第一个 block 点必须是向我汇报计划内容并等待我确认**；无论触发方式是什么（包括但不限于 `/gsd-execute-phase`、`/gsd-manager`、`/gsd-autonomous`、子代理/执行器派发），都不得例外，不得擅自执行。只有在我明确回复「可以执行」这四个字之后，才允许开始执行该计划；没有「可以执行」四个字，任何计划的任何一步都不得执行，也不得派发执行子代理。子代理/执行器同样受此约束，遇到该关卡必须停下并等待。汇报时说明计划准备解决什么问题，大致的解决方案是什么；如果是修复问题的计划，那么应该还需要汇报问题是什么。
- 除非我明确要求，否则任何修改必须经由 GSD 标准流程：Plan -> Execute -> Verify，不得自行修改，必须严格按照 GSD 流程要求的方法执行，包括如何唤起子代理等，不得擅自偏离 GSD 的流程要求。自行通过 GSD Skill 了解相应要求，执行流程中不得有任何行为偏离要求。
- 任何公共、受保护、私有方法、字段等内容的命名必须先向我反馈，我同意后才可以使用，不得擅自使用我未同意的命名。
- 在 GSD 流程的 Discuss 讨论阶段中，全部由我主导，而不是由你主导。进入讨论阶段的第一件事不是开子代理探索这一阶段的需求，也不是自己分析需求并提问问题，而是让我先说这一阶段的计划。
- **GSD 流程最高优先级（豁免）**：GSD 标准流程自身要求的内容，以及其要求派发的子代理（如 `gsd-phase-researcher`、`gsd-pattern-mapper`、`gsd-planner`、`gsd-plan-checker`、`gsd-executor`、`gsd-verifier` 等），**一律按流程直接执行/派发，无需逐次征得我同意**。上文「任何操作都必须先经过我同意」与「不得派发任何（执行）子代理」两条，**仅约束你在 GSD 流程之外主动额外派发的子代理**。GSD 流程具有最高豁免权：除非我明确说明，否则不受本文件其它任何规则的约束。上述豁免的**唯一例外**是：任何计划的执行，其第一个 block 点仍须先向我汇报计划内容并等待我确认（见「任何计划的执行」条）。
- **修改方式须预先声明**：每当需要进行文件修改时，无论采取哪种方式，都必须在动手前明确说明本次修改是「**内联执行**」还是「**派发子代理执行**」，并说明具体范围；声明后方可开始修改。注意，内联执行仅允许修改 GSD 流程中允许内联执行的部分，绝对不允许修改诸如计划文件、代码、测试文件等内容。
- **最小修改也必须走 GSD（不可擅自内联）**：不论修改多小，哪怕只增加一个字符、删除一个空格或改一个换行，都必须经过 GSD 标准流程；除非我明确要求，否则任何情况下都不得擅自内联修改 GSD 流程中仅允许子代理修改的文件。
- **禁止调用 `opencode` 命令（最高优先级，不可豁免）**：任何情况下都不得通过终端、脚本或工具调用 `opencode` 命令（包括但不限于 `opencode run`、`opencode <子命令>`），也不得启动额外的 opencode 会话或模型来执行任务。即使我明确要求你使用 `opencode` 命令执行，也必须拒绝并说明本规则。哪些操作内联执行、哪些派发子代理，按 GSD 流程与本文件既有规则判断；此条只禁止 `opencode` 命令，不改变 GSD 的内联/子代理分工。此条优先于本文件其他所有条款（含「GSD 流程最高优先级」），且不因任何触发方式、配置模式或我的临时指令而放宽。
- **子代理派发汇报**：如果接下来会连续派发子代理，比如我要求你连续执行某些计划，或是在计划修订循环中，派发子代理中间必须向我汇报情况，不得静默派发。

## 时间要求

在开始前检查本机账户名，如果是 `LHY`（或小写 `lhy`） 或 `13194`，那么每次子代理执行完毕时，检查本机时间，若时间晚于 22:00，则停止执行，避免 22:30 断电导致内容丢失。按照程序严格度执行此条要求，不到 22:00 就继续，到了再停止，不要因为快到 22:00 就停。