企业官网建设流程全解析

导读：本文围绕 learn-harness-engineering 仓库中《Initializer Agent Playbook》文档展开，讲解在正式增量开发之前，如何通过一次"初始化会话"为仓库建立稳定运行工作面，让后续任何没有前文上下文的 Agent 新会话都能独立回答"仓库做什么、怎么启动、怎么验证、什么未完成、下一步做什么"。文中以本仓库 project-01 的 solution 目录 为真实落点，逐条对照AGENTS.md、CLAUDE.md、feature_list.json、claude-progress.md、init.sh等工件，说明每个产出物的职责、写法与验证方法，供你在自己的仓库里直接照搬执行。

这个 Playbook 解决什么问题

在 Agent（如 Claude Code、Codex 等）驱动的开发流程中，会话通常是一次性的：新会话开始时没有前一次对话的记忆，只能从仓库文件本身重建上下文。如果仓库没有一份"自解释"的运行说明，每个新会话都会重复推导启动命令、猜测当前状态、自己划定任务边界——这既浪费时间，也容易产生不一致的结论。

Playbook 的目标非常明确：在一次初始化会话中，把"启动路径、验证路径、当前状态、任务边界"全部固化成仓库中的持久工件，使后续增量功能开发可以跳过"重新推导"环节，直接进入实现。这一设计思路与本仓库的系列课程（如 lecture-03 关于"仓库必须成为系统记录源"、lecture-06 关于"初始化需要独立阶段"）一脉相承，可参考 docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase。

必需产出：初始化会话至少要留下五个工件

原文档明确要求初始化器至少留下以下工件，本文结合 project-01/solution 的真实文件逐一说明。

1. 根指令文件：AGENTS.md 或 CLAUDE.md

这是给所有未来会话看的"宪法"，通常放在仓库根目录。它要回答"这个仓库怎么被正确对待"，包括启动顺序、架构边界、约定和完成标准。

project-01/solution/AGENTS.md 是一个可参考的模板，其结构包含：

• Startup Rules（启动规则）：写代码前按顺序执行的步骤——先完整读本文件、再读架构文档与产品文档、运行bash init.sh验证构建、最后读feature_list.json了解功能现状；
• Electron Layer Boundaries（分层边界）：明确 main / preload / renderer / services 四层各自的职责与禁止事项（例如 renderer 禁止 import Node.js 模块）；
• Conventions（编码约定）：如 TypeScript 严格模式、使用命名导出、IPC 通道名统一收口在src/shared/types.ts；
• Definition of Done（完成定义）：一个功能"完成"需要同时满足编译通过、应用可启动、feature_list.json状态更新且有证据、遵守分层边界、运行期无控制台报错。

CLAUDE.md则作为针对 Claude Code 的快速参考，通过@AGENTS.md引用主文件，避免双份内容漂移——project-01/solution/CLAUDE.md 中就是用一行@AGENTS.md导入，然后只保留构建命令、关键文件表、架构规则和"如何新增功能"的六步流程。这种"一份完整指令 + 一份轻量引用"的组合，可以让不同 Agent 工具都能快速对齐。

2. 机器可读的功能面：feature_list.json

人类读进度日志，Agent 读机器可解析的 JSON。feature_list.json的价值在于：结构固定、状态字段明确，任何会话都能用代码快速解析"还有哪些没做完"。

project-01/solution/feature_list.json 展示了推荐的字段结构：

{ "project": "project-01", "description": "Baseline Electron knowledge base with minimal harness", "features": [ { "id": "window-launch", "name": "Window Launch", "description": "Electron app opens a BrowserWindow with correct dimensions and preload script", "status": "pass", "evidence": "npm run dev launches window at 1200x800 with contextIsolation=true and nodeIntegration=false", "testedAt": "2026-03-30T10:00:00Z" } ] }

每个功能条目包含id、name、description、status、evidence、testedAt。status取值为"pass"/"fail"/"not-started"三态：实现完成并验证后置为"pass"并附上证据；被阻塞则置为"fail"并写明原因；AGENTS.md还约定了一条重要规则——永不从列表中删除功能条目，保证历史与边界可追溯。证据字段应具体到命令和可观察结果（如上面window-launch的 evidence），这样后续会话不用重新验证就能信任状态。

3. 持久进度工件：claude-progress.md

进度日志记录"发生了什么、当时怎么决策、下一步是什么"。它不是写给过程看的形式主义，而是跨会话连续性的核心载体。

project-01/solution/claude-progress.md 的 Session 1 记录展示了应包含的信息：会话编号与日期、耗时与目标、实际完成事项清单、关键决策（如"用构造器注入 PersistenceService 保持可测试性""IPC 通道名统一收口在 types.ts"）、遗留问题，以及给下一次会话的明确指引（"Proceed to Project 02…"）。其中"决策"部分尤其重要——它把隐性的上下文变成显性知识，让后续会话不必重新权衡一遍。

4. 标准启动辅助脚本：init.sh

把"装依赖 + 类型检查 + 构建"这些开机动作固化成一条命令，是消除启动路径歧义的最直接手段。

project-01/solution/init.sh 展示了最小可用写法：

#!/usr/bin/env bash # init.sh -- Verify the project builds cleanly before starting work. # Run this after cloning or when resuming work. set -euo pipefail echo "=== Project 01 Init ===" echo "" echo "[1/3] Installing dependencies..." npm install echo "" echo "[2/3] Running type checks..." npm run check echo "" echo "[3/3] Building project..." npm run build echo "" echo "=== Init complete. All checks passed. ===" echo "Run 'npm run dev' to launch the application."

注意set -euo pipefail：任一环节失败立即退出并返回非零状态，避免"假成功"。脚本末尾打印下一步提示，把"启动路径"进一步收敛为bash init.sh后npm run dev。package.json中对应的脚本定义在 projects/project-01/solution/package.json：dev通过node scripts/dev.js启动 Electron，check用两个 tsconfig 分别做tsc --noEmit，build先tsc -p tsconfig.node.json编译主进程/预加载/共享/服务层，再vite build打包 renderer。

5. 初始安全提交

最后一个工件是记录"基础脚手架当前状态"的第一次提交。它的意义是建立一个干净的、可回退的基线：此后所有增量功能都从这一提交出发，diff 始终可审、可回滚。

从源码结构看，project-01 的基线脚手架（projects/project-01/solution/src 下的 main / preload / renderer / services 四层骨架，以及 ARCHITECTURE.md 中描述的层间调用关系）正是 Playbook 所说的"baseline scaffold"。首次提交前应保证init.sh全流程通过、feature_list.json与claude-progress.md已写入初始状态，再提交，从而让"初始状态"本身可被任何后续会话随时检出。

检查清单：初始化会话的五步执行顺序

原文档把初始化过程压缩为五步检查清单，执行顺序如下：

1. 定义标准启动路径——确定"从克隆到可运行"的确切命令序列，写进AGENTS.md的 Startup Rules，并用init.sh固化；
2. 定义标准验证路径——确定"如何确认工作正常"，在 project-01 中即npm run check（类型检查）与npm run dev（窗口可见）的 Definition of Done 判定，同时配合测试命令（project-01/solution/CLAUDE.md 中的npm test）；
3. 建立进度日志并写下初始状态——创建claude-progress.md，如实记录本次会话做了什么、基于什么决策；
4. 把工作拆成功能并给出状态字段——在feature_list.json中列出所有功能条目，未完成的一律"not-started"，完成且验证过的标"pass"并附证据；
5. 建立第一个干净的 baseline commit——在上述四步全部完成、验证全绿之后提交，作为后续所有增量的起点。

这五步的顺序本身就有讲究：先有"怎么跑、怎么验"的约定，再记录状态，最后才提交基线——保证提交快照与文档、功能列表完全一致。

成功标准：用"无上下文新会话"做验收

Playbook 最精彩之处在于它的验收方式——不是看初始化器自己觉得做完了，而是看一个完全没有前文聊天上下文的新会话能否独立回答五个问题：

这五个问题恰好对应本文开头的目标：启动路径（怎么启动）、当前状态（做什么、什么没做完）、任务边界（下一步做什么）都被显式固化。如果你的新会话只需读仓库文件就能答出这五点，初始化阶段就算真正完成；如果答不出其中任何一点，说明对应工件缺失或写得不够自解释，需要补强后再进入增量开发。

在你自己仓库中执行 Playbook 的要点

结合原文档与仓库实例，实际落地时建议注意：

• 指令文件单一事实来源：AGENTS.md作为主文件，CLAUDE.md用@AGENTS.md引用，避免同一规则在多个文件里漂移失同步；
• 功能列表永不删条目：状态可以变（not-started→pass/fail），但条目本身保留，让"任务边界"可追溯；
• 证据要可复现：feature_list.json的evidence写成可重跑的命令与可观察结果，而不是模糊描述；
• 进度日志记录决策而非流水账：重点写"为什么这么做"，因为决策是跨会话最有价值的隐性知识；
• 基线提交前先全绿：确保init.sh通过、进度与功能列表已写入，再打第一次提交，保证基线快照干净可用。

总结

《Initializer Agent Playbook》提供了一套轻量但完整的初始化仪式：一份根指令、一个机器可读功能面、一份持久进度日志、一个启动辅助脚本、一次干净基线提交。本仓库的 project-01/solution 是这套方法的完整落地方案，五个工件与五步清单、五个验收问题一一对应。在你自己的 Agent 驱动项目中，照此执行一次初始化会话，就能把"每次重新推导上下文"的成本一次性结清——后续每一个无记忆的新会话，都能从仓库本身获得全部启动信息、状态信息和边界信息，直接开始增量实现。