codex-usage-guide/engineering.html at master · WhoJay0609/codex-usage-guide · GitHub

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
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>工程 flow</title>
  <!-- guide:theme-bootstrap:start -->
<script src="assets/theme.js"></script>
<!-- guide:theme-bootstrap:end -->
  <link rel="stylesheet" href="assets/site.css">
  <!-- guide:metadata:start -->
<meta name="description" content="用用户、编排线程和执行线程组织从需求澄清到验证发布的工程任务。">
<meta name="guide-build" content="ee947e14a0a9">
<link rel="icon" href="favicon.svg" type="image/svg+xml">
<link rel="canonical" href="https://whojay0609.github.io/codex-usage-guide/engineering.html">
<meta property="og:type" content="website">
<meta property="og:locale" content="zh_CN">
<meta property="og:site_name" content="Codex 使用指南">
<meta property="og:title" content="工程 flow">
<meta property="og:description" content="用用户、编排线程和执行线程组织从需求澄清到验证发布的工程任务。">
<meta property="og:url" content="https://whojay0609.github.io/codex-usage-guide/engineering.html">
<meta property="og:image" content="https://whojay0609.github.io/codex-usage-guide/figures/social-preview.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="Codex 使用指南">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="工程 flow">
<meta name="twitter:description" content="用用户、编排线程和执行线程组织从需求澄清到验证发布的工程任务。">
<meta name="twitter:image" content="https://whojay0609.github.io/codex-usage-guide/figures/social-preview.png">
<meta name="twitter:image:alt" content="Codex 使用指南">
<!-- guide:metadata:end -->
</head>
<body>
  <!-- guide:header:start -->
<script src="assets/site-data.js"></script><a class="skip-link" href="#main-content">跳到正文</a><header class="topbar"><div class="topbar-inner"><a class="brand" href="index.html"><span class="brand-mark" aria-hidden="true"></span><span>Codex 使用指南</span></a><div class="topbar-actions"><label class="theme-control"><span class="sr-only">主题</span><select class="theme-select" id="theme-select" name="theme" aria-label="主题"><option value="light" selected>浅色</option><option value="dark">深色</option></select></label><span class="theme-status sr-only" aria-live="polite"></span><button class="search-trigger" type="button" aria-haspopup="dialog" aria-controls="site-search-dialog">搜索</button><button class="menu-toggle" type="button" aria-controls="global-nav" aria-expanded="false">目录</button></div></div></header><dialog class="search-dialog" id="site-search-dialog" role="dialog" aria-modal="true" aria-labelledby="site-search-title"><div class="search-dialog-panel"><div class="search-dialog-head"><p class="search-title" id="site-search-title">搜索全站</p><button class="search-close" type="button" aria-label="关闭搜索">关闭</button></div><label class="search-label" for="site-search-input">搜索标题、正文和可复用 prompt</label><input class="search-input" id="site-search-input" type="search" role="combobox" autocomplete="off" aria-autocomplete="list" aria-controls="site-search-results" aria-describedby="site-search-status" aria-expanded="false"><p class="search-message" id="site-search-status" aria-live="polite">输入关键词开始搜索。</p><ul class="search-results" id="site-search-results" role="listbox" aria-label="搜索结果"></ul></div></dialog>
<!-- guide:header:end -->
  <!-- guide:shell-open:start -->
<div class="toolbook-shell"><aside class="global-nav" id="global-nav" aria-label="全站导航"><section class="global-nav-group"><strong>开始</strong><a data-nav href="index.html">首页</a><a data-nav href="install-desktop.html">安装</a><a data-nav href="desktop-cli.html">Desktop</a></section><section class="global-nav-group"><strong>基础概念</strong><a data-nav href="codex.html">Codex</a><a data-nav href="git.html">Git</a><a data-nav href="worktrees.html">Worktrees</a><a data-nav href="permissions.html">权限</a><a data-nav href="agents-md.html">AGENTS.md</a><a data-nav href="skills.html">Skills</a><a data-nav href="mcp.html">MCP</a><a data-nav href="subagents.html">Subagents</a><a data-nav href="goal.html">Goal</a></section><section class="global-nav-group"><strong>任务路径</strong><a data-nav href="workflows.html">任务</a><a data-nav href="daily-workflow.html">日常</a><a data-nav href="engineering.html" aria-current="page">工程</a><a data-nav href="research.html">学术</a><a data-nav href="automation.html">定时任务</a></section><section class="global-nav-group"><strong>扩展与资料</strong><a data-nav href="compound-engineering.html">Compound</a><details class="global-nav-disclosure"><summary>Skills 仓库</summary><a data-nav href="skills-repositories.html">全部仓库</a><a href="skills-repositories.html#compound-engineering">Compound Engineering</a><a href="skills-repositories.html#mattpocock-skills">Matt Pocock skills</a><a href="skills-repositories.html#academic-research-skills-codex">ARS</a><a href="skills-repositories.html#aris-auto-claude-code-research-in-sleep">ARIS</a><a href="skills-repositories.html#refine-user-prompt">refine-user-prompt</a></details><a data-nav href="prompt-guidance.html">提示词</a><a data-nav href="resources.html">资料</a></section></aside><div class="toolbook-main"><nav class="breadcrumbs" aria-label="面包屑"><a href="index.html">首页</a><span aria-hidden="true">/</span><span>任务路径</span><span aria-hidden="true">/</span><span aria-current="page">工程</span></nav><div class="page-freshness"><span>页面更新：<time datetime="2026-07-12">2026-07-12</time></span><span>事实核验：<time datetime="2026-07-12">2026-07-12</time></span></div><aside class="page-toc" aria-label="本页目录"><details><summary>本页目录</summary><nav><a class="toc-h2" href="#从-idea-到-task-receipt">从 Idea 到 task receipt</a><a class="toc-h2" href="#双层角色与权限">用户、编排线程与执行线程</a><a class="toc-h3" href="#a2-用户-产品负责人">用户（A2）</a><a class="toc-h3" href="#a3-主线程-编排者">编排线程（A3）</a><a class="toc-h3" href="#a4-subagent-独立-reviewer">执行线程 / 独立 reviewer（A4）</a><a class="toc-h3" href="#外部写入-grant">外部写入 grant</a><a class="toc-h3" href="#自动失效">自动失效</a><a class="toc-h2" href="#按依赖和写域组织并行">按依赖和写域组织并行</a><a class="toc-h3" href="#contract-lane-串行">Contract lane 串行</a><a class="toc-h3" href="#独立-lanes-并行">独立 lanes 并行</a><a class="toc-h3" href="#更新基线">更新基线</a><a class="toc-h3" href="#集成门">集成门</a><a class="toc-h3" href="#可并行示例">可并行示例</a><a class="toc-h3" href="#失败停止">失败停止</a><a class="toc-h2" href="#独立-reviewer-合同">独立 reviewer 合同</a><a class="toc-h2" href="#真实实例-历史复合案例">真实实例：历史复合案例</a><a class="toc-h3" href="#请求">请求</a><a class="toc-h3" href="#先读">先读</a><a class="toc-h3" href="#角色">角色</a><a class="toc-h3" href="#边界-文件">边界 / 文件</a><a class="toc-h3" href="#脏主保护">脏主保护</a><a class="toc-h2" href="#完整-goal">完整 Goal</a><a class="toc-h3" href="#分工">分工</a><a class="toc-h3" href="#验证证据">验证证据</a><a class="toc-h3" href="#独立-review">独立 review</a><a class="toc-h3" href="#重要恢复">重要恢复</a><a class="toc-h3" href="#结果-receipt">结果 / receipt</a><a class="toc-h3" href="#失败停止-2">失败停止</a><a class="toc-h3" href="#来源分类">来源分类</a><a class="toc-h2" href="#真实实例-修复-api-429-限流">真实实例：修复 API 429 限流</a><a class="toc-h3" href="#api-start">起始状态</a><a class="toc-h3" href="#api-prompt">Prompt</a><a class="toc-h3" href="#api-approval">审批边界</a><a class="toc-h3" href="#api-result">可观察结果</a><a class="toc-h3" href="#api-recovery">失败恢复</a><a class="toc-h3" href="#api-verify">验证证据</a></nav></details></aside>
<!-- guide:shell-open:end -->
<main id="main-content">
    <section class="hero compact"><div class="hero-copy"><p class="hero-kicker">团队工程</p><h1>团队协作规范</h1><p class="lead">以 Codex Desktop 主线程为协作中枢：产品负责人批准合同，编排者维护统一计划，subagent 在隔离写域执行，独立 reviewer 只按验收合同审查。复杂任务走完整闭环；短小、低风险、单写域任务可以直接执行最窄验证，不必机械套用全流程。</p></div></section>

    <section class="section" id="team-flow">
      <div class="section-head"><div class="section-title"><p class="section-kicker">团队流程</p><span class="fragment-alias" id="heading-engineering-1" data-canonical-fragment="从-idea-到-task-receipt" aria-hidden="true"></span><h2 id="从-idea-到-task-receipt">从 Idea 到 task receipt<a class="heading-permalink" data-heading-permalink data-search-exclude href="#从-idea-到-task-receipt" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2></div><p>先把产品问题变成合同，再把同一份合同逐层细化。下述 <code>ce-brainstorm</code>、<code>ce-plan</code> 等 CE 流程需要先安装 <strong>Compound Engineering</strong>；未安装时可沿用相同步骤，但不能假定命令可用。需要任务入口、长目标、Worktree 隔离、代理分工或指令层级时，分别参考 <a href="workflows.html#task-entry">任务路径</a>、<a href="goal.html#real-example">Goal</a>、<a href="worktrees.html#desktop-start">Worktrees</a>、<a href="subagents.html#worktree-subagent">Subagents</a> 与 <a href="agents-md.html#real-example">AGENTS.md</a>。</p></div>
      <figure class="figure-card mermaid-card">
        <div class="mermaid">
flowchart TD
  A["Idea"] --> B["Matt-style grill"]
  B --> C["ce-brainstorm Product Contract"]
  C --> D["ce-plan 统一实施计划"]
  D --> E["Issues 与依赖图"]
  E --> F["Worktrees / subagents"]
  F --> G["PR + 独立 review + CI"]
  G --> H["经授权合并主分支"]
  H --> I["主分支 / 公开页面验证"]
  I --> J["task receipt"]
  C -->|驳回| B
  D -->|not ready| D
  E -->|依赖或写域重叠| E
  G -->|验证失败 / changes / CI red| F
  H -->|未授权| K["blocked receipt"]
  I -->|失败| K
        </div>
        <figcaption>团队协作主流程及失败回路。图形不可用时，紧邻下方的文字版提供完全等价的顺序与门禁。</figcaption>
      </figure>
      <div class="decision-table" aria-label="团队协作流程文字等价版">
        <div class="decision-row"><strong>1. Idea → grill</strong><span>先读证据并做 Matt-style grill</span><span>开放问题不能带入实现</span><span>Product Contract 驳回就回到 grill</span></div>
        <div class="decision-row"><strong>2. Contract → plan</strong><span><code>ce-brainstorm</code> 固化 Product Contract</span><span><code>ce-plan</code> 细化同一份统一实施计划</span><span>plan 不 ready 就留在 plan</span></div>
        <div class="decision-row"><strong>3. Issues → lanes</strong><span>建立依赖图和互斥写域</span><span>Worktree / subagent 只接明确 lane</span><span>依赖或写域重叠就回 issue slicing</span></div>
        <div class="decision-row"><strong>4. PR → review</strong><span>提交 PR、独立 review、运行 CI</span><span>reviewer 记录合同、diff、disposition</span><span>验证失败、changes 或 CI red 回 implementation</span></div>
        <div class="decision-row"><strong>5. Merge → receipt</strong><span>获得授权后合并主分支</span><span>更新基线并验证主分支/公开页面</span><span>未授权或最终验证失败，输出 blocked receipt</span></div>
      </div>
    </section>

    <section class="section" id="roles-authority">
      <div class="section-head"><div class="section-title"><p class="section-kicker">角色与权限</p><span class="fragment-alias" id="heading-engineering-2" data-canonical-fragment="双层角色与权限" aria-hidden="true"></span><h2 id="双层角色与权限">用户、编排线程与执行线程<a class="heading-permalink" data-heading-permalink data-search-exclude href="#双层角色与权限" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2></div><p><strong>A2/A3/A4 是本指南的教学框架</strong>，不是 Codex 原生角色名。主要角色分别是用户、编排线程和执行线程；编排线程负责整合但不能替代用户的产品批准，执行线程提供实现或独立证据且不能越过写域自行发布。</p></div>
      <div class="bento">
        <article class="card span-4 dark-card"><span class="fragment-alias" id="heading-engineering-3" data-canonical-fragment="a2-用户-产品负责人" aria-hidden="true"></span><h3 id="a2-用户-产品负责人">用户（A2）<a class="heading-permalink" data-heading-permalink data-search-exclude href="#a2-用户-产品负责人" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>拥有产品意图、Product Contract、范围变化和最终合并授权；验收 receipt，并决定 blocked 项如何处理。</p></article>
        <article class="card span-4"><span class="fragment-alias" id="heading-engineering-4" data-canonical-fragment="a3-主线程-编排者" aria-hidden="true"></span><h3 id="a3-主线程-编排者">编排线程（A3）<a class="heading-permalink" data-heading-permalink data-search-exclude href="#a3-主线程-编排者" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>维护唯一合同与统一计划，切 issue、分配写域、集成结果、处理 review disposition，并向用户报告可审计证据。</p></article>
        <article class="card span-4"><span class="fragment-alias" id="heading-engineering-5" data-canonical-fragment="a4-subagent-独立-reviewer" aria-hidden="true"></span><h3 id="a4-subagent-独立-reviewer">执行线程 / 独立 reviewer（A4）<a class="heading-permalink" data-heading-permalink data-search-exclude href="#a4-subagent-独立-reviewer" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>在被分配的只读或隔离写域内工作。reviewer 必须未参与实现，且不共享被审 lane 的写域。</p></article>
      </div>
      <div class="decision-table" aria-label="A2 A3 A4 动作权限表">
        <div class="decision-row"><strong>动作</strong><span>A2 用户 / 产品负责人</span><span>A3 主线程 / 编排者</span><span>A4 subagent / reviewer</span></div>
        <div class="decision-row"><strong>Product Contract 批准</strong><span>批准、驳回或收窄</span><span>基于 grill 起草并维护版本</span><span>只提供证据与风险</span></div>
        <div class="decision-row"><strong>计划 readiness</strong><span>确认产品验收口径</span><span>补齐依赖、写域和验证后判定</span><span>独立检查缺口，不自行放行</span></div>
        <div class="decision-row"><strong>Issue</strong><span>定优先级与产品边界</span><span>创建、切片、维护依赖图</span><span>只执行被分配 issue</span></div>
        <div class="decision-row"><strong>Worktree / branch</strong><span>批准超出既定合同的隔离需求</span><span>按 lane 创建、登记、回收</span><span>不得自行创建或切换</span></div>
        <div class="decision-row"><strong>扩范围</strong><span>批准新版合同</span><span>停止当前 lane 并申请变更</span><span>停止并上报，不擅自扩写域</span></div>
        <div class="decision-row"><strong>commit / push</strong><span>对外 push 需明确 grant</span><span>可按合同 commit；push 仅在 grant 内</span><span>禁止 commit/push，只返回文件与验证证据</span></div>
        <div class="decision-row"><strong>PR</strong><span>授予目标仓库与 base 范围</span><span>在有效 grant 内创建/更新</span><span>不创建或更新 PR</span></div>
        <div class="decision-row"><strong>review resolution</strong><span>裁决产品分歧</span><span>逐项记录接受、修复或有据拒绝</span><span>独立 reviewer 只给 disposition 建议</span></div>
        <div class="decision-row"><strong>merge</strong><span>逐次明确授权</span><span>仅在授权、review、CI 都满足时执行</span><span>禁止合并</span></div>
        <div class="decision-row"><strong>receipt</strong><span>验收或要求补证</span><span>签发 done / blocked receipt</span><span>提交本 lane 的证据与未验证项</span></div>
      </div>
      <div class="bento">
        <article class="card span-6"><span class="fragment-alias" id="heading-engineering-6" data-canonical-fragment="外部写入-grant" aria-hidden="true"></span><h3 id="外部写入-grant">外部写入 grant<a class="heading-permalink" data-heading-permalink data-search-exclude href="#外部写入-grant" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p><strong>grant 是提示词层面的授权约定</strong>，不能扩大 Desktop 的沙箱、审批、账号或组织权限。push、PR、评论、发布、merge 等外部写入还必须处于实际权限边界内，并写清 scope、目标 base、允许动作和到期条件；默认不会跨任务继承。</p></article>
        <article class="card span-6 dark-card"><span class="fragment-alias" id="heading-engineering-7" data-canonical-fragment="自动失效" aria-hidden="true"></span><h3 id="自动失效">自动失效<a class="heading-permalink" data-heading-permalink data-search-exclude href="#自动失效" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>scope、base、review 结论或 redaction 要求发生变化，原 grant 立即失效。A3 必须停下，重新展示影响并向 A2 申请授权。</p></article>
      </div>
    </section>

    <section class="section" id="issue-lanes">
      <div class="section-head"><div class="section-title"><p class="section-kicker">Issue 分工</p><span class="fragment-alias" id="heading-engineering-8" data-canonical-fragment="按依赖和写域组织并行" aria-hidden="true"></span><h2 id="按依赖和写域组织并行">按依赖和写域组织并行<a class="heading-permalink" data-heading-permalink data-search-exclude href="#按依赖和写域组织并行" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2></div><p>并行前先确认依赖允许并行、写域互不重叠，且集成点可以验证。多开线程本身不等于并行。</p></div>
      <div class="steps">
        <article class="step"><span class="fragment-alias" id="heading-engineering-9" data-canonical-fragment="contract-lane-串行" aria-hidden="true"></span><h3 id="contract-lane-串行">Contract lane 串行<a class="heading-permalink" data-heading-permalink data-search-exclude href="#contract-lane-串行" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>schema、公开接口、共同数据模型等 contract 变更先完成并合并；所有下游都依赖这一基线。</p></article>
        <article class="step"><span class="fragment-alias" id="heading-engineering-10" data-canonical-fragment="独立-lanes-并行" aria-hidden="true"></span><h3 id="独立-lanes-并行">独立 lanes 并行<a class="heading-permalink" data-heading-permalink data-search-exclude href="#独立-lanes-并行" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>在 contract 稳定后，互不重叠的 docs、frontend、test 可以进入不同 Worktree / subagent 并行执行。</p></article>
        <article class="step"><span class="fragment-alias" id="heading-engineering-11" data-canonical-fragment="更新基线" aria-hidden="true"></span><h3 id="更新基线">更新基线<a class="heading-permalink" data-heading-permalink data-search-exclude href="#更新基线" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>上游合并后，下游先更新 base，核对 diff 是否仍属于原 scope，再重跑本 lane 验证。</p></article>
        <article class="step"><span class="fragment-alias" id="heading-engineering-12" data-canonical-fragment="集成门" aria-hidden="true"></span><h3 id="集成门">集成门<a class="heading-permalink" data-heading-permalink data-search-exclude href="#集成门" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>只有依赖满足、写域无重叠、验证和 review 通过的 lane 才能进入 PR 合并候选。</p></article>
      </div>
      <div class="bento">
        <article class="card span-6"><span class="fragment-alias" id="heading-engineering-13" data-canonical-fragment="可并行示例" aria-hidden="true"></span><h3 id="可并行示例">可并行示例<a class="heading-permalink" data-heading-permalink data-search-exclude href="#可并行示例" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p><code>contract</code> 先串行；其合并后，<code>docs</code>、<code>frontend</code>、<code>test</code> 各自拥有不重叠文件集合，可同时推进。</p></article>
        <article class="card span-6 dark-card"><span class="fragment-alias" id="heading-engineering-14" data-canonical-fragment="失败停止" aria-hidden="true"></span><h3 id="失败停止">失败停止<a class="heading-permalink" data-heading-permalink data-search-exclude href="#失败停止" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>测试失败回 implementation；写域重叠或依赖不清回 issue slicing；依赖暂不可满足则回退该 lane，或输出带 blocker、已验事实和解锁条件的 blocked receipt。</p></article>
      </div>
    </section>

    <section class="section" id="independent-review">
      <div class="section-head"><div class="section-title"><p class="section-kicker">独立审查</p><span class="fragment-alias" id="heading-engineering-15" data-canonical-fragment="独立-reviewer-合同" aria-hidden="true"></span><h2 id="独立-reviewer-合同">独立 reviewer 合同<a class="heading-permalink" data-heading-permalink data-search-exclude href="#独立-reviewer-合同" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2></div><p>独立 reviewer 必须没有实现该 lane，也不共享该 lane 的写域。其任务是验证约定，不是接管实现；即使换成独立线程，使用相同模型仍可能共享盲点，因此关键安全、数据、权限和发布变更必须由人类审查。</p></div>
      <div class="decision-table">
        <div class="decision-row"><strong>Acceptance contract</strong><span>记录要满足的行为、边界和验证</span><span>固定 review 使用的 base / head</span><span>合同变化即重新审查</span></div>
        <div class="decision-row"><strong>Diff</strong><span>检查实际 diff 和生成产物</span><span>核对无越界文件、无隐藏副作用</span><span>不只依赖实现者摘要</span></div>
        <div class="decision-row"><strong>Disposition</strong><span><code>approve</code> / <code>changes requested</code> / <code>blocked</code></span><span>每项 finding 有证据和严重度</span><span>A3 逐项记录 resolution</span></div>
      </div>
    </section>

    <section class="section" id="team-case" data-case-type="composite" data-case-id="team-delivery-composite">
      <div class="section-head"><div class="section-title"><p class="section-kicker">真实实例</p><span class="fragment-alias" id="heading-engineering-16" data-canonical-fragment="真实实例-历史复合案例" aria-hidden="true"></span><h2 id="真实实例-历史复合案例">真实实例：历史复合案例<a class="heading-permalink" data-heading-permalink data-search-exclude href="#真实实例-历史复合案例" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2><div class="tier-badges"><span class="tier-badge">历史复合案例</span><span class="tier-badge">中等脱敏</span></div></div><p>以下案例由多个可核验片段组成，用来说明完整协作合同；它不声称来自一次连续执行。内容保留工程证据类别，但不包含私人姓名、机器路径、主机或业务代码。</p></div>
      <div class="bento">
        <article class="card span-6"><span class="fragment-alias" id="heading-engineering-17" data-canonical-fragment="请求" aria-hidden="true"></span><h3 id="请求">请求<a class="heading-permalink" data-heading-permalink data-search-exclude href="#请求" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>在 Codex Desktop 中把团队工程规范做成可公开验证的指南页；保持导航和视觉模式，保护既有修改，只改批准的页面，并在授权后才发布。</p></article>
        <article class="card span-6"><span class="fragment-alias" id="heading-engineering-18" data-canonical-fragment="先读" aria-hidden="true"></span><h3 id="先读">先读<a class="heading-permalink" data-heading-permalink data-search-exclude href="#先读" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>按层级读取全局、仓库根目录、目标目录的 <code>AGENTS.md</code>，再读 README、目标 HTML、共享样式、验证脚本与生成上下文；最近规则优先，生成上下文只作索引并检查漂移。</p></article>
        <article class="card span-4"><span class="fragment-alias" id="heading-engineering-19" data-canonical-fragment="角色" aria-hidden="true"></span><h3 id="角色">角色<a class="heading-permalink" data-heading-permalink data-search-exclude href="#角色" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>A2 批准 Product Contract 与 merge；A3 维护统一计划和依赖图；A4 分别承担隔离实现、只读验证和独立 review。</p></article>
        <article class="card span-4"><span class="fragment-alias" id="heading-engineering-20" data-canonical-fragment="边界-文件" aria-hidden="true"></span><h3 id="边界-文件">边界 / 文件<a class="heading-permalink" data-heading-permalink data-search-exclude href="#边界-文件" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>写域仅含目标指南页。共享 CSS、脚本、导航结构、生成上下文和敏感路径均为只读；证书、环境文件与本地凭据不读取、不回显。</p></article>
        <article class="card span-4"><span class="fragment-alias" id="heading-engineering-21" data-canonical-fragment="脏主保护" aria-hidden="true"></span><h3 id="脏主保护">脏主保护<a class="heading-permalink" data-heading-permalink data-search-exclude href="#脏主保护" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>预检发现主工作区已有未提交修改，因此不清理、不覆盖、不借用该写域；实现转入登记过的隔离 Worktree，并保留原工作区状态证据。</p></article>
      </div>
      <div class="content-block">
        <p class="section-kicker">完成 Goal</p>
        <span class="fragment-alias" id="heading-engineering-22" data-canonical-fragment="完整-goal" aria-hidden="true"></span><h2 id="完整-goal">完整 Goal<a class="heading-permalink" data-heading-permalink data-search-exclude href="#完整-goal" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2>
        <pre><code>Objective:
建立中文优先、Codex Desktop 优先的团队协作规范主页面，并可在主分支公开验证。

Scope:
- Include: 目标指南页内容、现有组件内的流程图与表格
- Exclude: 公共导航结构、共享 CSS/JS、生成上下文、敏感路径、既有脏修改

Acceptance:
- 团队流程、A2/A3/A4 权限、issue lanes、独立 review、历史复合案例齐全
- 所有失败门与授权边界可见，短小低风险任务有轻量路径

Validation:
- 静态站点检查通过
- diff 仅含目标页
- Mermaid 有邻接文字等价版；无 Mermaid 时仍可读
- PR review 与 CI 通过；合并后复验主分支和公开页面

Artifacts:
- 目标页面、PR、独立 review 记录、CI 结果、done 或 blocked task receipt

Stop Conditions:
- Product Contract 未批准、计划不 ready、写域重叠、敏感路径风险
- 验证失败、review changes、CI red、merge 未授权或主分支验证失败</code></pre>
      </div>
      <div class="bento">
        <article class="card span-4"><span class="fragment-alias" id="heading-engineering-23" data-canonical-fragment="分工" aria-hidden="true"></span><h3 id="分工">分工<a class="heading-permalink" data-heading-permalink data-search-exclude href="#分工" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>contract lane 先串行；合并后 docs、frontend、test 按不重叠写域并行。每个下游更新 base 后重跑验证，A3 只整合已满足依赖的结果。</p></article>
        <article class="card span-4"><span class="fragment-alias" id="heading-engineering-24" data-canonical-fragment="验证证据" aria-hidden="true"></span><h3 id="验证证据">验证证据<a class="heading-permalink" data-heading-permalink data-search-exclude href="#验证证据" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>记录目标锚点、静态检查输出、仅目标页的 diff、无脚本渲染时的文字可读性、独立 reviewer disposition、PR checks 与合并后页面抽样。</p></article>
        <article class="card span-4"><span class="fragment-alias" id="heading-engineering-25" data-canonical-fragment="独立-review" aria-hidden="true"></span><h3 id="独立-review">独立 review<a class="heading-permalink" data-heading-permalink data-search-exclude href="#独立-review" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>reviewer 未参与实现且无该 lane 写权限；固定 acceptance contract 与 diff，逐项给出 approve、changes requested 或 blocked，并记录 resolution。</p></article>
        <article class="card span-4"><span class="fragment-alias" id="heading-engineering-26" data-canonical-fragment="重要恢复" aria-hidden="true"></span><h3 id="重要恢复">重要恢复<a class="heading-permalink" data-heading-permalink data-search-exclude href="#重要恢复" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>历史片段证明主工作区既有修改必须保留。教学组合中的恢复规则是：若下游 base 过期，就停下更新基线、复核 scope 并重跑验证；仍失败则回 implementation，不把这一条件分支冒充已发生事件。</p></article>
        <article class="card span-4"><span class="fragment-alias" id="heading-engineering-27" data-canonical-fragment="结果-receipt" aria-hidden="true"></span><h3 id="结果-receipt">结果 / receipt<a class="heading-permalink" data-heading-permalink data-search-exclude href="#结果-receipt" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>公开记录支持 PR、验证与默认分支合并已完成。教学组合另明确授权规则：push/创建 PR 的 grant 不覆盖 merge；只有在 review 与 CI 通过后展示最终证据并取得独立 merge 授权，才可合并和签发 receipt。</p></article>
        <article class="card span-4 dark-card"><span class="fragment-alias" id="heading-engineering-28" data-canonical-fragment="失败停止-2" aria-hidden="true"></span><h3 id="失败停止-2">失败停止<a class="heading-permalink" data-heading-permalink data-search-exclude href="#失败停止-2" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>任何合同驳回、计划缺口、依赖阻塞、越界写入、敏感信息风险、review changes、CI red、未授权 merge 或最终验证失败都停止；无法立即恢复时给 blocked receipt。</p></article>
        <article class="card span-12"><span class="fragment-alias" id="heading-engineering-29" data-canonical-fragment="来源分类" aria-hidden="true"></span><h3 id="来源分类">来源分类<a class="heading-permalink" data-heading-permalink data-search-exclude href="#来源分类" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p><strong>可核验仓库片段：</strong>指令层级、生成上下文、dirty 检出、diff 与测试日志。<strong>可核验协作片段：</strong>issue 依赖、Worktree 登记、review disposition、PR/CI/merge 状态。<strong>教学性组合：</strong>为说明端到端合同而重排这些片段；不表示它们发生在同一任务或同一时间线上。</p></article>
      </div>
    </section>

    <section class="section" id="api-endpoint-case" data-case-type="demo" data-case-id="api-rate-limit-fix">
      <div class="section-head"><div class="section-title"><p class="section-kicker">真实实例</p><span class="fragment-alias" id="heading-engineering-29a" data-canonical-fragment="真实实例-修复-api-429-限流" aria-hidden="true"></span><h2 id="真实实例-修复-api-429-限流">真实实例：修复 API 429 限流<a class="heading-permalink" data-heading-permalink data-search-exclude href="#真实实例-修复-api-429-限流" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2><div class="tier-badges"><span class="tier-badge">演示场景</span></div></div><p>工程团队常见任务：公开 REST API 在 burst 流量下返回 429。Codex 先澄清验收标准，再只改 rate limit 中间件和对应测试。</p></div>
      <div class="bento">
        <article class="card span-4"><h3 id="api-start">起始状态<a class="heading-permalink" data-heading-permalink data-search-exclude href="#api-start" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>集成测试 <code>test_rate_limit_burst</code> 失败；生产日志显示 429 过早触发；主分支已有无关 dirty 文件需排除在写域外。</p></article>
        <article class="card span-4"><h3 id="api-prompt">Prompt<a class="heading-permalink" data-heading-permalink data-search-exclude href="#api-prompt" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><pre><code>Objective: 修复 burst 场景 429，保持正常用户不受影响。
Scope: middleware/rate_limit.py 与 tests/integration/test_rate_limit_burst.py
Validation: pytest tests/integration/test_rate_limit_burst.py
Stop: 若需改数据库 schema 或公共 contract，先输出 blocked receipt。</code></pre></article>
        <article class="card span-4"><h3 id="api-approval">审批边界<a class="heading-permalink" data-heading-permalink data-search-exclude href="#api-approval" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>允许改 middleware 和测试；禁止改 billing、auth 或部署配置，除非用户追加 grant。</p></article>
        <article class="card span-4"><h3 id="api-result">可观察结果<a class="heading-permalink" data-heading-permalink data-search-exclude href="#api-result" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>目标测试 pass；p95 延迟无显著回归；PR diff 仅含限流模块。</p></article>
        <article class="card span-4"><h3 id="api-recovery">失败恢复<a class="heading-permalink" data-heading-permalink data-search-exclude href="#api-recovery" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>若 baseline 测试环境缺 Redis，停止并报告环境 blocker，不伪造通过结果。</p></article>
        <article class="card span-4"><h3 id="api-verify">验证证据<a class="heading-permalink" data-heading-permalink data-search-exclude href="#api-verify" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>pytest 输出、diff stat、reviewer 对 contract 未变的确认；本项目没有该 API 仓库的执行记录，因此标为演示场景。</p></article>
      </div>
    </section>
  </main>
<!-- guide:shell-close:start -->
<nav class="page-sequence" aria-label="前后页"><a rel="prev" href="daily-workflow.html">← 日常</a><a rel="next" href="research.html">学术 →</a></nav></div></div>
<!-- guide:shell-close:end -->
  <footer class="footer"><p><strong>团队协作规范</strong><br>同一份合同、隔离写域、独立 review、授权合并、证据回执。</p><a class="button" href="research.html">下一页：学术 flow</a></footer>
  <!-- guide:runtime:start -->
<script src="https://cdn.jsdelivr.net/npm/mermaid@11.14.0/dist/mermaid.min.js" integrity="sha384-1CMXl090wj8Dd6YfnzSQUOgWbE6suWCaenYG7pox5AX7apTpY3PmJMeS2oPql4Gk" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
<script src="assets/site.js"></script>
<!-- guide:runtime:end -->
</body>
</html>