企业官网建设流程全解析

• 前端构建
• 构建工具
• 开发工具

在 Farm 仓库的 AI Agent 工具链中，.agents/skills/目录下沉淀了一套面向子代理（subagent）的工程化开发与审查工作流。其中 code-quality-reviewer-prompt.md 是一个专门用于派发"代码质量审查子代理"的提示词模板。本文以该模板为骨架，结合同目录下的SKILL.md、实现者与规范审查模板，以及requesting-code-review、receiving-code-review两个配套技能，完整讲解它的定位、占位符填充方法、专项检查清单与整改闭环，读完可直接在类似的多代理开发流程中落地复用。

一、模板所处的工作流：Subagent 驱动开发的两阶段审查

该模板不是孤立存在的，它是 subagent-driven-development/SKILL.md 所定义的"每个任务独立子代理 + 两阶段审查"流程中的第二道关卡。该技能的核心原则是：

Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration

即每个实现任务派发一个全新的实现者子代理，任务完成后按固定顺序执行两次审查：

1. 规范符合性审查（Spec Compliance Review）——派发 spec-reviewer-prompt.md 中的规范审查者，确认代码"构建了被要求的东西，不多不少"；
2. 代码质量审查（Code Quality Review）——即本文主角，派发 code-quality-reviewer-prompt.md 中的质量审查者，确认代码"构建得好：干净、可测试、可维护"。

模板开篇就明确写死了调用前提：

Only dispatch after spec compliance review passes.

这是一个顺序硬约束：质量审查必须在规范审查通过之后才能启动。SKILL.md的红线清单也把这一点列为不可违反项——"Start code quality review before spec compliance is ✅（wrong order）"。其逻辑是：先保证"做对了事情"，再检查"把事情做好"；如果实现本身偏离了需求，过早的质量审查只会把精力浪费在错误的代码上。

二、为什么需要单独的"代码质量审查"关卡

对照两份审查模板的 Purpose 可以清晰看出职责划分：

规范审查者的模板中有一句著名的警示——"CRITICAL: Do Not Trust the Report"，要求审查者独立阅读代码、逐行比对需求，而不是相信实现者的汇报。而质量审查者则承接其上，把关注点从"对不对"转向"好不好"。

这一分工与 requesting-code-review/SKILL.md 的核心原则"Review early, review often"一脉相承：在每个任务节点设置自动化的审查检查点，避免问题在任务间"级联放大"（catch issues before they cascade）。质量审查专门负责拦截结构性缺陷——职责混乱、难以测试的耦合、偏离计划的文件组织——这些在规范审查中往往不会被发现。

三、模板占位符逐项解析与填充方法

模板主体是一个可直接填充的派发指令块，原文如下：

Task tool (general-purpose): Use template at requesting-code-review/code-reviewer.md DESCRIPTION: [task summary, from implementer's report] PLAN_OR_REQUIREMENTS: Task N from [plan-file] BASE_SHA: [commit before task] HEAD_SHA: [current commit]

其中"Use template at requesting-code-review/code-reviewer.md"指向的是 requesting-code-review/code-reviewer.md——一套更完整、带完整输出格式的代码审查提示词模板。四个占位符的语义如下：

• DESCRIPTION：实现者汇报中的任务摘要，描述"这次改动了什么"。填写时直接摘录实现者子代理的 Report 部分（来自 implementer-prompt.md 规定的报告格式），无需自行重写；
• PLAN_OR_REQUIREMENTS：本次任务对应的计划条目，通常是"Task N from [plan-file]"，给审查者提供判断基准；
• BASE_SHA：任务开始前的提交哈希（审查范围的起点）；
• HEAD_SHA：当前提交哈希（审查范围的终点）。

BASE_SHA 与 HEAD_SHA 共同界定审查的 Git 范围。requesting-code-review/SKILL.md给出了获取方式：

BASE_SHA=$(git rev-parse HEAD~1) # or origin/main HEAD_SHA=$(git rev-parse HEAD)

审查者拿到范围后会执行git diff --stat {BASE_SHA}..{HEAD_SHA}与git diff {BASE_SHA}..{HEAD_SHA}来查看实际改动（见 code-reviewer.md）。在 Subagent 驱动的流程中，控制器（controller）负责在每次审查前取回这两个 SHA，再连同前两个占位符一起注入模板。

四、四项专项检查清单：质量审查的"加分题"

模板在"标准代码质量关注点（standard code quality concerns）"之外，为审查者额外指定了四条与本工作流强相关的检查项。它们全部围绕一个核心命题：这次改动是否以可维护的方式扩展了代码库。

4.1 每个文件是否有单一清晰职责与定义良好的接口

Does each file have one clear responsibility with a well-defined interface?

这条与实现者提示词中的"Code Organization"要求形成双向呼应。实现者被要求"Each file should have one clear responsibility with a well-defined interface"（见 implementer-prompt.md），审查者则负责核实实现者是否真的做到了。判定信号包括：文件是否能用一个短句说清职责；对外暴露的函数/类签名是否稳定、自解释；是否有多个互不相干的关注点挤在同一个文件中。

4.2 单元是否被分解到可独立理解与测试

Are units decomposed so they can be understood and tested independently?

可测试性在这里被当作可理解性的代理指标：如果一个单元必须连同大量无关上下文才能理解，或者无法脱离外部状态单独测试，就说明分解粒度不合格。这条检查在实践中常转化为"是否存在难以构造测试环境的函数""测试是否必须 mock 掉半个系统才能运行"等问题。

4.3 实现是否遵循计划中的文件结构

Is the implementation following the file structure from the plan?

Subagent 驱动开发的前提是有一份事先写好的实现计划（由writing-plans技能产出）。计划通常会规定文件结构与放置位置。实现者被明确要求"Follow the file structure defined in the plan"，并且"don't split files on your own without plan guidance"。质量审查者负责检查这一纪律是否被遵守——偏离计划的文件组织本身就是需要标记的质量问题，哪怕代码逻辑正确。

4.4 新增文件是否过大、是否显著膨胀既有文件

Did this implementation create new files that are already large, or significantly grow existing files? (Don't flag pre-existing file sizes — focus on what this change contributed.)

这是最微妙的一条，模板特意用括号补充了判定边界：不要标记既有的文件大小，只关注本次改动贡献的部分。也就是说，审查者不能因为"这个文件本来就很长"而开问题单，但必须指出"这次改动让一个本来健康的文件膨胀到难以维护"或"新文件出生即臃肿"的情况。这与实现者提示词中的另一条规则对齐：如果实现者创建的文件超出计划意图，应停止并报告DONE_WITH_CONCERNS，而不是擅自拆分。

五、审查者的输出规范：Strengths / Issues / Assessment

模板规定质量审查者必须返回三部分内容：

Code reviewer returns:Strengths, Issues (Critical/Important/Minor), Assessment

requesting-code-review/code-reviewer.md把这套输出规范扩展成了完整结构：

• Strengths：先说做得好的一面，且要具体。校准原则（Calibration）明确指出"accurate praise helps the implementer trust the rest of the feedback"——准确的肯定能让实现者信任后续的批评；
• Issues（Critical / Important / Minor）：按真实严重度分级。Critical 指 bug、安全问题、数据丢失风险、功能破坏；Important 指架构问题、缺失功能、糟糕的错误处理、测试缺口；Minor 指代码风格、优化机会、文档打磨。每条问题必须给出file:line定位、问题是什么、为什么重要、如何修复；
• Assessment：给出明确结论——"Ready to merge? Yes | No | With fixes"，并附 1～2 句技术性理由。

该模板还立了四条审查纪律：按真实严重度分级、具体到file:line而非泛泛而谈、解释每条问题"为什么重要"、承认优点并给出明确裁决；同时明确禁止"没看代码就说 looks good"、把吹毛求疵标成 Critical、以及给没有读过的代码提意见。

code-reviewer.md中的示例输出可以直观感受这套格式：

### Strengths - Clean database schema with proper migrations (db.ts:15-42) - Comprehensive test coverage (18 tests, all edge cases) ### Issues #### Important 1. **Missing help text in CLI wrapper** - File: index-conversations:1-31 - Issue: No --help flag, users won't discover --concurrency - Fix: Add --help case with usage examples ### Assessment **Ready to merge: With fixes** **Reasoning:** Core implementation is solid with good architecture and tests. Important issues (help text, date validation) are easily fixed and don't affect core functionality.

六、整改闭环：从审查发现到任务验收

质量审查发现的问题不会停留在报告里，SKILL.md定义的每任务循环是：

Dispatch code quality reviewer subagent → Code quality reviewer approves? (yes/no) → 若 no：implementer fixes quality issues → 再次派发质量审查（re-review） → 若 yes：Mark task complete in TodoWrite

三个关键纪律：

1. 由同一个实现者修复：审查发现问题后，由原实现者子代理修复，而不是控制器手动改（"Don't try to fix manually — context pollution"）；
2. 修复后必须复审：不得跳过 re-review，"Reviewer found issues = implementer fixes = review again"是强制循环；
3. 存在未修复问题不得推进下一任务：任一审查存在未关闭的问题，都不能开始下一个任务。

而在实现者一侧，接收审查反馈也有配套方法论——receiving-code-review/SKILL.md 强调"Verify before implementing. Ask before assuming. Technical correctness over social comfort"：先完整阅读反馈，用自己的话复述需求，对照代码库现实核实，判断该建议对当前代码库是否技术上成立，然后要么技术性确认要么有理有据地反驳；禁止表演式附和（如"You're absolutely right!"）和未经核实的盲目照做。审查反馈是"待评估的建议，而非必须服从的命令"。

此外，SKILL.md的示例工作流还展示了闭环的最后一环：所有任务完成后，再派发一次针对整个实现（entire implementation）的最终代码审查，确认"All requirements met, ready to merge"，之后才进入finishing-a-development-branch收尾流程。

七、使用该模板的纪律与红线

结合 SKILL.md 的红旗清单，围绕该模板的硬性纪律可以归纳为：

• 顺序不可颠倒：规范审查未通过（✅）前，禁止启动代码质量审查；
• 审查不可跳过：规范审查和代码质量审查两者缺一不可，实现者的自审（self-review）不能替代真实审查——模板在 implementer-prompt.md 中要求实现者回报前自审，但SKILL.md明确"Let implementer self-review replace actual review（both are needed）"是红线；
• 未修复问题不得放行：不得带着未修复的问题进入下一任务，不得接受规范审查上的"差不多就行"；
• 不可并行派发多个实现者：实现任务只能串行，避免文件冲突；审查任务本身则相对独立，必要时可参照 dispatching-parallel-agents/SKILL.md 的独立性判定决定是否并行；
• 实现者的状态必须被认真对待：DONE直接进入规范审查；DONE_WITH_CONCERNS先阅读疑虑再决定；NEEDS_CONTEXT补上下文后重派；BLOCKED必须更换策略（补上下文、换更强的模型、拆分任务或上报人类），绝不无视升级或原样强制重试。

在模型选择上，SKILL.md的建议是：机械性实现任务用便宜快速的模型，集成与判断类任务用标准模型，而架构、设计与审查类任务用可用的最强模型——代码质量审查显然属于后者，因为单文件职责判定、分解粒度评估与文件膨胀判断都依赖对整个代码库的宏观理解。

八、总结

code-quality-reviewer-prompt.md 是一份小而精的工程化模板：它用四个占位符定义了审查任务的派发契约，用四条专项检查清单把"可维护性"翻译成了可操作的问题，用 Strengths / Issues（Critical / Important / Minor）/ Assessment 三段式强制审查者给出分级、具体、有明确结论的输出。它的价值不在于模板本身的行数，而在于它所嵌入的流程——在规范符合性把关之后设置独立的质量关卡，并以"发现 → 修复 → 复审 → 标记完成"的闭环确保每条意见都被真正消化。对于任何在 AI Agent 工作流中实施多子代理开发与代码评审的团队，这套模板与配套技能（requesting-code-review、receiving-code-review、subagent-driven-development）可以直接作为团队知识资产照搬落地，与仓库根目录 AGENTS.md 中声明的工作区级 Agent 工具链共同构成一套完整的工程化协作规范。

• 前端构建
• 构建工具
• 开发工具