企业官网建设流程全解析

导读

本文讲解 learn-harness-engineering 仓库中定义的「编码代理开工流程」：一套在每次会话初始化完成后、正式动手改代码之前必须执行的标准操作程序（SOP）。它回答了 Agent 编码工作中的一个核心工程问题——如何让每一轮会话都在可验证、可续接、不会在坏状态上叠改动的前提下开始与结束。读完本文，你将掌握 9 步固定开工模板、每一步背后的原理与仓库中的真实落地形态（init.sh、claude-progress.md、feature_list.json、session-handoff.md），以及与之镜像对应的收尾流程。

一、为什么编码会话需要一套固定开工流程

1.1 会话是无状态的，仓库才是系统记录

在 learn-harness-engineering 的课程体系中有一个核心论断：长期任务之所以丢失连续性，是因为每次新会话都是一张白纸。Agent 的上下文窗口会在会话结束时清空，而仓库文件是唯一能在会话之间存活下来的持久载体（参见第 3 讲：为什么仓库必须成为系统记录 与第 5 讲：为什么长期任务会丢失连续性）。

因此，开工流程的本质不是「仪式感」，而是把「当前处于什么状态、接下来做什么」这件事从 Agent 的记忆里搬进仓库文件里，让每个新会话都能在几秒钟内恢复出全部上下文。

1.2 顺序即协议：9 步模板为什么不能乱

开工模板给出的 9 个步骤之间存在严格的依赖关系，顺序本身就是约束。下面逐条拆解：

1. 运行pwd，确认仓库根目录——防止在错误目录里干活。很多「改了没生效」的诡异问题，根源其实是 Agent 在子目录或错误的工作区里编辑了文件。
2. 读取claude-progress.md——恢复持久状态。这个文件记录了上次会话的验证结果、未完成功能与阻塞项（模板见 docs/ru/resources/templates/claude-progress.md）。
3. 读取feature_list.json——恢复功能清单与优先级。它回答了「接下来该做什么」。
4. 用git log --oneline -5查看最近 5 条提交——快速解释上次会话结束时发生了什么变更。
5. 运行./init.sh——把启动过程标准化，而不是靠记忆执行一串命令。
6. 跑一条基础 smoke test 或端到端路径——建立「基线是绿的」这一事实。
7. 如果基础状态已坏，先修这个——永远不要在红基线上叠加新改动。
8. 选择最高优先级的未完成功能——从 feature_list.json 中挑选。
9. 只围绕这个功能工作，直到它被验证或明确 blocked——单活动功能约束（对应feature_list.json中"single_active_feature": true规则）。

第 7 步是全流程的纪律核心：基线验证必须先于任何新工作，否则新改动会「掩盖」旧的破坏，让问题在事后难以定位。

二、开工流程的五个关键工件：仓库里的真实落地形态

开工流程不是抽象口号，仓库中给出了每个工件的可直接复制模板与真实用例。

2.1 init.sh：标准化启动

模板位于 docs/ru/resources/templates/init.sh，核心结构如下：

#!/usr/bin/env bash set -euo pipefail ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" cd "$ROOT_DIR" # Replace these commands with the correct commands for your repository. INSTALL_CMD=(npm install) VERIFY_CMD=(npm test) START_CMD=(npm run dev) echo "==> Working directory: $PWD" echo "==> Syncing dependencies" "${INSTALL_CMD[@]}" echo "==> Running baseline verification" "${VERIFY_CMD[@]}" ...

要点解读：

• set -euo pipefail：任何一步失败立即退出，防止「假装成功」继续往下跑——这本身就是对「过早宣布胜利」问题的防御。
• ROOT_DIR用脚本自身位置推导仓库根，配合cd "$ROOT_DIR"让脚本在任何目录下被调用都能落到正确位置，这正是开工模板第 1 步pwd的脚本化等价物。
• 三个命令数组INSTALL_CMD/VERIFY_CMD/START_CMD可按仓库替换；默认用npm install同步依赖、npm test做基线验证。
• RUN_START_COMMAND=1时才会直接拉起应用，默认只打印启动命令，避免 init 阶段误启动长驻进程。

真实项目中的落地示例见 projects/project-01/solution/init.sh：它按npm install→npm run check（类型检查）→npm run build（构建）三步执行，并在结尾明确提示Run 'npm run dev' to launch the application——同样体现了「先验证再启动」的顺序纪律。

2.2 claude-progress.md：会话间持久状态

模板见 docs/ru/resources/templates/claude-progress.md，固定包含两部分：

• 当前已验证状态：仓库根路径、标准启动路径、标准验证路径、当前最高优先级未完成功能、当前阻塞项。
• 会话日志：按### 会话 001、### 会话 002递增编号，每条记录日期、目标、已完成事项、实际运行的验证、记录的证据、提交哈希、更新的文件/工件、已知风险、下一步最佳行动。

这个文件解决了「上次会话到底做到哪了」的问题，是开工模板第 2 步的读取对象，也是收尾流程第 1 步「记录进度」的写入对象。

2.3 feature_list.json：功能即原语

模板见 docs/ru/resources/templates/feature_list.json，这是「功能清单是 harness 原语」一讲的直接载体（参见第 8 讲：为什么功能清单是 harness 原语）。其结构要点：

• rules 区声明三条元规则：single_active_feature: true（同时只允许一个活动功能）、passing_requires_evidence: true（通过必须有证据）、do_not_skip_verification: true（不得跳过验证）。
• status_legend 区定义四个状态：not_started、in_progress（当前活动任务）、blocked（需先解决记录的阻塞项）、passing（验证通过且证据已记录）。
• features 数组中的每条功能包含：id（如 chat-001）、priority（数值越小优先级越高）、area、title、user_visible_behavior（用户可见行为，即验收标准）、status、verification（可执行验证步骤列表）、evidence（证据记录）、notes。

精简形态的示例见 docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json，它用passes: false布尔字段直接表达「该功能尚未通过验证」。真实项目用例则存在于 projects/project-01/solution/feature_list.json 等多个项目目录。

开工模板第 3、8 步分别对应读取该文件、并从中挑选status != passing且priority最小的功能作为本轮唯一目标。

2.4 session-handoff.md：交接摘要

模板见 docs/ru/resources/templates/session-handoff.md，固定五个板块：

1. 现在已验证的内容：当前能跑什么、实际跑了哪些验证；
2. 本会话变更：新增的代码/行为、基础设施或 harness 的改动；
3. 已损坏或未验证的部分：已知缺陷、未验证路径、对下一会话的风险；
4. 下一步最佳行动：最高优先级未完成功能、为什么是它、什么算通过、此步骤中不能改什么；
5. 命令速查：启动命令、验证命令、定向调试命令。

这份文件是收尾流程第 3 步「写交接摘要」的标准格式，也是「长期任务连续性」主题的实操工具（相关讲稿见 docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/）。仓库同时提供了该模板的可编辑副本 skills/harness-creator/templates/session-handoff.md。

2.5 git log：用提交历史解释「刚刚发生了什么」

git log --oneline -5只展示最近 5 条提交的单行摘要。它的作用不是审计，而是快速对齐：上一会话结束时提交了什么、有没有遗留未提交的改动。结合claude-progress.md中的「提交」字段，Agent 可以判断持久状态文件与 git 历史是否一致。

三、对应的收尾流程：开工模板的镜像

开工模板要求会话结束同样按固定顺序收尾，五步与开工步骤形成镜像：

1. 记录进度——更新 claude-progress.md 的会话日志；
2. 更新功能状态——把 feature_list.json 中本条功能的 status 改为passing、blocked或保持in_progress，并同步last_updated；
3. 必要时写交接摘要——生成/更新 session-handoff.md；
4. 提交安全状态的代码——只提交已验证、不会破坏基线的变更；
5. 留下可直接重启的干净环境——保证下一会话执行开工模板时能顺利通过第 6 步基线验证。

镜像关系的意义在于闭环：收尾时留下的文件，恰好就是开工时读取的文件；开工时的基线验证，恰好能检验收尾是否留下了干净状态。这也与「会话必须留下干净状态」的主题一脉相承（参见第 12 讲：为什么每次会话都必须留下干净状态）。

四、把流程嵌入 harness：从模板到项目实践

4.1 三份模板文件与项目结构的关系

在真实项目中，开工模板所需的工件按以下约定落位（以项目目录为根）：

• init.sh放在仓库根目录，直接可执行（chmod +x后运行./init.sh）；
• claude-progress.md、feature_list.json同样放在仓库根，与 AGENTS.md / CLAUDE.md 等 harness 指令文件并列；
• session-handoff.md在需要多会话接力时生成。

参见真实用例 projects/project-01/solution/（含 init.sh、claude-progress.md、feature_list.json、AGENTS.md、CLAUDE.md 的完整布局）与 projects/project-02/solution/（含 session-handoff.md 的多会话示例）。

4.2 常见误用与规避

• 跳过 init.sh 直接改代码：等于放弃了基线验证，第 6、7 步的防线失效；
• 同时推进多个功能：违反single_active_feature规则，导致状态文件互相污染；
• 把 status 标成 passing 却没有证据：违反passing_requires_evidence，feature_list.json 的evidence数组必须记录实际运行的验证输出；
• 收尾不写 handoff 就提交：下一会话只能靠猜，开工模板第 2、3 步会读到过期状态。

五、总结：开工与收尾是一枚硬币的两面

编码代理开工流程本质上是一条可复制的状态恢复协议：开工 9 步负责「读状态 → 验基线 → 选唯一目标」，收尾 5 步负责「写状态 → 留证据 → 保干净」。两者共用同一套工件（claude-progress.md、feature_list.json、session-handoff.md、init.sh），因此在 learn-harness-engineering 的项目实践中，它们被统一收纳为模板目录 docs/ru/resources/templates/，并被 harness-creator 技能（skills/harness-creator/templates/）引用为生成新项目 harness 的标准零件。

对任何想把 Agent 从「一次性的、靠运气的编码会话」升级为「可接力、可审计、可验证的持续工程过程」的开发者而言，这套开工/收尾流程是最小可用、也最容易被验证的起点：它不依赖任何特定模型能力，只依赖「把状态写进文件、把验证跑在基线前」这两条朴素纪律。