map-project

此技能会修改持久化的项目记忆。以下规则不可妥协： 1. 写入任何内容前，先识别项目实际采用的框架形态。 2. 更新 `CLAUDE.md` 或参考文档前，先对代码库进行实际探索。 3. 优先更新现有项目文档，而不是整体替换。 4. 生成的记忆应足够精简，以便在 Claude 的上下文预算内保持实用。 5. 不要主动运行此技能（它会修改持久化的项目记忆）——仅在用户明确提出要求时，或在用户明确调用的工作流中组合使用时运行（例如，构建完成后由 `/ship-playbook` 刷新项目地图）。

映射项目

输入

• $request：可选的目标范围或刷新说明，例如 api only、after auth refactor 或 update the docs for the Next.js app。

目标

刷新 CLAUDE.md 和导入的参考文档，使其描述真实项目，而非过时、通用或不完整的模式。

步骤 0：确定范围并识别项目形态

确定：

• 用户需要全面刷新还是限定范围的刷新
• 当前使用的主要框架或项目形态
• 仓库是单个应用，还是只有一个主要应用面的单一仓库
• 已有哪些记忆文件需要更新，而非重新创建

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

• 框架识别顺序
• 框架特定的探索要求
• 清单要求

遇到以下情况时，提前停止：

• 无法识别仓库形态
• 请求范围过于模糊，无法确定要更新哪些记忆文件

成功标准：在开始探索前，明确项目形态和文档范围。

步骤 1：写入前进行全面探索

使用适用于相应框架的方法，清点代码库的实际情况：

• 路由、界面或处理程序
• 导出项、模型、服务、钩子、模块或软件包
• 有状态实体及其生命周期流程
• API 路由、CLI 入口或软件包导出等公共接口
• 关键子系统及其集成边界
• 仓库自身提供的能力：项目内提交的技能（.claude/skills/）和已启用的 MCP 服务（.mcp.json / .claude/settings*.json）

规则：

• 不要轻信记忆或旧文档；应通过代码核实
• 对参考文档约定要求覆盖的内容，统计其数量
• 搜索实际实现示例，为指南提供依据
• 如果仓库已有部分文档，应先核实并补充，而不是不加判断地重写

加载 references/framework-discovery.md 并完成适用于已识别项目形态的探索步骤。 加载 references/skills-and-mcp.md，了解技能和 MCP 的发现来源及脱敏规则。

成功标准：收集到足够具体的清单信息，能够在不使用占位符或猜测的情况下记录项目情况。

步骤 2：先更新参考文件

根据探索所得的实际情况，刷新或创建导入的参考文件：

• 导出项或 API 接口参考文档
• 开发指南
• 架构参考文档

加载 references/output-contract.md，了解：

• 必需文件
• 每个文件必需的章节
• 框架特定的章节要求
• 行数预算目标

写作规则：

• 使用真实项目示例，而非通用模板
• 尽量用简洁的表格替代重复的文字说明
• 记录 Agent 在实现过程中实际需要的模式
• 各文件应各有侧重，避免内容重复

成功标准：参考文件准确反映代码库的实际情况，且篇幅适中、便于使用。

步骤 3：将 CLAUDE.md 更新为精简入口

将 CLAUDE.md 视为精简的路由入口：

• 导入详细的参考文件
• 仅在文件内保留高价值的速查内容和项目级指导
• 不要重复导入文件中已有的大型表格或操作指南
• 加入一个精简的内联“可用技能和 MCP — 优先使用”部分，并在 CLAUDE.md 最顶部添加一行指引，让后续 Agent 使用仓库的技能和 MCP 服务，而不是忘记它们——该内容必须保留在 CLAUDE.md 本身，不能放入导入的参考文件，因为只有始终加载的文本才会改变行为

规则：

• 保留现有已检入的项目指导，除非调查发现其已过时或有误
• 不要仅仅因为有用的人为编写的约定不属于生成结构，就将其删除
• 让速查内容确实能帮助 Agent 选择合适的导入文件

加载 references/output-contract.md，了解预期的 CLAUDE.md 结构。 加载 references/skills-and-mcp.md，了解“可用技能和 MCP”部分的格式及发现来源。

成功标准：CLAUDE.md 成为精简、准确的入口，指向更新后的项目记忆。

步骤 4：验证覆盖范围、篇幅预算和实用性

在宣布完成前，验证此次更新：

• 必需文件均已存在
• 预期章节均已包含
• 对于所选项目结构，文档覆盖范围足够全面
• 行数预算合理
• CLAUDE.md 与导入文件之间没有明显重复
• 实现 Agent 能够通过更新后的文档找到路由、导出内容和工作流指导

加载 references/output-contract.md，了解验证门槛和预算规则。

如果验证未通过：

• 精简文档
• 恢复缺失的章节
• 删除重复内容
• 利用调查清单提高覆盖范围

成功标准：更新后的记忆精简、可靠，对后续 Agent 确实有用。

步骤 5：报告变更内容

总结：

• 检测到的项目结构
• 新建或更新的文件
• 覆盖范围或清单要点
• 预算状态
• 有意未记录或暂缓处理的区域

如果仓库存在较大的盲区，或因混用多个框架而有意缩小了范围，就不要声称更新已臻完美。

成功标准：用户清楚了解更新了哪些项目记忆，以及更新的完整程度。

护栏

• 不要主动使用此技能（它会修改持久项目记忆）——仅在用户明确提出要求，或由用户明确调用的工作流组合调用时（例如 /ship-playbook）运行。此技能不再是 disable-model-invocation，因此工作流可以调用它；但这并不意味着可以在未获用户提示时运行。
• 不要添加 context: fork；此工作流会写入当前活动仓库。
• 不要添加 paths:；这是一个通用维护技能。
• 没有证据表明实用的人为编写项目规则已过时，就不要覆盖它们。
• 不要将框架发现矩阵或文件契约大全保留在 SKILL.md 中。
• 不要让 CLAUDE.md 过于臃肿；详细内容应放在导入的参考文件中。
• 未经验证，不要宣布更新完成。

何时加载参考文件

• references/framework-discovery.md 用于了解框架检测顺序、特定框架的调查步骤和清单要求。

• references/output-contract.md 用于了解必需的输出文件、必需章节、行数预算和验证规则。

• references/skills-and-mcp.md 用于发现仓库的项目技能和 MCP 服务，并将内联的“可用技能和 MCP — 优先使用”部分写入 CLAUDE.md。

输出契约

报告：

1. 检测到的项目结构和范围
2. 新建或更新的文件
3. 覆盖范围或清单摘要
4. 预算和验证结果
5. 暂缓处理或有意跳过的部分