# AGENT_RULES

目的：为本仓库提供稳定的执行流程与行为规范。

## 优先级

1. 系统/开发者指令与安全约束
2. 项目私有规则：`AGENT_RULES.local.md`（如存在）
3. 仓库规则：`.agents/` 与 `AGENTS.md`
4. 本文件

## 安全与沟通

### 安全红线

- 不得在代码、日志或注释中写入明文密钥、密码、Token
- 修改鉴权、权限或敏感数据流时，必须说明动机与风险
- 不确定是否敏感时，一律按敏感信息处理
- 执行会修改文件系统的命令前，必须说明目的与潜在影响

### 沟通原则

- 统一使用简体中文
- 专业、直接、简洁，避免对话填充词
- 发现用户理解有误时，礼貌纠正
- 无法满足请求时，简洁说明原因并提供替代方案
- 不给时间估算，专注事实、风险与下一步
- 代码块必须标注语言类型
- 不使用 emoji，除非用户明确要求

## 工作原则

- 模仿项目现有风格，先看周围代码、配置和测试再动手
- 不假设库、框架或命令可用，先验证再使用
- 完整覆盖用户请求，不遗漏边界条件和收尾工作
- 技术准确性优先于迎合；不确定时先调查再回答
- 只做当前任务需要的改动，不顺手加功能、不顺手重构
- 不为一次性操作增加抽象，不为假设的未来需求设计

## 会话启动

每次新会话开始时，按顺序加载以下上下文：

1. `AGENT_RULES.local.md`：项目私有规则（如存在）
2. `.agents/index.md`：语言规则与工具入口（如存在）
3. `memory-bank/project-brief.md`：项目定位、边界、约束
4. `memory-bank/tech-context.md`：技术上下文、工具链、验证命令
5. `memory-bank/system-patterns.md`：系统模式、边界与不变量
6. `memory-bank/active-context.md`：当前目标、最近变更、下一步
7. `memory-bank/decisions.md`：重要决策记录（如存在）
8. `memory-bank/progress.md`：执行进度与 Plan 状态（如存在）
9. `docs/superpowers/specs/`：最新设计稿（如存在）
10. `docs/superpowers/plans/`：相关实施计划（如存在）

目的：快速建立项目全貌，避免重复解释和重复试错。

## 规划与执行模型

- 头脑风暴使用 `$brainstorming`，产出
  `docs/superpowers/specs/*-design.md`
- 实施计划使用 `$writing-plans`，产出
  `docs/superpowers/plans/*.md`
- Plan 生命周期由 `main_loop.py` 协调，并通过
  `memory-bank/progress.md` 留痕
- 默认执行器是 `$executing-plans`
- 代码类执行必须同时遵循：
  `karpathy-guidelines`、`.agents/`、`AGENT_RULES.md`

重要约束：

- 规划阶段必须走 `using-superpowers -> brainstorming -> writing-plans`
- `brainstorming` 写出 spec 后，立即用 `playbook.py -record-spec`
  记录 `phase=planning` 与 `spec=<path>`
- `writing-plans` 写出 plan 后，立即用 `playbook.py -record-plan`
  记录 `plan=<path>`、`executor=executing-plans`、
  `constraints=karpathy-guidelines,.agents,AGENT_RULES`
- 未领取 Plan 前，不得直接进入 `$executing-plans`
- 已领取 Plan 后，默认执行使用 `$executing-plans`
- `$subagent-driven-development` 仅在 Plan 或平台明确要求时使用，
  不是默认执行器
- 执行完成后，必须先运行 `main_loop.py finish` 写回状态，
  再更新 `progress.md` 上半部分摘要

### Plan 要求

- `Plan Meta` 必填，位于 Plan 头部 `---` 之后、Task 1 之前
- `Plan Meta` 至少包含：
  - `Plan Group`
  - `Parent Plan`
  - `Verification Scope`
  - `Verification Gate`
- Plan 中不得包含必然失败或依赖未确认的信息
- 未确认项必须在 `$brainstorming` 阶段解决后，才能产出 Plan
- Plan 内验证必须是当前阶段可通过的局部验证
- 需要集成验证的内容，放入上层或集成 Plan
- Plan 生成完成后，执行入口只能是主循环
- 代码类 Plan 应显式声明执行约束：
  `karpathy-guidelines`、`.agents/`、`AGENT_RULES.md`
- 不因等待确认而中断可执行步骤；待确认事项写入回复
- 每个 Plan 应小步、可验证、可快速完成

## 主循环执行契约

### 触发方式

- 常规模式：`执行主循环`、`继续执行`、`下一个 Plan`
- 无交互模式：`自动执行所有 Plan`

### Plan 状态

- `pending`：待执行
- `in-progress`：执行中，用于恢复中断任务
- `done`：已完成
- `blocked`：阻塞，需人工介入或切换环境
- `skipped`：永久跳过，不再执行

`skipped` 如需恢复，必须手动改回 `pending`。

### 环境阻塞格式

- 格式：`env:<环境>:<Task列表>`
- 示例：`env:windows:Task2,Task4`
- `Task` 列表必须使用英文逗号分隔，且不要包含空格

### 领取与写回

领取命令：

```bash
python {{PLAYBOOK_SCRIPTS}}/main_loop.py claim \
  -plans docs/superpowers/plans \
  -progress memory-bank/progress.md
```

该命令会在锁保护下串行完成三件事：

- 自动识别当前环境：`windows`、`linux`、`darwin`
- 按顺序选择可执行 Plan：
  `in-progress` > `pending` > `blocked: env:<当前环境>:...`
- 将选中的 Plan 写成 `in-progress`

这里的锁保护的是 `progress.md` 状态块更新，避免多个 session
同时读写时发生覆盖。

stdout 必须包含：

- `PLAN=<path>`
- 如为环境恢复，还会附带 `NOTE=env:<环境>:<Task列表>`

规划与执行留痕示例：

```bash
# brainstorming 完成后
python {{PLAYBOOK_SCRIPTS}}/playbook.py \
  -record-spec docs/superpowers/specs/<topic>-design.md \
  -progress memory-bank/progress.md
```

```bash
# writing-plans 完成后
python {{PLAYBOOK_SCRIPTS}}/playbook.py \
  -record-plan docs/superpowers/plans/<topic>.md \
  -progress memory-bank/progress.md
```

写回命令示例：

```bash
python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
  -plan <plan> \
  -status done \
  -progress memory-bank/progress.md
```

```bash
python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
  -plan <plan> \
  -status blocked \
  -progress memory-bank/progress.md \
  -note "env:<所需环境>:<Task列表>"
```

```bash
python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
  -plan <plan> \
  -status blocked|skipped \
  -progress memory-bank/progress.md \
  -note "<原因>"
```

### Plan 场景下的分支与隔离策略

- 本节仅适用于通过主循环领取并执行 Plan 的场景
- 默认允许在当前分支直接执行 Plan，包括 `main` / `master`
- 不强制为 Plan 执行创建隔离工作区、临时分支或 `git worktree`
- 仅在以下场景使用隔离工作区：
  - 用户明确要求隔离执行
  - Plan 文本自身明确要求隔离执行
  - 当前任务需要并行隔离以避免相互影响
- 如外部技能、工具或默认流程要求先隔离，再执行 Plan，以本文件和用户当前指令为准

### 执行规则

1. 先 `claim`，拿到 `PLAN=` 后再读取 Plan 内容
2. 如返回 `NOTE=env:...`，本轮只执行列出的 Task
3. 默认执行器是 `$executing-plans`；代码类任务在执行前必须显式
   加载 `karpathy-guidelines`
4. 执行时同时遵循 `.agents/`、`AGENT_RULES.md` 和 Plan 本身；
   如发生冲突，以优先级更高的规则为准
5. 按顺序执行 Task，并完成 Plan 约定的验证
6. 环境不匹配时，记录所需环境和 Task，继续处理本 Plan
   其余可执行 Task
7. 其他阻塞写回 `blocked`；永久放弃写回 `skipped`
8. 触碰安全红线时立即停止，不继续后续 Plan
9. 常规模式下可对高风险事项向用户确认；无交互模式按本文件
   的“需要确认的场景”自动处理
10. 每次 `claim` 只领取一个 Plan；写回后再领取下一个
11. 全部 Plan 处理完后，统一汇总完成项、阻塞项、跳过项、
    环境需求与待确认事项

## 通用执行约束

### 代码与配置修改

- 必须先读文件再修改
- 遵循 `.agents/`、项目代码风格和现有命名约定
- 只改必要部分，不顺手重构无关内容
- 执行与改动相称的验证；如有相关测试且未被豁免，必须通过
- 遵循 `.gitattributes` 等换行与文件格式规则

### 决策与留痕

- 重要决策记录到 `memory-bank/decisions.md`
- 待确认事项在回复中显式列出
- `workflow-state` 和 `plan-status` 只能通过
  `{{PLAYBOOK_SCRIPTS}}/main_loop.py` 维护
- `progress.md` 上半部分的人类摘要在阶段变化或执行结束后同步更新
- 同一错误重复两次以上时，立即更新
  `AGENT_RULES.local.md` 或 `memory-bank/decisions.md`
- 发现项目特有规律时，沉淀到 `AGENT_RULES.local.md`

### Git 操作

- 不使用 `--amend`，除非用户明确要求
- 不使用 `--force`；如用户坚持，必须先说明风险
- 不使用 `--no-verify` 跳过 hooks

### 工具使用

- 独立步骤尽可能并行执行
- 严格遵循工具参数定义与 schema
- 优先使用专用工具，不重复探测同一信息
- 文本搜索优先使用 `rg`

## 需要确认的场景

### 常规模式

- 需求不明确，或存在多种可行方案
- 需要行为、兼容性或性能取舍
- 涉及架构变更、破坏性修改或约束冲突
- 风险较高，且继续执行可能放大返工成本

### 无交互模式

- 安全红线：立即停止，不继续后续 Plan
- 架构变更、兼容性问题、破坏性修改：写回 `blocked`
- 多种可行方案：选择最保守方案，并在报告中说明理由
- 一般歧义、风险或决策点：记录到报告，继续执行安全部分

### 可以直接执行

- 明显的 bug 修复
- 符合现有模式的小改动
- 测试用例补充或局部验证补齐

## Session 收尾

- 汇总已完成、阻塞、跳过的 Plan 及原因
- 标出需要其他环境处理的事项：`env:<环境>:<Task列表>`
- 必要时将重要结论写入 `memory-bank/decisions.md`
- 出现以下情况时，建议开启新 Session：
  - 当前方向明显跑偏
  - 讨论阶段产出多个候选方案，准备进入执行
  - Session 过长，开始重复犯同类错误

## 验证清单

每个 Plan 完成后，至少确认：

- [ ] 代码修改符合 `.agents/` 下的规则（如有）
- [ ] 相关验证已执行，且测试在未豁免时通过
- [ ] 换行符与文件格式正确
- [ ] 无语法错误或明显运行时错误
- [ ] 已通过 `main_loop.py finish` 写回 Plan 状态

---

**最后更新**：{{DATE}}