KO
|
EN
gitlite — search
Search
#javascript
#python
#hacktoberfest
#react
#ai
#typescript
#llm
#go
#golang
#android
#machine-learning
#rust
#deep-learning
#linux
meta-project-poc
★ 17
Open GitHub ↗
元工程的poc程序
Download README (.md)
Explore Similar Repositories
chai-gpt-build
:
No description available.
ShareClean
:
Local-first Python CLI for safer log sharing: redact secrets, tokens, emails, and local paths before posting to GitHub issues, tickets, or AI chats.
ai-accelerator-C8
:
No description available.
dream-team-for-microsoft-scout
:
Your own team of eight AI digital employees, running locally on Microsoft Scout. Windows only.
langchain
:
No description available.
// repository documentation
Was this content helpful?
★ 0
(0 ratings)
Select Rating:
★
★
★
★
★
Submit Feedback
Recent Feedback
×
Download README
Do you want to download the
README.md
file for
meta-project-poc
?
Download (.md)
# Meta-Project Demo (元工程) ## 核心理念 **元工程（Meta-Project）** 是将**软件工程方法论**引入 LLM 驱动的开发流程中，把"人类如何用 AI 构建项目"这一过程本身系统化、自动化、可重演。 它解决的根问题是：**常规 LLM 编程（一次性对话 + 上下文窗口）缺乏结构化、缺乏方法论语境、缺乏多轮改进，导致上下文丢失、任务完成度不可控、质量不稳定。** 元工程不是"用 Agent 写代码"的工具，而是一套**元层（Meta-Layer）** 的工程体系： ``` ┌─────────────────────────────────────────────────────────┐ │ 元工程 (Meta-Project) │ │ │ │ 每个开发阶段导入对应的方法论，在方法论的指导下： │ │ 1. 产出该阶段的关键工件（需求文档、领域模型、架构等） │ │ 2. 以工件为输入，生成 LLM 调用脚本 │ │ 3. 脚本驱动 PDCA 循环（Plan-Do-Check-Act） │ │ 4. 每阶段自动多轮改进，直到达到质量门限 │ │ 5. 差异化利用模型能力：不同阶段用不同模型 │ │ 6. 脚手架机制：固化模式，降低成本，提高确定性 │ │ │ │ ── 宏观由人类/元脚本掌控，微观由 Agent 执行 ── │ └─────────────────────────────────────────────────────────┘ ``` ### 宏观确定性，微观灵活性 元工程的一个核心设计原则是**在宏观层面提供确定性，在微观层面留给 Agent 发挥空间**。这与"给 Agent 一个高层的目标，让它自己发挥到细节"的做法根本不同。 | | 常规 LLM 编程 | "放手式" Agent | 元工程 | |:---|:---|:---|:---| | 宏观（做什么、按什么顺序、用什么方法论） | 由 LLM 自己决定，随上下文漂移 | 由 LLM 自己规划，不可控 | **由元脚本/人类预先定义，确定不变** | | 微观（具体怎么实现一个模块、怎么写一行代码） | 完全由 LLM 决定 | 完全由 Agent 决定 | **由 LLM/Agent 在约束范围内发挥** | 具体来说，以下由元脚本或人类**预先确定**，不交给 Agent 自行决策： - 采用哪些方法论，各在哪个阶段使用 - 每个阶段产出的工件类型和格式 - 阶段之间的流转顺序和门禁条件 - 每个阶段选用哪个模型 - 多轮改进的退出标准（质量门限） 以下留给 LLM/Agent 在范围内**自主发挥**： - 在需求阶段，如何从用户的描述中推导出完整的需求 - 在建模阶段，如何识别实体和聚合 - 在编码阶段，具体的代码实现方式和风格 ### 人工门禁（Human Gate） 元工程在以下关键节点预设**人工介入点（Gate）**，由人类做最终裁决，而非完全自动化： ``` 阶段内： Plan → Do → Check → [Human Review?] → Act ↑ 按配置决定是否暂停等待人工审核 阶段间： [阶段 Artifact 产出] → [Human Gate] → 下一阶段 ↑ 人类审核工件，决定通过/驳回/调整 ``` 每个 Gate 的配置决定了人工介入的深度： | Gate 模式 | 行为 | |:---|:---| | `auto` | 自动通过，不暂停（适用于成熟、低风险环节） | | `review` | 暂停执行，等待人类审核工件后确认继续 | | `review_if` | 条件触发（如：某轮改进后仍未达标，或某个关键指标异常） | | `override` | 人类可以随时介入修改任一步骤的产出 | 这一设计让元工程在**自动化效率**和**人类掌控**之间取得平衡——自动化的归自动化，决策的归人类。 ## 方法论驱动的开发流程 元工程的核心是按**开发阶段**安排相应的**方法论**，每个阶段在该方法论的指导下产出工件。方法论文档作为该阶段 LLM 调用的语境（Context），让 LLM 不再"即兴发挥"，而是遵循成熟工程实践。 ``` 开发阶段 导入的方法论 关键产出 ─────────── ────────────── ───────────────────── 需求分析 Design Thinking 用户画像、问题定义 │ (同理心 → 定义 → 构思) 需求文档、用户故事地图 │ ▼ 领域建模 Domain-Driven Design 领域模型、通用语言 │ (统一语言 → 限界上下文 聚合、实体、值对象、领域事件 │ → 实体/值对象/聚合) │ ▼ 架构设计 DDD + 敏捷架构 上下文映射、分层架构 │ (战略设计 → 战术设计) 模块划分、接口契约 │ ▼ 迭代计划 敏捷开发 (Scrum) Backlog、Sprint 计划 │ (用户故事 → 估算 → 迭代) 验收标准、DoD │ │ ┌──────────┬──────────┬──────────┐ │ ▼ ▼ ▼ ▼ │ Sprint 1 Sprint 2 Sprint 3 ... │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ 编码 + 测试 TDD 可工作的增量 │ (红 → 绿 → 重构) │ │ ▼ 持续改进 敏捷回顾 + 自动化检查 回顾报告、改进措施 (检视 → 调整) 质量门禁报告 ``` ### 阶段详解 #### 阶段 1：需求分析 — Design Thinking Design Thinking 的五阶段模型（Empathize → Define → Ideate → Prototype → Test）中，前三个阶段被引入需求分析： - **Empathize（同理心）**：LLM 根据输入的领域描述，从多视角推导用户/利益相关者的真实需求 - **Define（定义）**：将需求收敛为明确的问题陈述，输出**用户画像**和**问题定义** - **Ideate（构思）**：生成候选方案、用户故事地图、功能优先级 **推荐模型：Gemini**（世界知识丰富，擅长理解业务领域和用户场景） **产出工件**：需求文档、用户故事地图、用户画像、功能优先级矩阵 #### 阶段 2：领域建模 — Domain-Driven Design 以 DDD 的**战略设计**为指导： - **统一语言（Ubiquitous Language）**：建立项目内共享的术语表 - **限界上下文（Bounded Context）**：划分业务边界 - **实体 / 值对象 / 聚合**：识别核心领域概念及其关系 - **领域事件**：建模业务流程中的关键事件 **推荐模型：Gemini**（强世界知识，理解复杂业务概念） **产出工件**：领域模型、统一语言表、限界上下文地图、聚合定义 #### 阶段 3：架构设计 — DDD 战术设计 + 敏捷架构 在领域模型的基础上，进行技术架构决策： - **上下文映射（Context Mapping）**：定义限界上下文之间的通信关系 - **分层架构 / Hexagonal 架构**：确定代码组织结构 - **战术设计**：Repository、Factory、Domain Service、Application Service 等模式 - **接口契约**：模块间 API 定义 **推荐模型：Gemini / Claude**（强推理，长上下文） **产出工件**：架构文档、分层结构、接口定义、模块划分 #### 阶段 4：迭代计划 — 敏捷开发 (Scrum) 将需求拆分为可交付的 Increment： - **用户故事拆分**：按 INVEST 原则 - **估算与优先级**：Story Point / 价值排序 - **Sprint 计划**：确定每个 Sprint 的目标和范围 - **DoD（Definition of Done）**：明确每个任务的完成标准 **产出工件**：Product Backlog、Sprint Backlog、验收标准 #### 阶段 5：编码与测试 — TDD 每个用户故事的实现遵循 TDD 的红-绿-重构循环： 1. **红（Red）**：编写失败的测试 2. **绿（Green）**：编写刚好通过测试的代码 3. **重构（Refactor）**：优化代码质量 4. **Check**：运行所有测试、代码审查 5. **Act**：若未通过，进入下一轮 TDD 循环 **推荐模型：Gemini 2.5 Flash Lite**（高性价比，适合大规模代码/测试生成） **产出工件**：可运行的代码增量、测试套件 #### 阶段 6：持续改进 — 敏捷回顾 + 自动化检查 每个迭代结束后： - **回顾（Retrospective）**：检视流程、识别改进点 - **质量门禁**：自动化检查（lint、测试覆盖率、性能基准） - **改进措施**：调整下一迭代的计划和方法 ## 模型差异化编排 不同模型按能力特点分配到对应阶段： | 阶段 | 模型 | 选型理由 | 调用方式 | |:---|:---|:---|:---| | 需求分析 | Gemini 3.5 Flash | 世界知识丰富，理解业务场景 | Gemini API（Python 直调） | | 领域建模 | Gemini 3.5 Flash | 复杂概念理解 | Gemini API（Python 直调） | | 架构设计 | Gemini 3.5 Flash | 长上下文，强推理 | Gemini API（Python 直调） | | 编码实现 | Gemini 2.5 Flash Lite | 高性价比，代码能力强 | Gemini API（Python 直调） | | Code Review | Gemini 2.5 Flash Lite | 高性价比 | Gemini API（Python 直调） | > Gemini API：`GEMINI_API_KEY=xxx source ~/work/env/gkey && ./run.sh` ## PDCA 循环 每个阶段的任务不是一次性的，而是驱动一个完整的 PDCA 循环： ``` ┌─────────────────────────────────────┐ │ Plan：根据工件 + 方法论制定执行计划 │ └──────────────┬──────────────────────┘ ▼ ┌─────────────────────────────────────┐ │ Do：LLM 生成产出 │ │ (在方法论语境 + 已有工件约束下) │ └──────────────┬──────────────────────┘ ▼ ┌─────────────────────────────────────┐ │ Check：自动评估质量 │ │ (检查清单、测试、静态分析) │ └──────────────┬──────────────────────┘ ▼ ┌─────────────────────────────────────┐ │ [Human Gate?] │ │ 按配置决定是否暂停等待人工审核 │ └──────────────┬──────────────────────┘ ▼ ┌─────────────────────────────────────┐ │ Act：判断是否达标 │ │ ┌─── 是 ──→ [Human Gate?] ──→ 下一阶段│ │ │ │ │ └─── 否 ──→ 下一轮改进 │ │ (携带上一轮评估反馈 │ │ + 人类批注) │ └─────────────────────────────────────┘ ``` 每一轮改进都携带： 1. 上一轮的完整产出 2. 自动评估结果（未通过的检查项） 3. 人类批注（若有） 4. 当前轮次编号（防止无限循环，达到上限时自动挂起等待人类） 这解决了常规 LLM 编程中**"一次生成、不管质量"**和**"上下文窗口溢出导致任务丢失"**的问题。 ## 工作流全景 ``` 设计思维 (Design Thinking) ┌────────────────────────────────────┐ │ Empathize → Define → Ideate │ ← Gemini │ 产出：需求文档、用户故事地图 │ └─────────────────────┬──────────────┘ │ [Human Gate: 需求审核] ▼ DDD (战略设计) ┌────────────────────────────────────┐ │ 统一语言 → 限界上下文 → 聚合 │ ← Gemini │ 产出：领域模型 │ └─────────────────────┬──────────────┘ │ [Human Gate: 模型评审] ▼ DDD (战术设计) + 敏捷架构 ┌────────────────────────────────────┐ │ 上下文映射 → 分层 → 接口契约 │ ← Gemini/Claude │ 产出：架构文档 │ └─────────────────────┬──────────────┘ │ [Human Gate: 架构评审] ▼ 敏捷开发 (Scrum) ┌────────────────────────────────────┐ │ Backlog → Sprint 计划 → DoD │ │ 产出：迭代计划 │ └─────────────────────┬──────────────┘ │ [Human Gate: 计划确认] ▼ ┌─────────────────────┐ │ LLM 调用脚本生成 │ │ (以所有工件为输入) │ └──────────┬──────────┘ ▼ ┌───────────────────────────────┐ │ Sprint 执行 (PDCA × 多轮改进) │ │ │ │ ┌───┐ ┌───┐ ┌───┐ │ │ │TDD│ → │TDD│ → │TDD│ ... │ ← Gemini Lite │ └───┘ └───┘ └───┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ [Gate] [Gate] [Gate] │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ 可运行 可运行 可运行 │ │ 增量1 增量2 增量3 │ └──────────┬────────────────────┘ │ [Human Gate: 增量评审] ▼ 敏捷回顾 + 自动化改进 ``` ## 执行手段 元工程混合使用两种执行手段，按阶段和任务特性选择： | 手段 | 适用场景 | 优点 | 注意 | |:---|:---|:---|:---| | **Gemini API（直接调用）** | 所有阶段（需求、建模、架构、编码、审查） | 精确控制 system instruction、输出格式、模型选择；无额外依赖 | 通过 `lib.py` 的 `gemini_markdown()` / `lite_markdown()` / `tdd_cycle()` 统一管理；内置 3 次重试 + 指数退避 | > **实践发现**：最初设计中使用 `agy CLI` 用于领域建模和架构设计阶段，但 `agy` 在 CI/非交互环境中需要 Google OAuth 交互式认证，无法静默执行。所有阶段最终统一使用 Gemini API 直调，降低了环境依赖。 ### Gemini API 直接调用 所有阶段通过 `meta-scripts/lib.py` 统一调用 Gemini API： ```python # 知识密集型任务（需求、建模、架构）→ Gemini 3.5 Flash gemini_markdown(system, prompt, temperature=0.3) # 性价比敏感任务（编码、审查）→ Gemini 2.5 Flash Lite lite_markdown(system, prompt, temperature=0.3) # TDD 完整循环（红→绿→重构） tdd_cycle(story_id, requirements, api_doc, dod, scaffold) ``` 选择 API 直调而非 Agent CLI 的原因是： 1. 需要注入长篇幅的方法论文档作为 system instruction 2. 输出需要严格结构化（Markdown 表格、固定列头） 3. 不需要文件写入、shell 执行等工具调用能力 4. 避免 OAuth / 环境认证问题 ### 错误重试策略 `lib.py` 中的 `_chat()` 内置了 3 次自动重试 + 指数退避，应对： - **5xx 服务端错误**：Gemini API 临时不可用 - **ConnectionError 连接断开**：网络不稳定导致连接被重置 每次重试等待 `2^attempt` 秒（2s → 4s → 8s），三次失败后抛出最终异常。 ## CI 执行引擎 元工程的执行引擎是 **CI Pipeline**（如 GitHub Actions），一切自动化工作都在 CI 上完成。人类的介入通过 **Git 仓库内的文档** 作为媒介，形成异步的协作循环。 ### 一次完整的 Push 驱动的 PDCA 周期 ``` GitHub Repo 本地环境 ┌─────────────────┐ ┌──────────────┐ │ │ │ │ Push (代码/回答) ──→ 触发 CI Pipeline │ │ 用户 Pull │ │ │ │ │ │ 1. 检查 Gate │ │ 审阅 Gate │ │ 文档状态 │ │ 文档 │ │ 2. 执行元脚本 │ │ │ │ (LLM 调用) │ │ 在文档中 │ │ 3. 生成工件 │ │ 填写回答/ │ │ 4. 运行质量门禁 │ │ 批准/修改 │ │ 5. 生成 Gate │ │ │ │ 文档(含问题) │ │ 本地修改 │ │ 6. Commit & │ │ 代码/工件 │ │ Push 回仓库 │ │ │ │ │ │ git push │ └────────┬────────┘ └──────┬───────┘ │ │ └─────────── 下一轮 ────────────┘ ``` ### 文档即媒介 人类与元工程之间的所有交互都通过仓库内的**结构化 Markdown 文档**完成，而非即时消息或 Web UI。所有阶段产出（需求文档、领域模型、架构设计、代码、审查报告）均为 `.md` 文件，人类可以直接阅读、编辑、批注。 ``` 元工程中的一切文档都是 Markdown： ├── methodology/*.md ← 方法论文档（LLM 调用的语境） ├── artifacts/*/*.md ← 各阶段工件（需求/模型/架构/代码） ├── artifacts/gates/*.md ← Gate 文档（人类决策媒介） └── scaffolding/*.md ← 脚手架模板 ``` #### Gate 文档示例 当一个阶段完成、需要人类介入时，CI 会生成一个 Gate 文档。人类拉取后直接在其中作答： ```markdown # Gate: 需求审核 (GATE-001) ## 状态 ⏳ 待审核 · 由 CI 于 2026-07-03 自动生成 ## 当前工件 - [需求文档](./artifacts/01-requirements/requirements.md) - [用户故事地图](./artifacts/01-requirements/story-map.md) - [用户画像](./artifacts/01-requirements/personas.md) ## 质量门禁报告 | 检查项 | 结果 | 说明 | |:---|:---:|:---| | 完整性 | ✅ 通过 | 覆盖了所有核心角色 | | 一致性 | ⚠️ 警告 | 角色A与角色B的需求有重叠 | | 可测试性 | ✅ 通过 | 每个故事都有验收标准 | ## 待人类决策 ### Q1：需求范围确认 需求文档第 3.2 节定义的 MVP 范围是否准确？ - [ ] 是，可进入下一阶段 - [ ] 否，需调整（请在下方说明） - [ ] 需要补充 [请描述] **人类回答**： <!-- 在此填写 --> ### Q2：警告处理 "角色A与角色B的需求有重叠"——是否应当合并这两个角色？ - [ ] 是，合并为一个角色 - [ ] 否，保持分离，各自独立 - [ ] 暂不处理，记录下来后续迭代 **人类回答**： <!-- 在此填写 --> --- 请在上述问题中勾选并填写回答，保存文件后 `git push`。CI 将读取你的决策并继续。 ``` #### 其他交互文档类型 | 文档类型 | 用途 | 由谁生成 | |:---|:---|:---| | Gate 文档 | 阶段间/多轮改进间暂停，等待人类决策 | CI | | 质量报告 | 展示自动化检查结果，附带改进建议 | CI | | 回滚提案 | 当某轮 PDCA 连续失败后，生成备选方案供人类选择 | CI | | 改进指令 | 人类在任意时刻可以提交的干预指令 | 人类 | ### CI Pipeline 逻辑 ``` on: push jobs: meta-pipeline: steps: 1. Checkout (含所有工件 + Gate 文档) 2. 读取当前状态元文件 (meta-state.json) ├── 当前阶段 (phase: "requirements") ├── 当前轮次 (round: 2) └── 待审核 Gate (pending_gate: "GATE-001") 3. 状态路由: ├── 有待审核 Gate? ──→ 检查人类是否已作答 │ ├── 已作答 ──→ 验证回答 → 通过则继续/驳回则挂起 │ └── 未作答 ──→ 跳过 (等待下次 Push) │ ├── 有失败改进? ──→ 加载反馈 → 执行下一轮改进 → 重新 Check │ └── 正常执行 ──→ 执行当前阶段 PDCA 4. 执行后处理: ├── 更新工件文件 ├── 生成 Gate 文档 (若需人工介入) ├── 更新 meta-state.json ├── git config user.name "meta-bot" ├── git commit -m "meta: phase=requirements round=2 gate=GATE-001" └── git push ``` ### 协作节奏 ``` 时间 ▶ CI 执行 ── Commit & Push ──→ 人类 Pull ── 审阅 ── 修改 ── Push │ ◀── Commit & Push ── CI 执行 ──┘ 继续下一阶段 ``` 这不是实时协作——每个来回都是一次 **异步的、有记录的迭代**。Git 历史本身就是审计日志。 ## 脚手架机制 脚手架（Scaffolding）是元工程中用于**提供确定性、降低成本**的预置模板： - **项目脚手架**：目录结构、构建配置、依赖管理 - **代码脚手架**：分层骨架、DTO/Entity 模板、Repository 实现 - **测试脚手架**：测试框架配置、Mock 模板、Fixture 模板 - **评估脚手架**：Lint 规则、Checklist 模板、Review 模板 脚手架让 LLM 不必从零开始生成大量样板代码，从而**减少 token 消耗**并**降低随机性**。 ## 与常规 LLM 编程的对比 | 维度 | 常规 LLM 编程 | 元工程 | |:---|:---|:---| | 上下文管理 | 单次对话窗口，溢出即丢失 | 分阶段 + 工件化 + PDCA 传递 | | 质量控制 | 一次生成，人工检查 | PDCA 循环 + 自动多轮改进 | | 方法论 | 依赖 LLM 隐含知识 | 按阶段显式导入对应方法论 | | 模型利用 | 单一模型完成所有 | 按阶段差异化编排 | | 可重复性 | 低，每次路径不同 | 高，可重演的工作流 | | 成本 | 返工成本高 | 脚手架 + 分阶段降低总成本 | | 任务完成度 | 上下文一长就丢任务 | 每阶段 PDCA 确保完成 | | **宏观确定性** | **无**（LLM 自己规划路径） | **强**（阶段/方法论/门禁由元脚本预定义，Agent 不越界） | | **人工介入** | 全手动或全自动 | **Gate 机制**：关键节点可配置人工审核，自动化与掌控平衡 | | **执行载体** | 本地对话/IDE 插件 | **CI Pipeline**（Push 驱动，异步文档交互） | | **可追溯性** | 对话历史（无结构） | **Git 历史即审计日志**：每次 Push 记录阶段、轮次、Gate 状态所有变更 | --- ## 实践总结（Lessons Learned） 以下是从首次端到端执行完整流水线中获得的经验，反映了理论设计与实际运行的差异。 ### 1. Agent CLI 的非交互局限 **设计时**：计划用 `agy` CLI 执行领域建模和架构设计阶段，利用其工具调用和多步推理能力。 **实践发现**：`agy` 需要 Google OAuth 交互式认证（弹出一个 URL 让用户访问并粘贴授权码），在 CI 和非交互终端中完全不可用。即使有 `--sandbox` 标志，仍然需要先完成一次交互式登录。 **结论**：在 CI/自动化流水线中，优先选择 **REST API 直调**而非 Agent CLI。如果需要 Agent 的自主能力，应选择提供 API Key 认证、无需 OAuth 的 Agent 服务。 ### 2. 输出拆分策略：分开调用胜于后处理拆分 **设计时**：用一个 API 调用生成多个工件，然后用正则表达式拆分输出到不同文件。 **实践发现**：LLM 的输出格式不稳定——同样的 prompt，Gemini 可能用 `###`、`**`、`---` 或编号列表作为段落分隔符。正则拆分逻辑（按 `^## ` 或 `^### ` 分割）经常匹配不到正确的分割点，导致某些工件文件为空或内容错位。 **结论**：**每个工件文件（如 `product-backlog.md`、`sprint-plan.md`）使用独立的 API 调用**。虽然增加了 API 调用次数，但显著提高了输出可靠性，且每个 prompt 可以精确指定该文件的输出格式（列名、最小行数等）。 ### 3. Prompt 模板的精确性直接影响输出质量 **设计时**：prompt 中给 LLM 宽泛的指令，如"输出需求文档"。 **实践发现**：宽泛指令导致 LLM 输出格式多变——有时用表格，有时用列表，有时用段落。后续的自动化处理（如 check_artifacts）无法适应这种变化。 **结论**：每个 prompt 必须包含： - **精确的 Markdown 表格模板**（含列名和对齐方式） - **最小行数/条数要求**（如"至少 15 个术语"、"至少 8 个 API 端点"） - **角色定义**（"你是 DDD 专家"、"你是 Scrum Master"） ### 4. 网络弹性的重要性 **设计时**：假设 API 调用总是成功。 **实践发现**：Gemini API 在生产环境中会出现间歇性的 `503 Service Unavailable` 和 `ConnectionError`（连接被远程服务器关闭）。一次端到端流水线执行约 20+ 次 API 调用，几乎必然遇到至少一次网络故障。 **结论**：必须内置重试机制。`lib.py` 的 `_chat()` 实现了 3 次自动重试 + 指数退避（`2^attempt` 秒），同时捕获 `HTTPError`（5xx）和 `ConnectionError`（网络断开）。 ### 5. 状态持久化的陷阱 **设计时**：`meta-state.json` 由 Python 脚本在 heredoc 中写入，后续步骤读取。 **实践发现**：bash heredoc 中的 Python 脚本运行在独立的 shell 上下文中，对 `meta-state.json` 的写入在 heredoc 结束时才真正刷盘。如果多个 heredoc 连续执行（如 coding.sh 中的 TDD heredoc + 状态更新 heredoc），第二个 heredoc 可能读到旧的状态。 **结论**：状态更新逻辑应该以**幂等方式**设计，确保即使状态文件被部分写入也能正确恢复。不要在同一个脚本中既产生状态又消费状态——最好让 `run.sh` 在脚本执行完毕后统一读取和更新状态。 ### 6. 人工 Gate 的价值 **设计时**：Gate 文档是 CI 流水线中的"暂停点"。 **实践发现**：Gate 机制非常有效——需求、领域模型、架构阶段的 Gate 文档让人类可以在每个关键节点审阅并修正方向。在实际使用中，Gate 文档以 `review` 模式暂停流水线，人类在文档中勾选"通过"后 CI 继续，形成了流畅的异步协作循环。 **结论**：保守地在高影响阶段配置 `review` 模式（需求、领域模型、架构），低影响阶段配置 `auto` 模式（计划、编码）。随着流水线成熟度提高，可以逐步将更多阶段改为 `auto`。 --- *元工程不是工具，是方法论。这个 Demo 是方法论的一个具体实例。*
