mb-map-codebase

mb-map-codebase — 棕地：仓库 → Memory Bank

• 用途： 扫描现有仓库，汇总各个限定范围的工作者收集的证据，并按现状编写 Memory Bank 文档。
• 适用场景： 代码已经存在，需要在规划变更前建立可靠的基线。
• 输入： 仓库根目录，以及已初始化的 .memory-bank/。
• 输出： 描述当前系统的产品、架构、测试、运行手册和契约文档，不包含推测性的任务规划。

前置条件

• 当前位于仓库根目录。
• .memory-bank/ 骨架已存在（如果不存在，请运行 mb-init）。

流程

1) 启动协议和任务文件夹

创建：

• .protocols/MAP-CODEBASE/plan.md
• .protocols/MAP-CODEBASE/progress.md
• .protocols/MAP-CODEBASE/verification.md（映射完整性 + 证据）
• .protocols/MAP-CODEBASE/handoff.md
• .protocols/MAP-CODEBASE/decision-log.md（可选）

创建：

• .tasks/TASK-MB-MAP/

计划必须包含 MB-SYNC（链接到 .memory-bank/workflows/mb-sync.md）。

2) 启动扫描子 Agent（并行）

使用 ./agents/shared-repo-scanner.md 作为基础工作者提示词。

规则：

• 并行子 Agent 最多 5–7 个。
• 范围不可重叠（以避免冲突）。
• 智能调用：每个工作者都要验证其 glob 是否匹配实际文件。

建议的范围：

• S-01 工具链/CI
• S-02 后端/服务
• S-03 前端/UI
• S-04 数据层
• S-05 测试/质量

每个子 Agent 都要写入：

• .tasks/TASK-MB-MAP/TASK-MB-MAP-S-0X-final-report-<code|docs>-01.md

3) 汇总（强制）

编写最终文档前：

• 阅读所有工作者报告
• 汇总为一份大纲
• 解决矛盾（或记录为“需要验证”）
• 在 .protocols/MAP-CODEBASE/progress.md 中简短记录汇总情况，包括：
  • 使用了哪些报告
  • 存在哪些冲突以及如何解决
  • 未解决的问题

4) 综合整理 Memory Bank（按现状）

根据汇总结果，创建或更新：

• 产品简介（.memory-bank/product.md）
• 架构概览（.memory-bank/architecture/）
• 有证据支持的规范性路由文档（.memory-bank/spec-index.md、.memory-bank/glossary.md、.memory-bank/invariants.md）
• 运行手册（.memory-bank/runbooks/）
• 契约（.memory-bank/contracts/）
• 当代码、工作流或测试体现出生命周期/状态规则时，记录状态（.memory-bank/states/）
• 测试策略（.memory-bank/testing/index.md）
• 索引（.memory-bank/index.md）

使用 references/synthesis-checklist.md。

无 PRD 规则（不可协商）： 如果没有 prd.md，则绝不能创建或填充：

• .memory-bank/epics/*
• .memory-bank/features/*
• .memory-bank/tasks/*.task.json 中的真实路线图任务

如果空骨架文件/文件夹是由引导程序创建的，则可以保留。

映射是对当前系统的文档记录，不是规划。

在概览文档中明确区分：

• 事实（证据：路径/命令/日志/测试）
• 推断（假设，必须明确标注）

5) 索取 PRD 差异说明

建立基线 Memory Bank 后：

• 请用户提供描述要变更/新增内容的 prd.md。
• 然后运行 mb-from-prd，在基线之上规划差异。

6) 审查关卡

在全新上下文中运行 mb-review。

7) MB-SYNC

遵循 .memory-bank/workflows/mb-sync.md，并追加一条变更日志记录。

完成标准

• .tasks/TASK-MB-MAP/ 中包含限定范围的报告。
• .memory-bank/ 根据证据描述系统的“现状”。
• 已记录矛盾和未解决的问题。
• 已向用户索取 PRD 差异说明。