技术地图
Mawflow Seed 的技术地图不是一张静态架构图，而是一套让 AI 和人都能快速定位项目事实的索引方法。它把项目身份、组件、模块、任务、检查和交付证据串起来，让后续 AI 执行会话不用从空白对话重新理解项目。
适用对象：想把普通仓库整理成 AI Coding 工作区的开发者、维护者和小团队。
技术地图解决什么问题
| 问题 | 技术地图的作用 |
|---|---|
| 项目入口不清晰 | 用 AGENTS.md、.maw/ 和 docs 入口给出最小读取路径。 |
| 任务边界不清楚 | 用 components、modules 和 Prompt Spec 固定允许修改范围。 |
| 模块事实分散 | 用模块档案沉淀页面、API、数据、测试和风险。 |
| 检查命令靠口口相传 | 用 Check Pack 和 readiness checks 固定检查入口。 |
| 交付结论不可追溯 | 用 Verification Pack 保存验证、验收、风险和交付说明。 |
地图层级
| 层级 | 典型文件 | 说明 |
|---|---|---|
| 项目身份 | .maw/project.yaml、README.md | 说明项目是什么、谁维护、当前边界是什么。 |
| 组件地图 | .maw/components.yaml | 说明 code/ 下有哪些 app_key、职责和源码路径。 |
| 模块地图 | .maw/modules.yaml、docs/modules/** | 说明功能模块、页面、API、表名、测试和文档入口。 |
| 任务地图 | Prompt Spec、Task Pack | 说明本次任务目标、输入、允许修改、禁止修改和验收方式。 |
| 检查地图 | ops/scripts/、Check Pack | 说明提交、分发、公开发布和脱敏前要运行什么。 |
| 交付地图 | docs/acceptance/、docs/delivery/、Verification Pack | 说明完成证据、风险和交付记录在哪里。 |
最小技术地图
新项目不需要一次性写完所有文档。建议先建立最小地图：
text
README.md
AGENTS.md
.maw/project.yaml
.maw/components.yaml
.maw/modules.yaml
docs/modules/<module-key>/module.md
ops/scripts/check-local-boundary.sh
docs/delivery/这组文件足以让 AI 理解项目身份、组件、模块、检查和交付记录。
AI 如何使用技术地图
一次任务开始时，AI 应按这个顺序读取：
- 任务 Prompt Spec。
AGENTS.md或项目 AI 入口。.maw/project.yaml、.maw/components.yaml、.maw/modules.yaml。- 与任务路径、module_key、页面、API 或报错栈相关的模块档案。
- 任务要求的输入资料。
AI 不应该因为关键词联想全量读取 docs、prompts、artifacts 或本机资料。技术地图的价值就是让上下文可收敛。
模块档案怎么写
一份有用的模块档案至少包含：
| 字段 | 用途 |
|---|---|
| 当前功能描述 | 说明模块做什么、不做什么。 |
| 实现程度 | 说明 active、部分完成、待确认或废弃状态。 |
| 页面边界 | 用户入口、页面路径或组件路径。 |
| API / 数据边界 | 接口、表、事件或配置。 |
| 验证方式 | 测试、构建、检查或人工验收。 |
| 文档维护规则 | 哪些变更必须同步档案。 |
模块档案不是营销文案，而是给后续开发和 AI 会话看的事实索引。
技术地图和 Pack 的关系
| Pack | 使用技术地图的方式 |
|---|---|
| Prompt Pack | 引用项目身份、模块和允许修改路径。 |
| Task Pack | 将技术地图拆成编号任务和恢复状态。 |
| Check Pack | 把技术地图中的检查要求变成命令。 |
| Verification Pack | 将检查结果和验收结论回写为交付证据。 |
公开仓库地址
Seed 的公开仓库地址以官网为准：
text
https://github.com/mawflow/mawflow-seed公开文档、示例和任务包只使用官网确认的公开仓库地址，不写非公开仓库地址、维护者本机路径或一次性同步目标。
下一步
继续阅读 升级反馈循环，了解 Seed 如何从项目使用反馈中持续演进。