| 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。发现需要变化时只报告并路由。
范围纪律
- 用户指定路径时，只处理该范围及必须同步的上下级地图。
- 未指定范围时，先扫描并列出缺失或失真的候选目录，确认后再写。
- 已有地图过时时只修正失真部分；缺失时只写最小必要说明。
- 不自动扩到整个项目，不为单个文件机械建立 README。
证据顺序
依次读取：项目 AGENTS.md → 根 README.md → doc/README.md → 目标目录上下级 README → 相关文档 → 代码、测试和配置。
地图中的事实必须由当前代码或权威文档支持。代码与地图冲突时，明确列出冲突，以当前实现作为事实证据，只更新地图文档；不替项目决定新的产品或架构意图。
文档地图原则
doc/README.md 说明阅读顺序、当前权威和历史归档边界；- 路线图、版本实施方案和归档材料已有明确分类时，放入项目约定的对应区域，不继续平铺混放；
- 小项目可以保持平铺，但要能看出文档职责和权威关系；
- 归档只用于追溯，不写成当前事实；
- 目录职责、入口或上下游变化时同步上下级 README。
工作流程
- 锁定范围：记录允许修改的地图文档、排除项和必须同步的上下级。
- 读取现实：识别入口、公共接口、主要文件、依赖关系和现有边界。
- 先画草图：形成目录定位、职责、主要文件、入口、上下游和边界。
- 最小落盘：只写代码支持的事实，不写营销话术、计划或臆测。
- 同步导航：检查上级目录表、下级入口和
doc/README.md 阅读顺序。
- 验证：检查 Markdown（标记语言）链接、相对路径、地图与代码一致性，并确认没有代码文件被修改。
常见 README 骨架按需取舍：
# <目录或项目名称>
## 一句话定位
<目录职责。>
## 主要文件
- `<path>` — <职责>
## 入口与关系
- 入口：...
- 上游：...
- 下游：...
## 边界
- ...
交付
说明处理与未处理范围、已读依据、每个文档的修改、代码/文档冲突、不确定性和链接验证结果。若发现规范、术语、决策、路线图或变更记录缺口，明确路由，不在本 skill 内代改。
红线
- 不改代码；
- 不做全量项目规范巡检；
- 不替项目设计新架构；
- 不把计划或归档写成现状；
- 不凭目录名推断职责；
- 不把个人偏好写成项目规范。
完成与接力
- 完成信号：声明范围内的根/分层 README 与 doc 地图已和当前代码、入口及目录职责一致，链接与导航已验证。
- 产物：只包含项目地图文档的修改，以及已读范围、冲突和未处理缺口说明。
- 候选出口：术语或用户决策缺口进入
507-grill；规范全量缺口进入 507-setup；代码问题进入相应实施；地图修改完成后进入 507-review，用户明确要求提交时再进入 507-commit。
- 回退条件：代码现实无法确认时返回
507-explore 或报告证据边界，不用文档猜测覆盖实现。
