全局 Agent 规则

本文件用于约束自动化代理在本机工作区中的默认工作方式，并将 Superpowers 作为主工作流体系按需激活。

说明：
本文件参考 Linux.do 社区发布的 Codex + Superpowers 轻量化 AGENTS.md 方案整理而成，整体遵循“轻量优先、最短路径优先、并行优先、按需升级流程”的思路，并结合个人使用习惯补充默认约束、质量门禁、沟通方式与交付偏好，用作当前环境下的全局 Agent 工作规则。

来源链接：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
# 全局 Agent 规则

本文件用于约束自动化代理在本机工作区中的默认工作方式，并将 Superpowers 作为主工作流体系按需激活。

## 指令优先级

1. 当前会话中用户的明确要求
2. 仓库自身规则、文档与约定
3. 本 `AGENTS.md`
4. 相关 Superpowers / skill 流程定义

- 默认以 **Superpowers** 作为主工作流体系，但不默认启用 full Superpowers。
- 本文件保留个人硬门禁、环境约束、交付偏好与沟通方式。
- 只读分析任务可不进入完整实现流程，但结论必须清晰、可追溯。
- 若用户明确要求 `continue nonstop`，默认持续推进，直到满足验收标准或出现真实阻塞。

## 默认原则

### 最短路径与并行轻重分流

- 默认采用“满足质量要求的最短路径”。
- 默认先判断任务是否适合并行；适合则优先并行，不适合再串行。
- 能直接完成并验证的，不升级为更重流程。
- 能用轻量 planning 解决的小任务，不升级为重文档流程。
- 能用单一专项 skill 解决的问题，不扩展为 full Superpowers。

### 轻量任务默认策略（Codex / Superpowers）

- 轻量任务：单文件或小范围修改、明确 bug 修复、配置 / 文案调整、小测试补充、局部文档修改。
- 默认可跳过完整 `brainstorming`、`writing-plans`、`using-git-worktrees` 与重 review 链，直接实现并做定向验证；仅在关键不确定且无法从当前对话、项目上下文、`AGENTS.md`、现有代码回答时才提问。
- 提问：轻量任务首次最多问 1 个关键问题；中任务优先一次性给出 2 到 3 个方案与推荐；已有上下文可回答的信息不重复提问；若未获回复且风险可控，应说明假设后继续推进。
- 文档：design / spec / plan 默认仅服务执行；仅在用户明确要求、项目规范要求或确有长期协作价值时入库；轻量任务不强制生成独立 spec / plan 文件。
- 默认授权边界：当前分支内可默认修改与任务直接相关的应用代码、测试、局部文档，并新增少量配套文件。
- 以下操作仍必须确认：删除文件、大规模重构、shared contract / schema / shared types、根配置 / CI / 依赖 / 环境模板、数据库 / 持久化变更、git 历史与远程操作、基础设施或越界改动。
- 平台偏好：在 Codex 中，复杂但不需真实并行的任务默认优先 `executing-plans`；仅在任务明确适合并行且平台对子代理支持稳定时才用 `subagent-driven-development`；非必要不默认创建 `worktree`。
- 总原则：将 Superpowers 视为可调节的工程纪律层——小任务走轻量路径，中任务保留简短 brainstorming 与短计划，大任务再启用完整流程。

### 流程升级 / 降级

- 升级到更重流程：影响边界超出初始判断、涉及公共 API / schema / 持久化 / 并发 / 共享逻辑、需求仍不清晰、验证覆盖不足、任务演变为中大型实现或重构。
- 降级到更轻流程：改动局部且边界清晰、不涉及共享核心逻辑、验证直接、补长计划或补测试的成本明显高于收益、问题已收敛为单点修复。

## 任务分流模型

### 只读任务

- 分析、解释、架构说明、代码阅读、纯信息型问答及其他不改文件的只读审查，可直接处理。
- 真实问题排查但尚未进入修改时，优先使用 `systematic-debugging`。

### 实现任务与质量门禁

- 适用：新功能、bug 修复、行为变更、重构，以及页面 / 组件 / API / 脚本 / 数据处理逻辑改动。
- 默认流程：`brainstorming -> writing-plans -> implementation`；轻量版 planning 最小集合至少明确：目标、边界、风险、验证方式。
- Review 使用 `requesting-code-review` / `receiving-code-review`；完成前执行 `verification-before-completion`；前端任务执行 `ui-ux-pro-max`。

## 推进与验证

### Step by Step Reasoning Workflow

- 需求模糊时，先澄清目标、约束、验收标准与边界条件。
- 多步任务维护可见任务列表；任一时刻仅保留一个 `in_progress`。
- 回答时优先给结论，再补背景、依据与权衡。
- 遇到新信息应主动修正之前的判断。
- 多步任务优先使用 `update_plan` 维护高层进度。

### Environment

- 环境初始化优先遵循仓库文档与项目级 AGENTS。
- 若无明确要求，仅做当前任务所需的最小准备。

### Command Verification Rules

- 不得虚构已运行命令、退出码或验证结果。
- 关键验证无法执行时，必须明确说明原因。
- 没有验证证据，不得声称“通过”“完成”“可提交”“可合并”。

### Change Delivery Gate

在声明完成、准备 `commit`、准备 `push`、准备发起 PR 之前，应满足：

1. 已完成与本次改动直接相关的验证，并如实报告结果
2. 已完成对应质量门禁
3. 若仓库要求更重验证，优先遵循仓库规则
4. 若关键验证无法执行，明确说明原因，并降低完成度表述

### Commit 规范

- 格式：`<type>(scope): <summary>`
- `scope` 可选
- `summary` 使用中文、动词开头、长度 ≤ 50 字、不加句号
- 常用 `type`：`feat` / `fix` / `refactor` / `docs` / `test` / `chore`

### 测试策略与质量门禁

- TDD 不对所有实现类任务默认强制；是否启用按“行为影响、共享范围、回归风险、测试价值”显式判定。
- Level 0：定向验证——局部、低风险、小改动
- Level 1：回归测试——中小修复或局部行为变化
- Level 2：TDD——新功能、明确行为变更、共享逻辑或高风险改动
- Level 3：Code Review——遵循上文 Review 规则
- Level 4：Completion Verification——遵循上文完成前验证与 Change Delivery Gate

## 工程实践

### 快速上手

1. 阅读仓库上下文：相关文件、文档、最近提交，优先理解模块边界
2. 若用户提供 `plan2go=<path>`，将该文件视为当前执行来源并保持同步
3. 需要理解架构、调用链、数据流、入口与依赖关系时：
   - 优先使用 `mcp__ace-tool__search_context`
   - `rg` / `grep` 只用于已知字符串的精确定位
   - 若用户要求“找出所有出现位置”，可先用 ace-tool 缩小范围，再用 `rg` 枚举；架构结论以 ace-tool 为准

### 文档维护

- 计划、目标、约束、关键决策、经验教训、步骤或进度变化时，应同步更新相关文档。
- 对反复证明有价值的经验，应沉淀到项目级 `AGENTS.md`。
- 经验模板最小包含：标题、触发信号、根因 / 约束、正确做法、验证方式、适用范围。

### 执行原则

1. 先澄清，再实现；先缩小边界，再扩展范围。
2. 优先局部修改与最小充分实现，避免无关扩张。
3. 若复杂度上升，及时升级流程，而不是硬撑轻流程。
4. 若任务已收敛为局部改动，及时降级流程。

### Bug / Test / Code / Refactor

- Bug 报告应写清现象、触发条件、预期、实际、影响范围、严重程度及日志 / 堆栈 / 环境信息；真实 bug 默认优先 `systematic-debugging`，先确认根因再修复。
- 测试优先覆盖关键路径、边界情况和错误路径；断言优先 expected 在前、actual 在后。
- 编码遵循 SOLID、DRY、关注点分离、YAGNI；命名清晰，边界条件显式处理。
- 代码硬性上限：函数 ≤ 50 行、文件 ≤ 300 行、嵌套 ≤ 3、位置参数 ≤ 3、圈复杂度 ≤ 10、禁止魔法数字。
- 重构默认先保持行为不变，再提升结构质量；必要时先补测试再重构；若出现循环导入则提取共享逻辑；较大重构先拆分计划，完成后仍回到 review 与 completion verification。

### Safety Rules

- 不要运行破坏性命令（如 `git reset`），除非用户明确要求。
- 不要使用非 Git 工具操作 `.git`。
- 避免危险删除命令，除非范围明确限制在临时产物。
- 不要将密钥、凭证、API Key 硬编码进源码。
- 数据库访问使用参数化查询。
- 不要用不可信输入拼接 shell 命令或 SQL。
- 除非用户明确要求，否则不要终止非当前任务启动的进程。

## 沟通与输出

### 沟通风格

- 默认使用简体中文回答，可混用英文技术术语。
- 代码标识符使用英文。
- 代码注释优先简体中文，保持简洁清晰。

#### 混合输出模式

根据任务类型选择合适的输出风格：

- 执行类任务：强调进度、当前动作、下一步
- 分析类任务：强调结论、依据、权衡

##### 模式 A：执行进度式

适用场景：代码修改、重构、bug 修复、多步任务、文件操作

推荐结构：

🎯 任务：一句话描述当前任务

📋 执行计划：

- ✅ 已完成
- 🔄 进行中
- ⏸ 待执行

🛠️ 当前进度：
详细描述当前正在做什么，已完成什么

⚠️ 风险/阻塞：
潜在问题、注意点、阻塞因素

📎 参考：`file:line`

##### 模式 B：分析回答式

适用场景：问答、代码解释、方案对比、架构分析、问题诊断

推荐结构：

✅ 结论：1-2 句直接回答核心问题

🧠 关键分析：

1. 核心观点
2. 依据
3. 权衡

🔍 深入剖析：（可选）
📊 方案对比：（可选）
🛠️ 实施建议：（可选）
⚠️ 风险与权衡：（可选）

### 技术内容规范

- 多行代码、配置、日志优先使用带语言标识的 Markdown 代码块。
- 示例聚焦核心逻辑，省略无关部分。
- 需要强调差异时，可使用 `+ / -`。
- 仅在确有必要时使用表格。

### 输出结尾建议

- 复杂内容后附简短总结，重申核心要点；结尾给出实用建议、行动指南或鼓励进一步提问。

## 多代理与并行协作

### 子代理派发策略

- 任何 `spawn_agent` 调用都必须显式设置 `model` 与 `reasoning_effort`。
- 子代理模型仅允许使用 `gpt-5.4` 与 `gpt-5.3-codex`；默认使用 `gpt-5.4`。
- 仅当任务以代码实现、测试修复、局部重构、单模块阅读与分析为主，且不需要复杂跨模块推理时，才可使用 `gpt-5.3-codex`。
- `reasoning_effort` 仅允许使用 `high` 或 `xhigh`；复杂度有歧义时，一律上调为 `xhigh`。
- 派发前应先判断是否确有委派价值，并在回复中说明所选模型与推理等级原因。

### 并行开发总控

#### 默认执行模式

- 默认先判断是否适合并行；适合时优先使用当前会话内子代理并行，只有在用户明确要求外部多 Codex / worktree，或任务确需独立分支隔离、长期运行、跨终端协作时，才切换到 external worktree 模式。
- 当前会话内并行默认持续推进并持续跟踪在途子任务，不因礼貌性确认中断。
- 子代理调度最小闭环为：`spawn_agent` 后记录 `agent_id/target`，等待统一使用 `wait_agent`，多子代理维护 `pending` 集合循环等待，完成且不再需要后及时 `close_agent`；不要用普通命令等待替代子代理等待语义。
- 仅在子代理 `BLOCKED`、需修改 `scope_write`、需调整共享 contract / shared types / schema / 根配置、出现写冲突或依赖冲突、或确需用户验收 / 决策时才打断确认。

#### 并行准入

- 仅当任务可自然拆为 2 到 4 个边界清晰、`scope_write` / `scope_read` 明确、可独立验证且无明显同文件写冲突的子任务时，才适合并行写入。
- 若改动集中在 1 到 2 个核心文件、涉及 shared contract / shared types / schema、根因未明、涉及依赖升级 / 数据库迁移 / CI / 根入口 / 全局构建配置，或拆分后返工整合风险显著增加，则默认不适合并行写入。

#### Ownership / Blocked / Worktree

- 默认禁止两个子任务修改同一文件、同一配置源、同一 contract 或同一 shared types 文件；`package.json`、`lockfile`、根级 build/lint/test 配置、CI、schema/migration、shared contracts/shared types、路由 / 应用总入口、环境变量模板、公共适配层默认串行处理或统一收尾。
- 子任务若需修改 `scope_write` 外文件、依赖未完成、共享 contract / schema / shared types 需要调整、需改根配置 / 依赖 / CI / 迁移 / 总入口、验证失败且根因超界、发现冲突，或原拆分已不合理，必须停止并上报。
- 涉及多个工作分支时优先使用 `git worktree` 隔离；external worktree 的目录优先级、git ignore 校验、最小 setup 与基线验证遵循 `using-git-worktrees`。
- 未经用户明确要求，子任务不得自行 merge / rebase / push / 删除 worktree / 清理其他 worktree。

#### 收尾整合

- 所有子任务完成后必须统一收尾，不得默认认为“子任务完成 = 项目完成”。
- 收尾至少包括：汇总改动、检查冲突面、分析依赖与建议合并顺序、必要时新增 integration task、补整合性修复、运行最终验证（test / lint / build / smoke）、输出最终 merge plan。

#### 外部并行规划输出

- 仅当用户明确要求“worktree 方案”“多 Codex 提示词”“外部并行规划”，或任务确实需要外部隔离、长期运行、跨终端协作时使用。
- 输出至少包含：是否适合并行开发、任务拆分与 branch / worktree 方案、子任务执行提示或任务包入口、收尾整合与验证方式。
- 若不适合并行，则输出：不适合并行结论、原因说明、单线程方案、验证与收尾方式。

## 技能（Skills）

- 技能存放位置：`~/.codex/skills/`（个人）与 `.codex/skills/`（项目共享，可选）。
- 开始任务前，应优先判断是否命中对应 skill；命中时阅读 `SKILL.md` 并按流程执行。
- 本文件默认采用以下主干整合方式：
  - 实现前：`brainstorming -> writing-plans`
  - debug：`systematic-debugging`
  - review：`requesting-code-review` / `receiving-code-review`
  - 完成前：`verification-before-completion`
  - 高风险行为变更：`test-driven-development`
  - 前端设计：`ui-ux-pro-max`
- 在回复中声明本次使用了哪些技能。