仓库平面与构造

MAWflow Seed 的核心思想是把普通代码仓库整理成几个职责清楚的平面。这样 AI 不需要每次从空白对话重新理解项目，也不会把本机资料、密钥或无关目录混入交付内容。

总体结构

路径	面向谁	职责
code/	开发者、AI、交付对象	产品源码、端工程配置、路由、构建和线上可见行为。
.maw/	开发者、AI	项目身份、组件、模块、运行、发布、仓库和协作边界。
docs/	开发者、项目负责人、AI	需求、设计、模块档案、验收、交付和公开说明。
prompts/	人工选择后交给 AI	Prompt Spec、Task Pack 和一次性任务说明。
ops/	开发者、维护者	检查、构建、发布、脱敏和治理脚本。
release/	维护者	发布随带文件和覆盖规则。
.local/	当前设备	本机路径、端口、代理、临时资料和 local overlay；真实内容不提交。
artifacts/	维护者	执行记录、验证输出和临时产物；公开前需评估。

code/ 产品源码平面

code/ 保存真实产品源码。用户运行、测试、交付和发布的行为以这里为准。

常见规则：

• 不把 .local/、日志、缓存、构建产物或私钥放进 code/。
• 端工程配置以组件内文件为准，例如 .env.example、框架配置和构建配置。
• 如果一个任务只改文档，不要顺手修改 code/。
• 如果任务改了 code/，收口时要说明验证结果和发布影响。

.maw/ 协作协议平面

.maw/ 让 AI 读懂项目身份和协作边界。它不是业务运行时代码，也不替代端工程真实配置。

常见文件：

文件	用途
.maw/project.yaml	项目 key、名称、时区、负责人和项目类型。
.maw/components.yaml	组件、app_key、源码路径和组件职责。
.maw/modules.yaml	模块树、页面/API/表名与模块档案入口。
.maw/app-runtime.yaml	本地调试入口和测试引用。
.maw/releases.yaml	发布环境和发布指令索引。
.maw/template-source.yaml	模板来源和升级基线。

公开 Seed 可以提供示例 .maw 配置，但不得包含真实 secret、生产连接串、客户资料或本机 overlay。

docs/ 文档平面

docs/ 保存项目长期事实。Seed 推荐把可复用事实写进文档，而不是停留在聊天记录里。

建议维护：

• docs/modules/：模块档案，帮助 AI 缩小上下文。
• docs/requirements/：需求说明和待确认问题。
• docs/design/：设计说明。
• docs/acceptance/：验收记录。
• docs/delivery/：交付说明。
• docs/public-seed/：公开 Seed 说明。

prompts/ 任务说明平面

prompts/ 存放人工选择后交给 AI 的任务说明。它不是默认必须读取的全部上下文。

建议：

• 小任务用单条 Prompt Spec。
• 大任务创建 Task Pack。
• 任务包保存计划、执行入口、编号任务、验证要求和 SESSION_STATE.md。
• 不把真实密钥、客户数据或未脱敏日志写进 prompt。

ops/ 检查与运维平面

ops/ 保存脚本和说明，用于把检查、构建、发布、脱敏和分发 gate 变成可执行命令。

Seed 常见检查包括：

• 本机边界检查。
• 公开开源 readiness 检查。
• 分发包就绪检查。
• 模块档案检查。
• 脱敏检查。

.local/ 本机平面

.local/ 只属于当前设备。它可以保存本机路径、端口、代理、浏览器 profile、原始资料和临时排障说明。

公开仓库和交付包不得包含 .local/ 真实内容。可提交的通常只有 .local/**/README.md 或 *.example.yaml。

Seed 的工作原理

项目事实写入 .maw 和 docs
  ↓
Prompt Spec 或 Task Pack 定义任务
  ↓
AI 执行会话在边界内修改 code 或文档
  ↓
Check Pack 执行验证
  ↓
Verification Pack 记录证据、风险和交付说明
  ↓
公开前执行脱敏和 release gate

这条链路让 AI 辅助开发有输入、边界、执行、验证和交付记录，而不是只依赖一次对话。

下一步

继续阅读 检查与发布 gate，或查看 技术地图 理解这些目录如何串成可执行索引。