Seed 快速开始

本页面面向已经会使用 Git 和 AI 编程工具的开发者。目标是在项目已经创建或完成改造后，建立第一次 AI Coding 闭环：项目事实清楚、第一条任务可执行、修改后有检查、有收口。

准备条件

• 本机可以使用 Git。
• 已完成 Seed 安装：全新项目已经创建，或现有项目已经增量接入 Seed 协作结构。
• mawflow --help 可用。
• 你能打开常用的 AI 编程工具。
• 你愿意把项目边界、允许修改路径、验收标准和验证命令写清楚。
• 项目根目录已有 AI_START_HERE.md 和 .maw/agent-entry.yaml，或你准备在本次接入中补齐它们。

1. 选择项目入口

所有项目初始化统一从 Seed 安装 开始。Seed 负责建立项目协作结构；需要本机增强、项目空间或团队治理时，再进入 Lite、Studio 或 Enterprise。

项目状态	先读哪一页	说明
新项目	Seed 安装	用 mawflow project init my-project 创建项目目录，再写入项目事实。
0.2.x 老项目 / 存量仓库	Seed 安装	通过 preview/confirm 一次性迁移到 Contract v2。
需要更多本机增强能力	Lite 安装	进入 Lite，本机管理项目和增强上下文。
需要项目空间和交付闭环	Studio 安装	进入 Studio，把需求、任务和交付证据串起来。

如果你想按训练路线继续学习，回到 Seed 新手训练路径。

2. 写入项目事实

至少先更新这些文件：

文件	要写清楚什么
README.md	项目是什么、怎么启动、谁维护、当前状态。
AI_START_HERE.md	AI 进入项目目录后先读什么、不能读什么、任务怎样收口。
.maw/agent-entry.yaml	多 Agent 共享的项目入口、受保护路径、验证和收口契约。
.maw/project.yaml	项目 key、名称、负责人、协作模式和基础边界。
.maw/components.yaml	真实组件，例如 server、client 或你的实际 app_key。
.maw/modules.yaml	当前业务模块树；不确定的模块先保守记录。
.maw/app-runtime.yaml	本地启动、测试入口和必要的环境引用。

不要提交 .local/ 真实内容、.maw/*.local.yaml、私钥、token、生产连接串或未脱敏日志。

3. 写第一条 Prompt Spec

不要只写“帮我做一个功能”。建议从这个最小结构开始：

# 任务标题

## 背景
说明当前项目状态、已有文件和用户目标。

## 目标
列出这次必须完成的交付物。

## 允许修改
- code/<app_key>/**
- docs/<topic>/**

## 禁止修改
- .local/**
- .maw/*.local.yaml
- 与任务无关的组件
- 真实密钥、token、账号密码

## 验收标准
- 用户可见行为是什么。
- 哪些文档或状态需要同步。
- 哪些检查命令必须通过。

## 验证命令
列出本次最小必要检查。

## 收口
说明变更、验证、发布影响和遗留风险。

完整结构见 Prompt Spec。

4. 交给 AI 执行会话

在项目根目录打开 AI 编程工具，给它 Prompt Spec。要求它先读取 AI_START_HERE.md、工具自己的入口文件和任务相关文件，再修改代码或文档。

建议把任务拆小：一个会话完成一个可验证目标。复杂任务用 Task Pack 保存计划、编号任务、恢复状态和验收要求。

5. 执行中发送引导消息

任务交给 AI 执行会话后，你可以根据工具界面提供的阶段说明、工具动作和进度更新，判断执行是否仍在任务边界内。这里不是要求你盯每一行代码，而是在口径跑偏时，及时给 AI 发送一条引导消息，让它按正确口径继续执行。

如果看到某一句明显不对，直接复制那句话，按这个格式发给 AI：

补充:<复制 AI 可见过程里的原话> 这句不对，应该是<写清正确口径>

示例：

补充:我会先运行 Seed 开源发布检查 这句不对，应该是第一次快速开始只需要确认本次任务结果和项目自己的最小验证，Seed 开源发布检查属于维护者发布前 gate

适合及时补充的情况：

• AI 把维护者 gate、公开发布检查或 Task Pack 状态文件说成新手必做步骤。
• AI 准备读取或修改 Prompt Spec 之外的无关路径。
• AI 要写入 .local/、真实密钥、私有仓库地址或客户资料。
• AI 说“已验证”，但没有说明它实际运行了什么，或者没有说明未配置原因。

这里说的过程信息只指工具主动展示的阶段说明、工具动作和进度更新。不同工具展示粒度不同，不要求也不应尝试查看或保存隐藏推理。

6. 确认收口

一次任务完成后，不要求你马上维护一套交付文档。先看 AI 的最终说明是否能让人判断这次任务是不是真的结束。

合格收口应包含：

• 修改了哪些文件。
• 用户能看到什么结果。
• 运行了哪些验证，结果是什么。
• 哪些验证没有运行，原因是什么。
• 哪些风险或未完成事项需要后续处理。
• 是否需要发布、打包或公开脱敏。

可以直接要求 AI 用这个格式收口：

请最后用中文收口：
- 变更：
- 验证：
- 未验证 / 不适用：
- 风险：
- 发布影响：
- 下一步：

只有当任务进入复杂任务、正式验收、交付或可恢复 Task Pack 时，才需要把这些信息写入 docs/acceptance/、docs/delivery/ 或 SESSION_STATE.md。第一次快速开始只要确认收口说得清楚即可。

7. 任务完成后审计

任务执行完成之后，再做一次人工审计。这里不是执行中的即时提醒，而是看这次 AI 任务最终有没有留下错误口径、错误文档、错误验证结论或不该沉淀的项目事实。

审计重点：

• 是否把 Seed 维护者脚本、公开发布 gate、Task Pack 状态文件当成普通用户必做步骤。
• 是否把“AI 内部约束”写成了“人工操作步骤”。
• 是否把本机路径、真实账号、私有仓库、客户资料或密钥带进了公开文档。
• 是否在没验证时写成已通过。
• 是否把一次性任务结论升级成长期项目事实。

如果审计发现问题，把问题发回当前 AI 执行会话，让它只修正本次任务留下的错误口径。仍然可以使用补充格式，但语义是“任务完成后修正”，不是“执行中打断”：

补充:<复制 AI 阶段说明、进度更新或最终说明里的原话> 这句不对，应该是<写清正确口径>

如果问题已经写进文件，还要补一句：

请修正对应文档，不要扩展新功能。

常见错误

错误	修正方式
直接让 AI 全仓搜索和修改	先写允许修改和禁止修改路径。
把本机路径写进公开文档	公开文档只写仓库相对路径。
把一次性对话当项目事实	第一次任务先看收口；稳定规则多次出现后再沉淀到 .maw/、docs 或模块档案。
一上来写交付文档	只有正式验收、交付或 Task Pack 才需要写入 docs/acceptance/、docs/delivery/ 或 SESSION_STATE.md。
修改后不验证	至少确认用户结果、改动范围和项目自己的最小验证。
把内部约束当人工步骤	复制 AI 可见过程里的原话，要求它按新手操作口径重写。

下一步

继续阅读 写第一条 Prompt Spec，把第一个小任务写成可执行、可验收的结构。复杂任务再阅读 创建 Task Pack。