From 74b4e606fa3806abf60cc9336a41158eaf20000c Mon Sep 17 00:00:00 2001 From: meijiali <你的邮箱@xxx.com> Date: Tue, 7 Jul 2026 17:07:35 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20AGENTS=20=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E7=BA=A6=E5=AE=9A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 42 +++++++++++++++--------------------------- 1 file changed, 15 insertions(+), 27 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a3dc6a5..6d2a12b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -135,30 +135,15 @@ - 每个处理单元（内容项、评论批次）都应独立提交到数据库。 不要在整个任务期间持有一个长事务。 -## Superpowers 工作流 +## 开发约定 + +- 修复任何工单必须在独立的 git worktree 中进行；开工前先用 `git worktree add` 创建专属工作目录，避免污染主工作区、便于多工单并行。修 CI 配置（Dockerfile、Drone 流水线等）可以直接在主仓库改，因为 CI 改动要打 tag 才能触发构建。 +- 处理任何工单必须先检查并使用适用的 Superpowers Skill；在分析、提问、制定计划或改代码前，至少先启用 `using-superpowers`，并按任务性质继续使用 `systematic-debugging`、`test-driven-development`、`using-git-worktrees`、`verification-before-completion` 等相关技能。若判断没有适用技能，必须简短说明原因后再继续。 +- 新功能需求类工单必须先使用 Superpowers 的 `brainstorming` 技能帮助澄清目标、约束和方案，再进入计划或实现；缺陷类工单必须先使用 `systematic-debugging` 技能复现问题并分析 root cause，再开始修复，禁止在根因未明确时直接改代码。 +- 实现或修复工单完成后，必须继续按 Superpowers 收尾流程执行验证、代码审查、PR/合并准备和工作区清理；通常应依次使用 `verification-before-completion`、`requesting-code-review`、`finishing-a-development-branch` 等适用技能，在完成这些流程前不得声称工单已结束。 -Superpowers 是某些 AI 编码环境（例如 Codex）中可用的结构化思考模式。 如果当前环境不支持 `superpowers:*` 前缀，请手动应用同样的认知顺序： -brainstorm -> plan -> test-first -> implement -> debug -> verify。 - -当 superpowers 技能可用时，将其作为开发过程层使用： - -- 在不明确的功能设计、范围决策或行为变更前，使用 `superpowers:brainstorming`。 -- 在较大的实现前，使用 `superpowers:writing-plans`。 -- 对业务逻辑、数据映射、解析、报告和 bug 修复，在可行时使用 `superpowers:test-driven-development`。 - -从实现阶段进入验证阶段前： - -- 删除所有占位注释（例如 `# TODO: implement this`、`# FIXME`）。 -- 删除所有调试用 print/console.log 语句。 -- 确保没有注释掉的代码块，除非它们是对刻意设计决策的文档说明（并标明原因）。 - -- 在修复失败行为或意外测试结果前，使用 `superpowers:systematic-debugging`。 -- 在声称工作完成前，使用 `superpowers:verification-before-completion`。 -- 对于大型变更或里程碑完成，使用 `superpowers:requesting-code-review`。 - -如果技能不可用，请手动遵循同样原则：澄清范围、编写简短计划、尽量测试先行、 -基于证据调试、完成前验证，并保持提交聚焦。 +brainstorm -> plan -> test-first -> implement -> debug -> verify。进入验证阶段前，删除占位注释、调试 print/console.log，以及无说明的注释掉代码块。 ## 多代理规则 @@ -250,8 +235,8 @@ AI 重试逻辑和文档编辑合并在一个提交里，除非它们确实都 当前项目阶段是初始单人开发和流程练习。除非用户明确启用并行工作或 PR 工作流， 否则按依赖顺序串行执行任务：一次一个任务。 -在此阶段，每个 `docs/Tasks.md` 任务使用一个任务分支，命名为 -`feat/tXX-short-description`（例如 `feat/t01-project-skeleton`）。 +除 CI 配置修复外，每个工单都应先在主仓库外创建独立 git worktree，再在该 worktree 中创建或检出对应任务分支。分支命名建议继续使用 +`feat/tXX-short-description`、`fix/tXX-short-description` 或工单系统约定名称。 任务通过所需检查后，在可行时为该任务创建一个聚焦提交。 如果单个提交难以评审或安全回滚，大型任务可以拆分为多个有意义的提交。 @@ -276,11 +261,13 @@ git diff --check 只提交与当前任务相关的文件。不要回滚无关的用户变更。只有在提交已验证且用户希望更新远端分支时才 push。 -### 分支策略 +### 分支与 Worktree 策略 -单代理开发：除非用户指定其他分支，否则直接在 `main` 上工作。 +工单开发默认不直接在主工作区或 `main` 上修改业务代码。开工前从当前 `main` 创建专属 git worktree，并在 worktree 中使用任务分支完成开发。 -多代理并行开发：每个代理必须在从当前 `main` 派生的独立 Git 分支上工作。 +修 CI 配置（Dockerfile、Drone 流水线等）可以直接在主仓库改，因为 CI 改动要打 tag 才能触发构建。除该例外外，如需直接在主仓库改动，必须先得到用户明确确认。 + +多代理并行开发：每个代理必须在从当前 `main` 派生的独立 Git 分支和独立 worktree 上工作。 分支命名约定：`agent//`（例如 `agent/codex-1/T08`）。 只有主代理（或用户）可以合并回 `main`。 @@ -324,3 +311,4 @@ git diff --check |---|---|---| | 2025-07-10 | v1.0 | 初始版本 | | 2025-07-10 | v1.1 | 基于双重评审合并后的修订（12 条指令）：§Two-Day MVP Discipline 重写为 "MVP Discipline (Optimized for Speed)"，不再是裁剪清单，并明确禁止未经用户确认延期 P0 功能；§Project Constraints 增加三项架构约束（后台线程中仅使用同步 httpx、预生成报告、单任务 executor 且冲突时返回 400）；§Source Of Truth 增加评审文件纳入规则、冲突时绝对停止策略、防幻觉指令和 RequirementsDoc.md 存在性保护；§Development Workflow 中的 TDD 指令从 "when practical" 升级为按类别强制执行，并明确引用 TDD.md §2.1；新增 Error Handling Philosophy 小节；§Testing And Verification 增加覆盖率命令和 80% 目标；§Git Workflow 增加分支策略和强制多代理分支隔离；§Multi-Agent Rules 增加 4 个构建类并行任务示例；§Superpowers Workflow 增加环境兼容性说明和验证前清理规则；§Safety Rules 增加 raw_data fixture 脱敏指导；§Completion Standard 增加 Tasks.md 复选框同步要求和明确测试结果汇报要求。 | +| 2026-07-07 | v1.2 | 融入新的开发约定：工单默认使用独立 git worktree；处理工单前必须检查并使用适用的 Superpowers Skill；新功能先 brainstorming，缺陷先 systematic-debugging；完成后按 verification、code review、finishing branch 流程收尾。同步删除旧的直接在 main 上工作的单代理分支规则，避免与 worktree 约定冲突。 |