507-map

name	507-map
description	维护项目地图：以当前代码为证据，建立或校准 README、doc 组织、目录职责、入口与上下游，只修改地图文档。Use when user says map, project map, 梳理项目结构, 项目结构, 更新 README, 补 README, 校准 README, 整理 doc, 整理结构, 文档地图, 目录职责, 分层 README.

项目地图（map）

本 skill 以当前代码为证据维护项目空间地图，让人和 agent 能快速找到目录职责、入口、主要文件、上下游和边界。

修改权限

允许在确认范围内创建、移动、重命名或校准：

• 项目根 README.md；
• doc/README.md 和承担导航职责的 doc/ 结构；
• 含代码目录的分层 README.md。

不修改业务代码、测试、配置、脚本、AGENTS.md、术语定义、决策正文、路线图/实施方案内容或 CHANGELOG.md。发现需要变化时只报告并路由。

范围纪律

1. 用户指定路径时，只处理该范围及必须同步的上下级地图。
2. 未指定范围时，先扫描并列出缺失或失真的候选目录，确认后再写。
3. 已有地图过时时只修正失真部分；缺失时只写最小必要说明。
4. 不自动扩到整个项目，不为单个文件机械建立 README。

证据顺序

依次读取：项目 AGENTS.md → 根 README.md → doc/README.md → 目标目录上下级 README → 相关文档 → 代码、测试和配置。

地图中的事实必须由当前代码或权威文档支持。代码与地图冲突时，明确列出冲突，以当前实现作为事实证据，只更新地图文档；不替项目决定新的产品或架构意图。

文档地图原则

• doc/README.md 说明阅读顺序、当前权威和历史归档边界；
• 路线图、版本实施方案和归档材料已有明确分类时，放入项目约定的对应区域，不继续平铺混放；
• 小项目可以保持平铺，但要能看出文档职责和权威关系；
• 归档只用于追溯，不写成当前事实；
• 目录职责、入口或上下游变化时同步上下级 README。

工作流程

1. 锁定范围：记录允许修改的地图文档、排除项和必须同步的上下级。
2. 读取现实：识别入口、公共接口、主要文件、依赖关系和现有边界。
3. 先画草图：形成目录定位、职责、主要文件、入口、上下游和边界。
4. 最小落盘：只写代码支持的事实，不写营销话术、计划或臆测。
5. 同步导航：检查上级目录表、下级入口和 doc/README.md 阅读顺序。
6. 验证：检查 Markdown（标记语言）链接、相对路径、地图与代码一致性，并确认没有代码文件被修改。

常见 README 骨架按需取舍：

# <目录或项目名称>

## 一句话定位
<目录职责。>

## 主要文件
- `<path>` — <职责>

## 入口与关系
- 入口：...
- 上游：...
- 下游：...

## 边界
- ...

交付

说明处理与未处理范围、已读依据、每个文档的修改、代码/文档冲突、不确定性和链接验证结果。若发现规范、术语、决策、路线图或变更记录缺口，明确路由，不在本 skill 内代改。

红线

• 不改代码；
• 不做全量项目规范巡检；
• 不替项目设计新架构；
• 不把计划或归档写成现状；
• 不凭目录名推断职责；
• 不把个人偏好写成项目规范。

完成与接力

• 完成信号：声明范围内的根/分层 README 与 doc 地图已和当前代码、入口及目录职责一致，链接与导航已验证。
• 产物：只包含项目地图文档的修改，以及已读范围、冲突和未处理缺口说明。
• 候选出口：术语或用户决策缺口进入 507-grill；规范全量缺口进入 507-setup；代码问题进入相应实施；地图修改完成后进入 507-review，用户明确要求提交时再进入 507-commit。
• 回退条件：代码现实无法确认时返回 507-explore 或报告证据边界，不用文档猜测覆盖实现。