map-project-monorepo

此技能会更改多个工作区成员的持久项目记忆。以下规则不可妥协： 1. 写入任何成员的 `CLAUDE.md` 之前，先确认实际工作区结构。 2. 记录实际导出或可访问的接口，而不只是原始可见性标记。 3. 每个成员文件都要自成一体，足以满足 Claude 的延迟加载模式。 4. 保留根级项目规则和已锁定的架构决策，除非发现证明它们已过时。 5. 不要主动运行此技能（它会更改持久项目记忆）——仅在用户明确要求时运行，或在用户明确调用的工作流包含此技能时运行（例如，`/ship-playbook` 在构建后刷新映射）。

映射项目单体仓库

输入

• $request：可选的范围或刷新说明，例如 all crates、only packages/api-* 或 refresh workspace docs after adding the sql crate。

目标

刷新根目录和各成员的 CLAUDE.md 文件，确保每个工作区成员都有准确、独立完整的本地指导，同时保持根目录文件精简，且仅包含项目级内容。

步骤 0：确定工作区范围并识别单体仓库结构

确定：

• 仓库是 Cargo 工作区还是包单体仓库
• 用户希望全面刷新还是仅刷新指定成员
• 存在哪些成员，以及哪些成员已有 CLAUDE.md 文件
• 已有哪些根级记忆文件和架构规则需要保留

加载 references/workspace-discovery.md，了解：

• 工作区检测顺序
• 成员清单要求
• 导出接口、连接关系和依赖映射的发现规则

如果出现以下情况，请提前停止：

• 无法识别工作区结构
• 目标成员范围过于模糊，无法安全更新

成功标准：在开始发现工作区内容之前，明确工作区结构和刷新范围。

步骤 1：发现成员、公共接口和连接关系

对于范围内的每个成员，清点：

• 实际导出或可访问的接口
• 关键源文件
• 连接文件，例如 crate 根文件、包入口点、清单文件、导出汇总文件、启动钩子、注册表、路由器或功能标志
• 成员间依赖关系
• 测试、基准测试或运行时入口点
• 实际使用方的使用模式（如可用）

此外，还要清点工作区范围内的能力（这些内容应写入根目录文件，而非成员文件）：

• 项目提交的技能（.claude/skills/）和已启用的 MCP 服务（.mcp.json / .claude/settings*.json）

规则：

• 不要把原始 pub 或原始 export 的数量等同于实际公共接口
• 先验证使用方实际能够访问的内容
• 优先依据实际导入、重新导出和运行时注册点，而不是猜测
• 如果现有成员文档仍然准确，就应保留并扩充或精简，而不是盲目重新生成

加载 references/workspace-discovery.md，并针对已识别的单体仓库结构完成相关发现步骤。 加载 references/skills-and-mcp.md，了解技能和 MCP 的发现来源及脱敏规则。

成功标准：你已收集足够具体的信息，可以编写独立完整的成员文档，无需使用占位符，也不会对接口作出错误描述。

第 2 步：更新各成员的 CLAUDE.md 文件

对于每个属于范围内的成员，更新或创建一份精简的本地 CLAUDE.md，涵盖：

• 用途
• 公开或导出的接口
• 关键文件
• 依赖项
• 连接方式和入口点
• 使用模式
• 架构说明
• 测试指南

加载：

• references/output-contract.md，了解必需章节、篇幅目标和验证规则
• references/package-template.md，适用于库或包成员
• references/app-template.md，适用于应用、二进制文件或入口点较多的成员

编写规则：

• 使用工作区中的真实示例，不要使用占位符
• 优先使用表格和项目符号，避免重复叙述
• 让每个成员文件都能独立使用，以适应 Claude 的延迟加载行为
• 记录隐藏的连接点，以便未来的更改能让相关行为生效

成功标准：每个目标成员都有一份准确且独立完整的 CLAUDE.md。

第 3 步：精简根目录的 CLAUDE.md

将根目录文件视为项目级路由器：

• 保留项目级规则、已确定的决策、测试策略和工作区布局
• 从根目录移除成员专属的 API 表格或文件列表
• 确保根目录清楚地指向成员本地文档，而非重复其中的内容
• 在根目录 CLAUDE.md 中加入精简的内联“可用技能与 MCP — 优先使用”部分， 并在文件最顶部加入一行指引，让未来的 Agent 使用仓库中的技能/MCP，而不是忘记它们（仅使用始终加载的文本——绝不可使用延迟引用，也不可按成员分别编写）

规则：

• 保留根目录级别的架构约束和指导决策
• 不要删除有用的人工编写的全局规则
• 将成员详情下移，避免根目录成为每个成员文件的另一份副本

加载 references/output-contract.md，了解根目录文件的要求和篇幅规则。 加载 references/skills-and-mcp.md，了解“可用技能与 MCP”部分的格式和发现来源。

成功标准：根目录保持精简且聚焦项目整体，同时将成员详情放在 Claude 会延迟加载的位置。

第 4 步：验证覆盖度、独立完整性和篇幅

在宣布完成前，验证更新结果：

• 每个范围内的成员都有一份 CLAUDE.md
• 成员文档描述的是真正可触达的接口，而不只是原始可见性标记
• 在相关情况下记录连接方式和入口点
• 根目录不再大量重复成员本地详情
• 行数预算保持合理
• 更新后的文档足以让实现 Agent 无需盲目搜索，就能在受影响的成员中开展工作

加载 references/output-contract.md，了解验证门槛和篇幅目标。

如果验证失败：

• 提高覆盖度
• 补全缺失章节
• 精简重复内容
• 更正过时的可达性或连接方式说明

成功标准：工作区记忆精简、按成员划分，并且真正对未来的 Agent 有用。

第 5 步：报告变更内容

总结：

• 检测到的工作区结构
• 已更新的成员
• 已创建或更新的文件
• 覆盖度或清单方面的要点
• 篇幅预算状态
• 有意推迟处理或不在范围内的成员

如果工作区只完成了部分覆盖，或者请求范围排除了某些成员，请勿声称已完美更新。

成功标准：用户能清楚了解工作区记忆更新了哪些内容，以及完成度如何。

护栏

• 不要主动使用此技能（它会修改持久项目记忆）——仅在用户明确表达意图，或明确由用户调用的工作流组合使用此技能时运行（例如 /ship-playbook）。它不再是 disable-model-invocation，因此工作流可以调用它；但这并不意味着可以在未收到提示时运行。
• 不要添加 context: fork；此工作流会写入当前活动仓库。
• 不要添加 paths:；这是一项通用维护技能。
• 没有证据表明根目录级项目规则已过时时，不要覆盖有用的规则。
• 不要在 SKILL.md 中内嵌工作区发现矩阵、模板百科或质量评分表。
• 不要让根目录的 CLAUDE.md 臃肿；将成员详情下移。
• 未验证自包含性和可达性前，不要将刷新标记为已完成。

何时加载参考资料

• references/workspace-discovery.md 用于了解工作区检测顺序、成员发现规则，以及导出表面与原始可见性方面的指导。

• references/output-contract.md 用于了解必需的成员／根目录章节、预算规则和验证关卡。

• references/package-template.md 用于刷新库风格的成员。

• references/app-template.md 用于刷新二进制文件、应用、服务或入口点较多的成员。

• references/skills-and-mcp.md 用于发现仓库的项目技能和 MCP 服务，并将内嵌的“可用技能与 MCP — 优先使用这些”章节写入根目录的 CLAUDE.md。

输出约定

报告：

1. 检测到的工作区形态和范围
2. 已刷新的成员
3. 已创建或更新的文件
4. 覆盖范围和自包含性摘要
5. 预算和验证结果
6. 延后处理或有意跳过的成员