# 507 Map

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

- **Type:** Skill
- **Install:** `agentstack add skill-ssdiwu-507-skills-507-map`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ssdiwu](https://agentstack.voostack.com/s/ssdiwu)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ssdiwu](https://github.com/ssdiwu)
- **Source:** https://github.com/ssdiwu/507-skills/tree/main/code/507-map

## Install

```sh
agentstack add skill-ssdiwu-507-skills-507-map
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 项目地图（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 骨架按需取舍：

```md
# 

## 一句话定位

## 主要文件
- `` — 

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

## 边界
- ...
```

## 交付

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

## 红线

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

## 完成与接力

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ssdiwu](https://github.com/ssdiwu)
- **Source:** [ssdiwu/507-skills](https://github.com/ssdiwu/507-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ssdiwu-507-skills-507-map
- Seller: https://agentstack.voostack.com/s/ssdiwu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.