mb-map-codebase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

mb-map-codebase — Brownfield: Repo → Memory Bank

What it does: scans an existing repository, merges evidence from scoped workers, and writes as-is Memory Bank docs.
Use it when: code already exists and you need a reliable baseline before planning changes.
Input: repository root plus an initialized
```
.memory-bank/
```
.
Output: product, architecture, testing, runbook, and contract docs that describe the current system without speculative backlog generation.

功能说明： 扫描现有代码仓库，合并来自指定范围工作器的佐证信息，写入现状Memory Bank文档。
适用场景： 已有代码存在，你需要在规划变更前获得可靠的基线信息时使用。
输入： 代码仓库根目录以及已初始化的
```
.memory-bank/
```
目录。
输出： 描述当前系统的产品、架构、测试、运行手册、合约文档，不会生成推测性的待办事项。

Preconditions

前置条件

You are in the repo root.
```
.memory-bank/
```
skeleton exists (if not, run
```
mb-init
```
).

你当前处于代码仓库根目录。
已存在
```
.memory-bank/
```
框架结构（如果没有，运行
```
mb-init
```
）。

Process

流程

1) Start a protocol + task folder

1) 新建协议与任务文件夹

Create:

```
.protocols/MAP-CODEBASE/plan.md
```
```
.protocols/MAP-CODEBASE/progress.md
```
```
.protocols/MAP-CODEBASE/verification.md
```
(mapping completeness + evidence)
```
.protocols/MAP-CODEBASE/handoff.md
```
```
.protocols/MAP-CODEBASE/decision-log.md
```
(optional)

Create:

```
.tasks/TASK-MB-MAP/
```

Plan MUST include MB-SYNC (link

.memory-bank/workflows/mb-sync.md

创建以下文件：

```
.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) Spawn scanning subagents (parallel)

2) 生成扫描子Agent（并行执行）

Use

./agents/shared-repo-scanner.md

as the base worker prompt.

Rules:

Max 5–7 parallel subagents.
Non-overlapping scopes (to avoid conflicts).
Smart calling: each worker validates that its globs match real files.

Suggested scopes:

S-01 tooling/CI
S-02 backend/services
S-03 frontend/UI
S-04 data layer
S-05 tests/quality

Each subagent writes:

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

使用

./agents/shared-repo-scanner.md

作为基础工作器提示词。

规则：

最多同时运行5–7个并行子Agent。
扫描范围不重叠（避免冲突）。
智能调用：每个工作器需验证其匹配的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) Fan-in (mandatory)

3) 结果聚合（强制要求）

Before writing final docs:

read all worker reports
merge into a single outline
resolve contradictions (or record them as “needs verification”)
write a short fan-in note into
```
.protocols/MAP-CODEBASE/progress.md
```
with:
- which reports were used
- what conflicted and how resolved
- open questions

在写入最终文档前：

读取所有工作器的报告
合并为单个大纲
解决矛盾内容（或者将其标记为“待验证”）
在
```
.protocols/MAP-CODEBASE/progress.md
```
中写入简短的聚合说明，包含：
- 使用了哪些报告
- 存在哪些冲突以及解决方式
- 未解决的问题

4) Synthesize Memory Bank (as-is)

4) 合成现状Memory Bank

Using the fan-in view, create/update:

product brief (
```
.memory-bank/product.md
```
)
architecture overview (
```
.memory-bank/architecture/
```
)
runbooks (
```
.memory-bank/runbooks/
```
)
contracts (
```
.memory-bank/contracts/
```
)
testing strategy (
```
.memory-bank/testing/index.md
```
)
index (
```
.memory-bank/index.md
```
)

Use

references/synthesis-checklist.md

PRD-less rule (non-negotiable): if there is no
prd.md
, you MUST NOT create or populate:
.memory-bank/epics/*
.memory-bank/features/*
.memory-bank/tasks/backlog.md
with waves/tasks
Empty skeleton files/folders are OK if they were created by bootstrap.

Mapping is documentation of the current system, not planning.

In overview docs, explicitly separate:

Facts (evidence: paths/commands/logs/tests)
Inferences (hypotheses, explicitly marked)

基于聚合后的视图，创建/更新以下内容：

产品概要（
```
.memory-bank/product.md
```
）
架构概览（
```
.memory-bank/architecture/
```
）
运行手册（
```
.memory-bank/runbooks/
```
）
接口合约（
```
.memory-bank/contracts/
```
）
测试策略（
```
.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/backlog.md
如果是初始化脚本创建的空框架文件/文件夹是允许的。

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

在概览文档中，明确区分：

事实（佐证：路径/命令/日志/测试）
推论（假设，明确标记）

5) Ask for PRD delta

5) 申请PRD增量信息

Once baseline MB exists:

ask the user for a
```
prd.md
```
describing what to change/add.
then run
```
mb-from-prd
```
to plan the delta on top of baseline.

当基线Memory Bank创建完成后：

要求用户提供
```
prd.md
```
说明需要变更/新增的内容。
之后运行
```
mb-from-prd
```
在基线之上规划增量变更。

6) Review gate

6) 评审关口

Run

mb-review

in fresh context.

在全新上下文环境中运行

mb-review

。

7) MB-SYNC

.memory-bank/workflows/mb-sync.md

and append a changelog entry.

遵循

.memory-bank/workflows/mb-sync.md

的要求，追加变更日志条目。

Definition of done

完成标准

```
.tasks/TASK-MB-MAP/
```
contains scoped reports.
```
.memory-bank/
```
describes the system “as-is” with evidence.
Contradictions and open questions are recorded.
User has been asked for PRD delta.

```
.tasks/TASK-MB-MAP/
```
包含各范围的扫描报告。
```
.memory-bank/
```
带佐证信息描述系统“现状”。
矛盾内容与未解决问题已记录。
已向用户申请PRD增量信息。