深入解析：工程循环

工程循环

工程循环是五层框架的连接组织------它是一个可重复、可验证的循环，能将模糊的想法转化为经过测试、已提交且有文档记录的产物。与提示词系统（单轮指令）、技能系统（可复用能力）或质量门禁（自动执行）不同，工程循环负责编排这些层级如何按顺序交互：定义、计划、执行、验证、提交和保留。本页将拆解该循环，将其映射到代码库的实际命令与约定中，并展示每一步如何作为下一步的门禁。

上下文中的循环：五层定位

工程循环并不取代其他四个层级中的任何一个------它负责编排它们。单次循环迭代可能会调用一个或多个提示词，激活零个或多个技能，并且始终在关闭前终止于某个质量门禁。

该循环的显著特征是闭环：每次迭代都必须产生一个可验证的产物（一次提交、一个测试结果或一次文档更新），才能被视为完成。这正是区分"氛围编程"与"氛围闲聊"的关键所在。

九步开发流

该代码库在 **docs/workflow/README.md**中定义了标准的九步开发流。每一步都有明确的输入、操作和验证标准。该流程的设计初衷是可执行、可检查且可重复的------而非一次性日志。

步骤	操作	门禁 / 验证	关键命令
① 明确目标	书写要做的事、不做的事以及成功标准	同行或自我审查目标清晰度	---
② 读取上下文	阅读 README、AGENTS、目录文档及现有实现	所有引用的文件均存在且为最新	---
③ 制定计划	将任务分解为细粒度、可验证的子步骤	计划在执行前经过审查	---
④ 执行修改	以最小爆炸半径修改文件；禁止顺带重构	未触碰无关文件	---
⑤ 运行门禁	至少运行 `make test`；按需增加领域专项检查	所有检查通过（退出码为 0）	`make test`
⑥ 检查差异	确认差异中无临时文件、密钥或无关变更	干净且有意为之的差异	`git diff`
⑦ 控制版本	使用标记里程碑的语义化消息进行提交	提交存在于本地日志中	`git commit -m "..."`
⑧ 推送远端	推送至 `develop`；观察 GitHub Actions 结果	远端 CI 显示绿色通过	`git push origin develop`
⑨ 同步文档	若有结构性变更，则更新 README、AGENTS 及相关索引	`make check-doc-structure` 通过	`make sync-doc-toc`

黄金路径：规范化的循环入口

AGENTS.md文件将循环提炼为一条黄金路径------一段可直接复制粘贴的命令序列，代表了循环执行的最小可行性形态。这是本代码库中每个 AI Agent 都必须遵循的基线。

bash 复制代码

git pull --rebase origin develop
 
# 2. Init submodules
git submodule update --init --recursive
 
# 3. Pre-flight lint
make lint
 
# 4. Execute task (your changes here)
# ...
 
# 5. Post-flight lint
make lint
 
# 6. Commit
git add -A
git commit -m "feat|fix|docs|chore: scope - summary"
git push origin develop

循环内的人机分工

工程循环并非全自动化------它是人类决策者与 AI 执行者之间的协作循环。明确每一步的所有权对于避免微观管理与不受控的自治至关重要。

循环阶段	人类 (决策者)	AI (执行者)	机器门禁 (门禁)
定义目标	✅ 陈述做什么、不做什么及成功标准	读取上下文，澄清歧义	---
读取上下文	✅ 确认范围边界	扫描 README、AGENTS、代码库	---
制定计划	✅ 批准或否决计划	分解为可验证的步骤	---
执行修改	✅ 授权敏感操作	修改文件、运行命令、安装依赖	---
运行验证	✅ 审查差异，判断可接受性	收集测试输出，格式化证据	`make test`
提交版本	✅ 确认提交消息	暂存文件，草拟消息	`make lint`
推送远端	✅ 观察 CI，决定是否回退	推送至远端	GitHub Actions CI
同步文档	✅ 验证结构准确性	更新 README、AGENTS 及索引	`make sync-doc-toc`、`make check-doc-structure`

核心原则是：人类决定"做什么"和"是否做"；AI 决定"怎么做"；机器强制执行"是否真的管用"。这种三方分工确保了没有任何一方可以自我证明其正确性。

质量门禁：循环的硬化点

步骤 ⑤（运行门禁）和步骤 ⑧（推送远端）是循环的两个硬性检查点。该代码库提供了一个分层门禁系统，从本地检查逐步升级到远端 CI。

本地门禁 (`make test`)

Makefile 中的 make test 目标链式执行了七项顺序检查，每项针对不同的质量维度：

检查项	脚本	捕获问题
`make lint`	`npx markdownlint-cli@0.48.0`	Markdown 格式违规
`make check-links`	`scripts/check-local-links.py`	损坏的相对链接与锚点
`make check-details`	`scripts/check-markdown-details.py`	格式错误的 `<details>/<summary>` 块
`make check-doc-structure`	`scripts/check-doc-structure.py`	章节顺序错误、重复锚点、缺失目录项
`make check-directory-docs`	`scripts/check-directory-docs.py`	目录中缺失 README/AGENTS 配对
`make check-metadata`	`scripts/check-metadata.py`	元数据中的过期路径或锚点
`make check-ai-citation`	`scripts/check-ai-citation.py`	AI 引用语料库中的无效路径

远端门禁 (GitHub Actions CI)

在向 develop/master 推送或发起 PR 时，GitHub Actions 会运行相同的检查，并额外运行外部链接检查器。如果任何检查失败，循环将被阻塞------直到门禁通过，该迭代才算闭环。

💡：提交前绝不能跳过 make test。 CI 会在远端运行相同的检查，但远端 CI 失败会浪费一次往返时间并阻塞协作者。在推送前于本地运行 make test 以快速失败并迭代。

知识沉淀：闭环收尾

步骤 ⑨（同步文档）是区分工程循环与工程流水线的关键。流水线从起点走向终点；而循环会将其输出反馈给系统，从而使下一次迭代从更高的基线启动。

该代码库通过**AGENTS.md**中的强制同步规则来执行这一点：

任何功能/命令/配置/目录/工作流变化必须同步更新： README.md、AGENTS.md

这创造了一种飞轮效应：

每一次闭环完成都会增加代码库的持续上下文 ------即那些使未来循环更快、更可靠的文档、测试与约定。这也是与技能系统在概念上的联系：在多次循环中反复出现的模式，便成为了被提取为可复用技能的候选者。

💡：将每次完成的循环都视为潜在的技能。如果你发现自己在多个任务中重复相同的步骤序列，那么该序列就是一个等待被正式化的技能。参见 Auto-Skill Meta-Skill 了解提取工作流。

递归自优化连接

工程循环是哲学层中描述的递归自优化系统概念在操作层面的实例化。该形式化模型定义了两个角色------生成器（α）与优化器（Ω）------它们递归地相互改进。在工程循环中：

生成器是任务执行阶段（步骤 ①--④）：它产出产物。

优化器是验证与文档化阶段（步骤 ⑤--⑨）：它评估、纠正并保留改进。

递归更新发生在保留的知识（文档、测试、CI 配置）反馈到下一次迭代的上下文（步骤 ②）时，从而抬高质量底线。

这并非比喻------这正是代码库质量基线随时间提升的确切机制：每次循环都会增加约束、检查和文档，进而约束下一次循环的失败模式。

反模式：循环是如何断裂的

理解失败模式与理解理想路径同等重要。以下是工程循环退化或彻底断裂的最常见方式：

反模式	症状	根本原因	修复方法
跳过并推送	远端 CI 失败；协作者被阻塞	提交前跳过了 `make test`	每次推送前在本地运行 `make test`
范围蔓延	单次提交触碰 20+ 个无关文件	未定义目标（跳过步骤 ①）	在触碰文件前先书写要做与不做的事
文档偏移	README 描述了不再存在的功能	步骤 ⑨ 被跳过或被视为可选	将文档同步视为硬性门禁，而非锦上添花
自我背书	AI 声称"所有测试通过"但实际并未运行	人类轻信口头保证而非机器输出	只信任 `make test` 的退出码 0，而非 AI 的总结
上下文丢失	新会话中的 AI 重新实现已解决的问题	结构性变更后未更新 AGENTS.md	每次结构性变更后运行 `make sync-doc-toc`
门禁疲劳	门禁被禁用或削弱以"节省时间"	短期速度压力压倒了长期质量	切记：门禁的存在是因为 AI 幻觉才是默认状态

循环指标：如何判断其生效

健康的工程循环具备可衡量的特性。使用这些指标来评估你的工作流是真的在闭环，还是仅仅在空转：

指标	健康信号	不健康信号
提交粒度	每次提交解决一个可验证的关注点	提交捆绑了无关变更
CI 通过率	> 95% 的推送首次尝试即通过	频繁的 CI 失败需要修复-推送的循环
文档新鲜度	`make check-doc-structure` 始终通过	过期的锚点、缺失的目录项
上下文复用	新任务引用现有文档与 AGENTS 规则	每次会话都从零开始
闭环率	> 80% 的已启动任务到达步骤 ⑨	任务在步骤 ④ 或 ⑤ 之后被放弃
技能提取	反复出现的模式被正式化为技能	跨会话重复相同的手动步骤

后续步骤

在理解了工程循环的结构与机制后，以下页面将深入探讨由该循环所编排的相邻层级：

提示词系统 ------ 单轮指令如何输入到步骤 ①（目标定义）与步骤 ③（制定计划）中
技能系统 ------ 可复用能力如何加速步骤 ④（执行修改）与步骤 ⑤（运行门禁）
质量门禁 ------ 用于硬化步骤 ⑤ 与步骤 ⑧ 的自动化检查完整目录
工作流与开发流程 ------ 日常操作的完整程序化参考
Auto-Skill Meta-Skill ------ 如何将反复出现的循环模式提取为正式技能

关于驱动循环设计的概念基础，请参阅问题解决框架与胶水编码哲学。

下一章：质量门禁