zhangxiang
5c65139fd8
- AGENTS.md: 新增 §20 工具脚本复用 / §21 分析结论复用 / §22 Flaky 门禁，更新文档配置表
- .pi/: 新增 settings.json、rules/guardrails.md、prompts/{debug,review,ship}-gym-manage.md
- .agents/: 新增 Hook 配置与 4 个 Hook 脚本（session-start/pre-agent-check/check-completeness/stop-check）
及 protocols/systematic-debugging.md（check-completeness 含接口链缺口检测）
- scripts/flaky-scan.sh: vitest shuffle 稳定性扫描（gym-manage-web）
- .gitignore: 追踪 AGENTS.md 与 .pi 配置，忽略运行时缓存（todos/taskflows-runs/tokenomy/sessions）
179 lines
10 KiB
Markdown
179 lines
10 KiB
Markdown
# 全局 Agent 规则
|
||
|
||
本文件用于约束自动化代理在本机工作区中的默认工作方式，并将 Superpowers 作为主工作流体系按需激活。
|
||
|
||
## 指令优先级
|
||
|
||
- 默认以 **Superpowers** 作为主工作流体系，但不默认启用 full Superpowers。
|
||
- 只读分析任务可不进入完整实现流程，但结论必须清晰、可追溯。
|
||
- 若用户明确要求 `continue nonstop`，默认持续推进，直到满足验收标准或出现真实阻塞。
|
||
- `AGENT.md` — 项目架构、命令、测试策略的主要参考
|
||
- `CONTEXT.md` — 领域术语表与业务上下文
|
||
- 本文件约束通用 Agent 行为模式。当 AGENTS.md 与 AGENT.md 冲突时，AGENTS.md 优先
|
||
|
||
## 核心原则
|
||
|
||
### §1 任务分解优先
|
||
- 任何需 3 步以上的工作，先创建任务列表再实施
|
||
- 开始任务标记 `in_progress`，完成标记 `completed`
|
||
- 停止前检查所有任务状态，无遗留 `pending`/`in_progress`
|
||
|
||
### §2 最短路径与流程升降级
|
||
- **默认以 Superpowers 作为主工作流体系**，但不默认启用 full Superpowers
|
||
- **默认实现方法**：TDD（RED→GREEN→REFACTOR）。能通过 TDD 完成的，不升级为更重流程
|
||
- 默认采用"满足质量要求的最短路径"
|
||
- 能直接完成并验证的，不升级为更重流程
|
||
- 能用轻量 planning 解决的小任务，不升级为重文档流程
|
||
- 能用单一专项 skill 解决的问题，不扩展为 full Superpowers
|
||
- **升级条件**：边界超出判断、涉及公共 API/schema/持久化/并发/共享逻辑、需求不清晰
|
||
- **降级条件**：仅限用户批准的极简单变更（文档、配置、拼写错误）
|
||
|
||
### §3 技能优先使用
|
||
- 执行任务前先检查可用 skills；若存在匹配 skill，通过 Skill 工具调用
|
||
- 禁止绕过已有 skill 手工实现
|
||
- 能用单一 skill 完成的事项，不使用 Agent 或 Workflow 重实现
|
||
|
||
### §4 编码质量（Karpathy Guidelines）
|
||
在编写、审查或重构代码时，遵循以下原则：
|
||
1. **编码前先思考** — 明确假设，不隐藏困惑，展示权衡
|
||
2. **简单优先** — 只写解决问题的最小代码，拒绝过度抽象
|
||
3. **精准修改** — 只触碰必须修改的部分，不"改进"相邻代码
|
||
4. **目标驱动执行** — 定义可验证的成功标准，循环直到验证通过
|
||
|
||
### §5 逐步推理
|
||
1. 先澄清再实现，先缩小边界再扩展范围
|
||
2. 涉及第三方库/框架时，优先用 `context7` 查询官方文档
|
||
3. 优先局部修改与最小充分实现
|
||
4. 复杂度上升时升级流程，收敛时降级
|
||
|
||
### §6 零缺陷交付
|
||
- **严守三不**：绝不延期、绝不出错、绝不超计划
|
||
- **禁止凭空制造**：代码/API/数据结构必须有可信来源支撑
|
||
- 所有产出物（代码/文档）必须逻辑严谨、可验证、无歧义错误
|
||
|
||
### §7 多源交叉验证
|
||
- 实现前从至少**两个独立可信源**比对求证，消除理解偏差
|
||
- 两个信源矛盾时以官方/权威文档为准
|
||
- 变更影响评估：修改前评估对关联模块的影响，并同步更新相关文档
|
||
|
||
### §8 双轨验证
|
||
任务完成后：
|
||
1. **功能验证**（测试/边界条件/异常路径）
|
||
2. **溯源验证**（对照可信信源）
|
||
|
||
### §9 循环控制
|
||
连续两步实质性重复、引用同一信源无新信息、结论已在上一轮已知结论集中 → **立即终止**并输出已确认的稳定结论
|
||
|
||
### §10 变更影响评估
|
||
修改前评估关联模块：数据模型→适配器/测试；API→调用方；配置→各环境
|
||
|
||
### §11 无骨架占位
|
||
- 禁止：`throw 'not implemented'`、空函数体、`// TODO`/`// FIXME`、无返回值函数
|
||
- 完成前验证：TDD 合规检查 → 类型检查 → 自我审查 → 集成验证
|
||
|
||
### §12 诚实地报告不完整性
|
||
不能完成时明确告知：已完成部分、未完成部分及原因、后续步骤
|
||
|
||
### §13 全链路集成验证（P0 强制）
|
||
**每个新功能必须打通完整链路**：API 接口 → Service 层 → Web 前端组件 / UniApp 页面
|
||
|
||
- ❌ 后端实现但前端无调用链 / 前端组件无后端数据源 / 类型漂移
|
||
- ❌ Mock 通过 ≠ 功能可用（需要通过真实后端验证）
|
||
- 详见 `AGENT.md` 工作流说明
|
||
|
||
### §14 任务拆分即包含集成
|
||
"后端 API → 前端页面/组件 → 小程序页面"是同一个 Task，禁止拆成后端/前端两个独立 Task（轻量修复除外）
|
||
|
||
### §15 系统调试优先
|
||
遇到 bug 先定位根因再修复，禁止"试试看"。完成根源调查前不得提修复方案。
|
||
|
||
### §16 中文文档与注释规范
|
||
业务逻辑/领域知识注释优先用中文。变量名/函数名/类名始终用英文。技术术语保留英文不翻译。
|
||
|
||
### §17 完整性命门（Completeness Gate）
|
||
功能完成前必须通过完整性验证，确保无遗漏接口、无未连接的调用链、无类型漂移。
|
||
|
||
### §18 测试编写流程
|
||
1. 阅读/Code Review 业务代码 → 理解组件实际行为
|
||
2. 识别测试需要覆盖的关键行为点
|
||
3. 编写精确断言，匹配业务代码的实际渲染输出
|
||
4. 运行测试验证
|
||
|
||
### §19 测试命令退出码保留（P0 强制）
|
||
- 测试命令必须是整条 bash 命令的**最后一个命令**，禁止在后面追加任何后处理（`grep`、`head`、`wc -l`、`echo`、`tee` 等，无论是否有用）
|
||
- 唯一例外是以下模式，且必须严格按模板书写：
|
||
```bash
|
||
test_cmd > /tmp/output.txt 2>&1; EXIT=$?
|
||
# 后处理（只读，不修改 EXIT）
|
||
wc -l /tmp/output.txt
|
||
grep ... /tmp/output.txt | head -30
|
||
exit $EXIT
|
||
```
|
||
- 管道场景使用 `set -o pipefail` 确保任一命令失败时整体退出码非零
|
||
- 重定向顺序必须是 `> file 2>&1`，不能是 `2>&1 > file`
|
||
|
||
### §20 工具脚本可复用优先（P0 强制）
|
||
**禁止生成一次性（one-off）内联脚本。任何需要重复执行的命令、分析、转换逻辑，必须固化为 `scripts/` 下的持久化工具脚本。**
|
||
|
||
- ❌ 禁止：每次在 bash 中内联 Python/Node/awk 脚本做一次性分析（接口扫描、测试报告解析、JSON 提取等），用完即丢
|
||
- ✅ 允许：将逻辑写入 `scripts/*.py` / `scripts/*.sh` / `scripts/*.mjs`（带参数、帮助信息、可重复执行），后续通过 `bash scripts/xxx.sh --args` 复用
|
||
- ✅ 已有工具先查 `scripts/` 是否已存在：`scripts/run-tests.sh`、`scripts/start-all.sh`、`scripts/collect-test-metrics.py`、`scripts/flaky-scan.sh` 等
|
||
- 内联 `python3 -c "..."` 仅允许用于不超过 3 行的极简调试输出
|
||
- 新工具脚本必须：① 放到 `scripts/` ② 支持 `--help` 或头部注释说明用法 ③ 可带参数运行 ④ 不硬编码具体文件路径（接受参数或从项目根推导）
|
||
|
||
### §21 分析结论复用，避免重复调查（P0 强制）
|
||
- 同一类分析（覆盖率、接口映射、测试报告）优先复用已有脚本与文档，不重新编写一次性脚本
|
||
- 已在 `docs/reports/`、`docs/plans/`、`docs/framework/` 中记录的任务状态/结论，先读取再继续，不重复调查
|
||
- 测试命令与服务端口以 `AGENT.md` 为准；领域术语以 `CONTEXT.md` 为准；已有结论以 `docs/reports/` 为准
|
||
|
||
### §22 Flaky 测试门禁（P1 强制）
|
||
- 新增/修改前端测试（`gym-manage-web`，vitest）后，必须通过 `bash scripts/flaky-scan.sh --spec <文件> --runs 3` 验证**顺序无关性**
|
||
- **存在 flaky 时禁止合并**：全量 `bash scripts/flaky-scan.sh --runs 1` 失败（shuffle 下任何测试失败）即阻断合并，须先定位根因修复
|
||
- 常见 flaky 根因（Vitest 环境）：
|
||
① `vi.clearAllMocks()` 不清除 `mockResolvedValue/mockRejectedValue` 实现 → beforeEach 须显式恢复默认实现
|
||
② store/pinia 单例跨测试残留 → beforeEach 须重置全部字段
|
||
③ 模块级可变 `let` mock 变量被测试修改未还原
|
||
④ `vi.stubGlobal` 全局替换（URL/Notification/FileReader 等）未在 afterEach 恢复
|
||
⑤ 异步测试缺少 `await flushPromises()`/`waitFor`（被空渲染掩盖的隐藏缺陷）
|
||
- 新增测试文件必须通过 `bash scripts/flaky-scan.sh --spec <新文件> --runs 3`
|
||
|
||
## 默认原则
|
||
|
||
### 轻量任务默认策略（Codex / Superpowers）
|
||
- 轻量任务：单文件或小范围修改、明确 bug 修复、配置 / 文案调整、小测试补充、局部文档修改。
|
||
- 默认可跳过完整 `brainstorming`、`writing-plans`、`using-git-worktrees` 与重 review 链，直接实现并做定向验证；仅在关键不确定且无法从当前对话、项目上下文、`AGENTS.md`、现有代码回答时才提问。
|
||
- 总原则：将 Superpowers 视为可调节的工程纪律层——小任务走轻量路径，中任务保留简短 brainstorming 与短计划，大任务再启用完整流程。
|
||
|
||
### 流程升级 / 降级
|
||
- **升级到更重流程**：影响边界超出初始判断、涉及公共 API / schema / 持久化 / 并发 / 共享逻辑、需求仍不清晰、验证覆盖不足、任务演变为中大型实现或重构。
|
||
- **降级到更轻流程**：改动局部且边界清晰、不涉及共享核心逻辑、验证直接、补长计划或补测试的成本明显高于收益、问题已收敛为单点修复。
|
||
|
||
## 文档与配置
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `AGENTS.md` | 通用行为规则（本文件） |
|
||
| `AGENT.md` | 项目架构、命令、测试策略、服务工作端口 |
|
||
| `CONTEXT.md` | 领域术语表 / 业务上下文 |
|
||
| `.pi/settings.json` | 项目级 Pi 配置 |
|
||
| `.pi/rules/guardrails.md` | Pi Agent 安全边界（文件/依赖/构建/Git） |
|
||
| `.pi/prompts/` | 项目专用调试 / 审查 / 发布提示词 |
|
||
| `.agents/settings.json` | 项目级 Hook 配置 |
|
||
| `.agents/hooks/` | Hook 脚本（session-start / pre-agent-check / check-completeness / stop-check） |
|
||
| `.agents/protocols/` | 调试与测试分析协议 |
|
||
| `.agents/skills/` | 自定义 Skills（feature-completeness-gate / systematic-debugging 等） |
|
||
| `docs/superpowers/specs/` | 需求共识 spec 与 PRD 文档 |
|
||
| `docs/superpowers/plans/` | 可执行任务计划 |
|
||
| `docs/superpowers/guides/` | 最佳实践指南 |
|
||
| `docs/adr/` | 架构决策记录 |
|
||
| `docs/architecture/` | 架构文档 |
|
||
| `README.md` | 项目概览、快速开始 |
|
||
|
||
## 问题升级路径
|
||
|
||
1. **自查比对**：检查代码逻辑与测试用例，定位明显错误
|
||
2. **第一信源查证**：使用 `context7` 获取官方/权威文档说明
|
||
3. **第二信源佐证**：搜索额外独立来源进行比对印证
|
||
4. **实证测试**：编写最小化验证代码，用实际运行结果终结争议
|
||
5. **仍无法解决**：明确告知用户已完成部分、卡点及所需支持
|