企业官网建设流程全解析

导读

本文围绕 learn-harness-engineering 仓库中日文版 AGENTS.md 模板（docs/ja/resources/openai-advanced/repo-template/AGENTS.md）展开，讲解如何为长时间运行的编码 Agent 设计一份"短而准"的 AGENTS.md：它不作为巨型指令转储，而是充当指向仓库各系统文档的路由层，配合启动工作流、路由映射、工作契约、完成定义与会话结束例程，让 Agent 每次会话都能以一致状态启动、在边界内工作、凭可执行证据收尾。读完本文，你将掌握该模板的完整设计骨架，并看到它在 harness-creator skill 模板与projects/project-01/solution/AGENTS.md实际项目中的落地形态。

一、为什么 AGENTS.md 必须是"路由层"而不是"指令转储"

模板开篇即点明核心设计哲学：

このリポジトリは長時間実行されるコーディングエージェントの作業に最適化されています。このファイルは短く保ち、巨大な指示のダンプではなく、記録のシステム文書へのルーティング層として使用してください。

翻译过来就是：仓库是为长时间运行的编码 Agent 优化的；AGENTS.md 应保持简短，不是巨型指令堆，而是通向"记录系统（system of record）"文档的路由层。

这与本仓库课程的论证一脉相承。docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/专门讨论"为什么单个巨型指令文件会失败"：把全部规则塞进一个文件，会稀释 Agent 的注意力、超过上下文预算、且难以增量维护。SKILL.md 中 Harness Creator 的设计规则也明确写着：

• Keep the root instruction file short: routing and invariants, not a full manual.（根指令文件保持精简：只放路由与不变式，而非完整手册。）
• Put project facts in project docs, not in the skill.（项目事实放进项目文档，不要堆进 skill 文件。）

因此 AGENTS.md 的正确职责只有三件事：

1. 路由：告诉 Agent "要看系统状态去哪个文件、要看设计决策去哪个文件"；
2. 不变式：跨会话恒成立的硬规则（工作契约、完成定义）；
3. 生命周期钩子：启动前做什么、结束时做什么。

而架构细节、质量评分、产品规格等"项目事实"，一律下沉到独立文档，由路由映射表索引。

二、スタートアップワークフロー：写代码前的 7 步启动路径

模板要求 Agent 在修改任何代码之前按序完成以下步骤（这是防止"状态不一致就开工"的第一道闸门）：

1. pwdでリポジトリルートを確認する —— 用pwd确认当前位于仓库根目录；
2. ARCHITECTURE.mdを読む —— 读取架构文档，掌握当前系统映射与严格依赖规则；
3. docs/QUALITY_SCORE.mdを読む —— 读取质量评分，确认哪个领域/层最薄弱；
4. docs/PLANS.mdを読み、作業中のアクティブプランを開く —— 读取计划文档，打开正在进行的活动计划；
5. docs/product-specs/の関連するプロダクト仕様を読む —— 读取相关产品规格；
6. 標準ブートストラップと検証パスを実行する —— 运行仓库标准引导与验证路径；
7. ベースライン検証が失敗している場合、スコープを追加する前にベースラインを修復する ——若基线验证失败，先修复基线，再谈新增范围。

第 7 步是整条工作流的分水岭：它把"环境健康"置于"功能开发"之上，杜绝 Agent 在破损基线上叠加新改动，从而避免"失败堆失败"。

仓库中的对应实现：init.sh 标准验证路径

模板第 6 步所说的"标准引导与验证路径"，在 harness-creator 模板 中落成了一个可复用的init.sh。它的关键设计包括：

• set -e：任何一条验证命令失败立即退出，让基线问题立刻显形；
• 包管理器自动探测：按pnpm-lock.yaml→yarn.lock→bun.lock/bun.lockb→ 默认npm的顺序识别项目所用的包管理器，再执行对应安装命令；
• npm scripts 探测式执行：用node -e读取package.json的scripts，按check→typecheck→type-check的优先级运行类型检查，随后依次尝试lint、test、build；
• 多语言支持：对pyproject.toml/requirements.txt跑pytest与compileall，对go.mod跑go test，对Cargo.toml跑cargo test，对pom.xml/build.gradle/*.csproj分别走 Maven/Gradle/dotnet；
• 友好收尾：验证完成后打印 "Next steps"，提醒 Agent 去读feature_list.json、只挑一个未完成功能、实现后重新验证再宣称完成。

实际项目中的范例可见 projects/project-01/solution/AGENTS.md，其启动规则同样要求"先读本文件 → 读docs/ARCHITECTURE.md→ 读docs/PRODUCT.md→ 跑bash init.sh→ 读feature_list.json"，且明确：If it fails, fix build errors before proceeding（失败就先修，再继续）。

三、ルーティングマップ：一份索引式文档清单

模板用一张路由映射表，把"何时该读哪个文件"固化成了机器可执行的查表逻辑：

这张表的本质是**"记录系统"的目录**：Agent 不需要靠记忆或聊天历史猜测项目状态，任何时刻都能按表定位到权威来源。这与 SKILL.md 提出的五子系统模型（skills/harness-creator/SKILL.md）严格对应：

路由映射表中的每个文档，都是这五个子系统在"记录系统"中的落点。

四、ワーキングコントラクト：Agent 必须遵守的六条工作契约

模板以契约条款形式定义了 Agent 日常工作的硬性约束，每一条都直指本仓库课程中反复出现的 Agent 失败模式：

1. 一度に一つの境界付けられたプランまたはフィーチャースライスから作業する—— 一次只做一个有边界的计划或功能切片。对应"one active feature"设计规则（SKILL.md），防止 Agent 同时推进多个任务导致上下文混乱。
2. コードの検査だけで作業完了とマークしない。実行可能な証拠が必要である—— 仅"看过代码"不算完成，必须提供可执行证据。这对应课程 lecture-09-why-agents-declare-victory-too-early（Agent 过早宣布胜利）与 lecture-10-why-end-to-end-testing-changes-results（端到端测试改变结果）：证据必须是实际运行验证命令的输出，而不是"看起来没问题"的推断。
3. 動作を変更した場合、同じセッションで対応するプロダクト、プラン、または信頼性の文書を更新する—— 改了行为，就在同一会话内更新对应的产品/计划/可靠性文档。这防止"代码改了、文档没改"的漂移。
4. 繰り返しのレビューフィードバックが見られた場合、チャットで再説明するのではなく、機械的なルール、チェック、またはリンターに昇格させる—— 反复出现的评审意见，要升级为机械化规则/检查/链接器，而不是每次在聊天里重新解释一遍。这是"把知识沉淀进仓库而非会话"的关键机制。
5. 生成された素材はdocs/generated/に、ソース参照はdocs/references/に配置する—— 生成物放docs/generated/，源引用放docs/references/，用目录结构区分"机器产物"与"人工参考"。
6. このファイルを肥大化させるのではなく、小さく最新の文書を追加することを優先する—— 优先新增"小而新"的文档，而不是让本文件膨胀，再次呼应"路由层而非指令转储"的哲学。

落地：feature_list.json 作为状态记录系统

契约中"状态"的机器化承载者是feature_list.json。其 JSON Schema（skills/harness-creator/templates/feature-list.schema.json）定义了每个功能条目的结构：

• id：唯一标识，强制^feat-\d+$格式（如feat-001）；
• name、description：功能名称与行为描述；
• dependencies：必须先完成的前置功能 ID 数组——这是范围控制的基础；
• status：枚举not-started/in-progress/blocked/done；
• evidence：状态为done时记录的验证证据。

在 projects/project-01/solution/AGENTS.md 中可以看到它的实际用法：每个功能有"pass"/"fail"/"not-started"三种状态，实现后更新为"pass"并附证据，被阻塞则标"fail"并写明原因，且永不删除功能条目——删除即丢失历史记录。

五、完了の定義：完成 = 五条全部满足

模板给出了一套可判定的"完成定义（Definition of Done）"，杜绝 Agent 的"我感觉完成了"：

一项变更只有在以下全部成立时才被视为完成：

• ターゲット動作が実装されている —— 目标行为已实现；
• 必要な検証が実際に実行された —— 必要验证确实被执行（强调"实际运行"而非假设）；
• 証拠が関連するプランまたは品質文書にリンクされている —— 证据已链接到相关计划或质量文档；
• 影響を受ける文書が最新の状態である —— 受影响的文档已保持最新；
• リポジトリが標準スタートアップパスからクリーンに再起動できる —— 仓库能通过标准启动路径干净重启。

对比模板版 AGENTS.md（skills/harness-creator/templates/agents.md）中的 checklist，可以看到同一逻辑的更轻量表达：

- [ ] Target behavior is implemented - [ ] Required verification actually ran (tests / lint / type-check) - [ ] Evidence recorded in feature_list.json or progress.md - [ ] Repository remains restartable from standard startup path

两条规则殊途同归：实现 + 验证 + 证据 + 文档同步 + 可重启，五者缺一不可。第 5 条尤其重要——它把"完成"与"下一会话能否无缝继续"绑定，这正是课程 lecture-12-why-every-session-must-leave-a-clean-state（每个会话必须留下干净状态）所讨论的核心。

六、セッションの終了：结束会话前的 5 步例程

模板要求 Agent 在结束会话前按序执行：

1. アクティブな実行プランを更新する—— 更新活动执行计划；
2. ドメインやレイヤーに意味のある変更があった場合、docs/QUALITY_SCORE.mdを更新する—— 若领域/层有实质变化，更新质量评分；
3. 債務を先送りした場合、docs/exec-plans/tech-debt-tracker.mdに新しい債務を記録する—— 若延期了技术债，在技术债追踪器中登记；
4. 適切なタイミングで終了したプランをdocs/exec-plans/completed/に移動する—— 将适时结束的计划移入已完成目录；
5. 次のアクションが明確な再起動可能な状態でリポジトリを残す—— 让仓库处于"下一步动作明确、可重启"的状态。

这套例程的核心目标是：下一个会话打开仓库时，不需要任何口头交接也能知道"现在做到哪、接下来做什么"。会话产生的所有认知增量——计划状态、质量评分、技术债、完成记录——都必须写回"记录系统"，而不是留在 Agent 的上下文窗口里（上下文窗口在会话结束后即丢失，这正是 lecture-05-why-long-running-tasks-lose-continuity 讲的问题）。

配套状态文件：progress.md 与 session-handoff.md

仓库模板提供了两个配套文件支撑可重启状态：

• progress.md 模板：会话连续性日志，包含当前状态（最后更新时间、活动功能 ID）、已完成/进行中/下一步清单、阻塞与风险、决策记录（含背景与被否决方案）、本次会话修改的文件、完成证据（测试/类型检查/手动验证的命令与输出），以及"给下一会话的笔记"。
• session-handoff.md 模板：面向多会话任务的交接单，包含当前目标、本会话完成项、验证证据表格（检查项/命令/结果/备注）、文件变更、决策、阻塞与风险，以及下一会话启动清单（读 AGENTS.md → 读 feature_list.json 与 progress.md → 复查交接单 → 编辑前先跑 init.sh）。

两者分工：progress.md是持续的会话日志，session-handoff.md是会话间的"接力棒"。实际项目中 projects/project-01/solution/claude-progress.md 即是前者的真实落地。

七、模板在 harness-creator skill 中的完整工作流

将本文讨论的 AGENTS.md 模板放入更大上下文看，它是 Harness Creator skill 五子系统中的Instructions 子系统，与 State（feature_list.json/progress.md）、Verification（init.sh）、Scope（依赖与完成标准）、Lifecycle（session-handoff.md）共同构成一套完整的 harness。Skill 提供了配套自动化：

# 创建 harness（本地仓库） node skills/harness-creator/scripts/create-harness.mjs --target /path/to/project # 审计现有 harness（输出五子系统评分） node skills/harness-creator/scripts/validate-harness.mjs --target /path/to/project # 生成可分享的评估报告 / 运行结构基准 node skills/harness-creator/scripts/render-assessment-html.mjs --target /path/to/project node skills/harness-creator/scripts/run-benchmark.mjs --target /path/to/project --html /path/to/report.html

其中create-harness.mjs支持--agent-file CLAUDE.md、--package-manager npm|pnpm|yarn|bun、--commands "cmd one,cmd two"、--force等选项，会按 agents.md 模板 生成一份带占位符的 AGENTS.md。Skill 的设计规则与本文模板完全一致：根指令文件只放路由与不变式、验证命令显式可运行、要求证据后才标记完成、一次只激活一个功能、优先追加状态文件而非依赖聊天历史、脚本不隐藏破坏性行为（覆盖需用户明确批准）。

八、总结：把 AGENTS.md 当作"会话操作系统"的路由层

这份日文版 AGENTS.md 模板的完整价值可以概括为一句话：它把"长时间运行 Agent 的可靠性"从提示词技巧，转译成了仓库结构约定。启动工作流保证每次会话从一致基线出发；路由映射让"记录系统"可被机器定位；工作契约约束行为边界；完成定义把"完成"变成可判定的五元组；会话结束例程确保认知增量全部落盘。五个部分环环相扣，最终目标与模板结尾一致——次のアクションが明確な再起動可能な状態でリポジトリを残す（留下下一步动作明确、可重启的仓库状态）。

如果要在自己的项目里实践这套设计，可以直接复用仓库中的现成资产：agents.md 模板（本模板的英文轻量版）、init.sh 模板、feature-list schema、progress.md 模板 与 session-handoff.md 模板，再参考 project-01 的 solution 目录 看它们如何组合成一份真实可用的 AGENTS.md。