gym-manage/AGENTS.md

全局 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 等，无论是否有用）
• 唯一例外是以下模式，且必须严格按模板书写：

  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. 仍无法解决：明确告知用户已完成部分、卡点及所需支持