Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

工程工作流

状态：已实现

最后复核：2026-08-15

关联：Issue #1、Issue #5

长期讨论：GitHub Discussions

工作契约

  • **Milestone（里程碑）**是阶段目标和进度容器。
  • Issue 是唯一任务契约，其可观察验收标准约束实现和 QA。
  • 一个内聚 outcome 对应一个 Codex 任务：一个 Issue、一个 issue/<number>-<slug> 分支、一个仓库外 worktree 和一个 PR。
  • 每个实现只有一个 tracked-file 写入者。负责统筹的工程 Agent 只承担治理与协调；每个 Issue 都在独立 worktree 任务中实现。

当 Issue 的 outcome、范围、可观察验收标准、验证命令、安全或风险约束和依赖均已明确，必要决策已解决，且规模足以由一个内聚 PR 完成时，Issue 才是 Ready。

角色

  • Implementer（实现者）： 唯一写入者。每个代码任务都必须在实现全程使用已安装的 ponytail:ponytail skill full 模式。Implementer 负责自检、发布 Issue 分支、维护 Draft PR、修复 finding，并在冻结最终 SHA 前完成文档影响扫描。
  • Reviewer（审查者）： 在同一最终 SHA 上执行只读审查。先审查正确性、架构、安全、回归风险、测试缺口、文档语言与实现/测试/图表的语义一致性，并单独报告 Documentation Consistency Review；涉及订单、风控或状态时，必须检查资金安全、fail-closed、恢复、对账和审计语义。随后运行已安装的 ponytail:ponytail-review skill 查找不必要复杂度。Ponytail 绝不替代标准审查。Reviewer 不修复文件，并分别报告结果。
  • QA（质量验收）： 不运行 Ponytail。QA 使用真实命令，依据 Issue 的可观察验收标准验证精确的最终 head SHA，并报告 SHA、环境、命令、结果和未验证项；同时确认本次范围内面向人的文档以简体中文为主。QA 必须构建文档 HTML 并人工检查目录、关键页面和图表渲染；涉及资金或交易状态时，还必须验证 fail-closed、恢复、对账和审计的可观察验收标准。QA 可以生成已忽略的构建产物，但绝不编辑源码、测试、配置、文档或其他 tracked file。
  • 用户： 唯一 merge authority（合并权威）。

Reviewer 和 QA 的 finding 都返回 Implementer。subagent 审查是证据，不等于 GitHub required approval；使用同一 GitHub 身份的 Agent 绝不伪装成独立审批者。

PR 流程

  1. 创建 Issue，fetch origin/main，并在仓库外 worktree 中创建对应分支。
  2. 首次 push 后，默认创建目标为 main 的 Draft PR，并写入 Closes #<number>。只有 Issue 明确记录依赖关系且用户授权 stacked workflow 时，分支才可从依赖 PR 的冻结 head 创建，并以依赖分支为临时 PR base；PR 正文必须标明依赖 PR 和后续 retarget 计划。
  3. Implementer 完成 Issue 验收标准、运行仓库检查、更新 PR 证据并冻结 head SHA。
  4. Implementer 按 DOCUMENTATION_POLICY.md 阅读相对 PR base 的完整 diff，更新背离的正文/图表，运行文档校验、测试和构建，并在 PR 记录 Documentation Impact 与证据。
  5. Reviewer 针对该 head SHA 与当前 PR base 的 merge-base（审查 fixed point）先运行标准审查及 Documentation Consistency Review，再运行 ponytail:ponytail-review，并记录 base 名称、base SHA、merge-base 与 head SHA，全程不编辑文件。
  6. Implementer 修复 finding、重跑检查、push 新 SHA，并要求 Reviewer 重跑受影响的审查。
  7. QA 验证最终 SHA，并确认验证前后 tracked diff 不变。
  8. 只有 Standard Review、Ponytail Review（改动代码或工具时）、Documentation Consistency Review、QA 和适用的 docs CI 在同一最终 SHA 上全部 PASS 后，PR 才能从 Draft 转为 Ready for review。
  9. 由用户决定是否 merge。

任何新 commit 都会使之前的最终 SHA 证据失效，并触发受影响的 Reviewer 与 QA 步骤重跑。

Stacked PR 的依赖 PR 合并后，Implementer 必须先 fetch origin/main，确认新 main 已包含依赖 PR 的预期结果，再用安全 rebase 或等价的无损方式把当前分支更新到新 base，并将 PR base retarget 为 main。base、merge-base 或 head 的任何变化都会使既有 diff、Review 与 QA 证据失效，必须按新的 fixed point 重跑检查；不得通过丢弃提交或覆盖他人改动来迁移 base。

仅在 Milestone 或阶段结束时使用 ponytail:ponytail-audit。只有存在 ponytail: 标记时，才在阶段结束或发布前运行 ponytail:ponytail-debt。ponytail:ponytail-gain 与 ponytail:ponytail-help 仅手动使用，绝不作为 merge 门禁。

授权与安全

明确分配的 Issue 实现任务授权创建对应 Issue 分支/worktree、commit 和 push 该分支，以及创建或更新匹配的 PR；它绝不授权直接 push main 或 merge。产品目标包含真实资金交易，但任何真实下单仍始终需要未来专门 Issue 的风险门禁、验收证据和用户新的明确授权；未知或不安全的交易状态继续采用 fail-closed。

合并与清理

只使用 squash merge。目标为默认分支的 PR 合并后，通过 Closes #<number> 关闭对应 Issue；随后由 GitHub 删除远端 head branch。确认合并后，再删除本地 worktree 和本地 Issue 分支。

首个真实 Rust target 出现前，不得添加空洞或伪造的 Rust CI。文档站已经具有真实可验证的构建目标，因此允许运行唯一命名的 docs job；Rust 格式化、Clippy 和测试仍须等对应 target 存在后再启用。

当前仓库已迁移至 caasxyz 组织私有仓库，并启用 Protect main ruleset；该 ruleset 目前只要求经 PR 合并并禁止删除与 non-fast-forward，尚未把 docs 配置为 required status check。因此 docs 仍通过用户 merge discipline（合并纪律）、PR 检查结果和最终 SHA 审查证据执行门禁，不得声称平台已经强制。只有通过独立 Issue 配置并验证 required check 后，文档才可改为平台强制状态；首个真实 Rust target 出现且唯一命名的 ci job 成功前，仍不得添加 Rust required check。