初始化项目的目标，不是一次性生成所有功能，而是在较短时间内建立一套能够运行、边界清晰、可以验证、便于继续迭代的工程基础。
使用 Coding Agent 可以显著提高搭建速度，但前提是先明确输入、范围、约束和验收方式。一个稳定的初始化流程可以组织为：
本文使用一个中性案例贯穿说明：团队准备开发一个“会议行动项管理工具”，用户可以创建会议、登记行动项、指定负责人，并查看行动项状态。初始化阶段只实现一条可运行的主流程，不追求完整的协作能力和精细界面。
Agent 的实现质量首先取决于输入质量。开始编码前，应把零散想法整理为一份“项目输入包”。它不必十分正式，但必须覆盖目标、边界、约束和已有资产。
至少说明以下内容：
案例输入可以写成：
这是一个供小型团队使用的会议行动项管理工具。初始化版本需要支持创建会议、在会议下新增行动项、填写负责人和截止日期，以及修改行动项状态。暂不实现消息通知、复杂权限、第三方登录、统计报表和移动端适配。
需要写清已经确定的技术决策，以及仍可由 Agent 提出建议的部分：
不要把偏好写成模糊描述。例如，与其写“使用现代前端技术”，不如写“使用团队现有技术栈，不新增同类状态管理库；页面层不得直接访问数据库”。
如果项目不是完全从空目录开始，还应列出：
准备好输入后，不要立即要求 Agent 编码。先让它复述理解、识别矛盾，并提出会影响实施的问题。
澄清阶段的重点不是让 Agent 替人做决定，而是暴露尚未做出的决定。
澄清问题可以分为三类。
不回答就无法安全开始实施，例如：
答案会影响目录、接口或数据模型，例如：
当前无需解决，但应记录为后续事项，例如：
可以要求 Agent 按固定结构回答：
人需要逐项确认，特别注意 Agent 是否擅自扩大范围、引入新技术或把建议描述成既定事实。
澄清完成后，应把对话结论沉淀为一份独立开发规格。它必须脱离对话也能被理解，避免 Agent 在后续压缩上下文或重新启动会话后丢失关键约束。
一份适合初始化项目的开发规格可以包括：
模糊要求：
页面需要易用，代码结构要合理。
可验证要求：
用户在会议详情页填写标题、负责人和截止日期后，可以创建行动项；标题为空时页面显示校验提示且不写入数据库。页面只能调用行动项服务，不得直接调用数据访问模块。
后一种写法同时定义了操作入口、输入、成功结果、失败结果和架构边界，更适合 Agent 实施与验收。
初始化项目不宜按照“先建所有表、再写所有接口、最后统一做页面”的水平方式推进。更稳妥的方法是切出一个最小垂直切片，让用户操作能够穿过界面、业务逻辑和数据存储，形成端到端闭环。
最小垂直切片应同时满足：
案例中的第一个切片可以定义为：
用户进入某个会议详情页，填写行动项标题和负责人后提交；系统校验标题非空，将行动项保存到数据库，并在当前页面显示新记录。保存失败时显示明确错误，页面不展示虚假成功状态。
这个切片虽然很小，但已经贯通页面、校验、服务、数据访问、数据库迁移和反馈机制，能够较早暴露技术栈集成问题。
开发规格和切片顺序确定后，再让 Coding Agent 开始实施。每一轮只处理一个边界明确的任务，并要求它用实际检查结果证明完成情况。
每轮可以按照以下顺序执行：
Agent 遇到以下情况时，不应自行猜测：
质量门禁是进入下一切片前必须通过的检查。它应尽可能自动化，并在项目初始化时就建立，而不是等功能增多后再补。
根据技术栈选择对应命令，但至少覆盖：
可以把门禁分成三个层级：
自动化检查可以证明代码满足一部分规则，但不能替代真实使用和架构判断。人工验收应按照固定脚本执行，并记录实际结果。
在尽可能接近新开发者环境的条件下检查：
以案例为例：
表现：只有一句产品描述，Agent 自动决定用户体系、权限、数据模型和依赖。
后果：实现看似完整，但关键决策与真实需求不一致。
改进：先准备输入材料和非目标，再开始澄清。
表现：Agent 推荐某个框架后立即安装，并据此重构目录。
后果：项目被不必要的技术选择锁定。
改进：要求区分“已确认决策”“默认建议”“待确认问题”。
表现：先创建大量表、接口、组件和工具类，但没有任何可操作的闭环。
后果：集成问题发现得晚，难以判断实际进度。
改进：优先完成贯通界面、业务逻辑和数据存储的最小垂直切片。
表现：一个任务同时包含登录、权限、核心业务、通知和管理后台。
后果：Agent 上下文变长，改动范围失控，失败后难以定位原因。
改进：让每个切片只产生一个主要用户结果，并设置明确停止条件。
表现：Agent 表示“功能已完成”，但没有运行测试、构建或启动检查。
后果：配置错误、类型错误和运行时问题留到人工使用时才暴露。
改进：要求报告实际执行的检查及结果，失败项必须如实保留。
表现：删除失败测试、关闭类型检查、忽略警告或扩大例外规则。
后果：检查显示通过，但项目质量并未提高。
改进：修复根因；确需调整规则时，先说明影响并由人确认。
表现：初始化阶段就建设插件系统、复杂事件总线、通用权限平台或多租户框架。
后果：增加理解和维护成本，却没有验证真实需求。
改进：只为当前切片建立必要结构，为已知变化保留清晰边界即可。
表现：自动化测试通过后直接宣布交付。
后果：操作流程、提示文案、空状态和文档问题被遗漏。
改进：按照固定验收脚本从用户视角完整操作一次，并检查工程结构。
表现：实施中改变了字段、状态或目录，但没有同步文档。
后果：后续 Agent 和开发者依据过期信息继续工作。
改进：把文档一致性纳入每个切片的完成条件。
“项目已经初始化”不应以创建了多少文件来判断，而应以是否形成可运行、可验证、可继续开发的基础来判断。
除非项目范围明确要求，否则以下内容通常不应阻塞初始化完成：
核心判断 一个初始化项目真正完成时，团队已经拥有一条可运行的业务闭环、一套可重复执行的质量检查、一份与实现一致的开发规格，以及一个清晰的下一步切片。Agent 负责提高实施速度，人负责确认目标、边界、风险和最终结果。
先切一条贯穿三层的薄片，而不是先把每一层铺满。
本文的初始化流程在 Agent X-Ray 的 R0 与 R1 里有对应物。
切片 0：工程可运行。 R0 的交付清单是 CLAUDE.md、轮次框架、本机唯一入口脚本、框架 skills、管理面注册、依赖安装冒烟——没有一行业务代码，但下一轮开工的一切都在了。
把已知坑写进宪法。 CLAUDE.md 硬性规则 1–4 「继承自上一个项目同机踩过的坑，原样适用」：守护进程的 socket 绑不到含中文的路径、测试只能经框架命令跑、含中文的脚本必须带 BOM、写 JSONB 的固定写法。初始化时把它们写进去，比之后再撞一次便宜。
「把建议当成已确认决策」的防线。 本文列的这条失败模式，在项目里的防线是 ROUNDS.md 各轮拆解里的四个字——「所有者裁定」。agent 提的建议与所有者裁定过的决定，在文档里用不同的写法区分。
任务模板的进化。 本文第五节的任务模板（目标、开始前、范围、禁止、验证、停止条件），在项目里长成了任务卡的七段（第 12 章）。→ 第 09、12、17 章。
苏公网安备32011402012723号