# Preflight Readme Scan

> Forces a lightweight README reconnaissance before any broad code exploration or multi-file modification in an unfamiliar repository. Use at the start of every new conversation on a project the agent has not yet read, whenever the user asks an open-ended question like "this project does what / how do I add X / where is Y", and before the agent would otherwise reach for SemanticSearch, Glob, or repeated Grep passes to understand the codebase. Reads the top-level README.md first, then only the folder-level README.md files relevant to the task, explicitly skipping dependency / cache / data folders. Cuts token cost significantly compared to ad-hoc exploration because each folder README is a pre-organized structural index.

- Skill: `playerrch/preflight-readme-scan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add playerrch/preflight-readme-scan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/playerrch/preflight-readme-scan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: playerrch (https://skillmd.com/u/playerrch)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/playerrch/preflight-readme-scan

---


# Preflight README Scan

新 agent 进入一个陌生/不熟的项目时，**第一步永远是读 README**，而不是盲目 Grep / Glob / SemanticSearch。本 skill 给出"何时读、读到什么程度、跳过什么"的判断树。

## 为什么省 token

| 做法 | 等价 token 消耗 | 信息密度 |
|---|---|---|
| 1 次 Read 顶层 README.md | 约 5-15 KB | 高（已按目录分类） |
| 1 次 SemanticSearch 宽泛查询 | 约 10-30 KB × 多轮可能 | 低（chunk 碎片、含无关内容） |
| 多次 Glob + Read 扫文件 | 累积 50-200 KB | 最低（文件本身含大量噪声） |

项目里的顶层 README 通常已经是一张"导航表"，直接链到各子 README；子 README 再分别给出该目录的职责、文件清单、约束。这套结构是人为精心整理过的**结构化索引**，远比机器扫出来的搜索结果省。

## 决策树：要不要预读

```
任务输入到手
  ├─ 任务里明确给出了具体文件 (如 "改 backend/routes/auth.py 的 X") ？
  │   └─ 是 → 跳过 README 预读，直接 Read 目标文件 (Level 0)
  │
  ├─ 任务仅涉及回答概念问题、不改代码？
  │   └─ 是 → 跳过 README 预读，直接回答或用 SemanticSearch 定位 (Level 0)
  │
  ├─ 同一对话里已经读过顶层 README？
  │   └─ 是 → 跳过重复 (Level 0)
  │
  ├─ 任务跨越多个模块、需理解架构？
  │   └─ 是 → Level 2 (顶层 + 2-3 个相关子 README)
  │
  ├─ 用户问 "这个项目是干啥的 / 从哪入手 / 介绍一下"？
  │   └─ 是 → Level 2 或 Level 3（用户若要"全貌"则 Level 3）
  │
  └─ 其它正常任务
      └─ Level 1（只读顶层 README 拿目录导航）
```

## 四档预读强度

### Level 0 — 不预读

- 任务文件已锁定
- 任务是纯回答、只读、不改动代码
- 已经在同一会话里读过 README

直接进入正常工具链（Read / Grep / SemanticSearch）。

### Level 1 — 最小预读（默认）

1. Read 项目根 `README.md`
2. 扫它的"目录导航"或"Directory Structure"章节
3. 把导航表记到心里 → 后续若要定位某个模块，直接 Read 对应子 README
4. **不要**一口气读所有子 README（浪费）

### Level 2 — 定向深读（推荐用于多模块任务）

1. Level 1 的 1-3 步
2. 根据任务关键字匹配 2-3 个子目录，Read 它们的 `README.md`
   - 例："改答疑流程" → 读 `backend/README.md` + `backend/routes/README.md` + `frontend/README.md`
   - 例："新增一张表" → 读 `backend/README.md` + `backend/migrations/README.md`
3. 若子 README 里指向 `docs/<具体文档>.md` 规范，按需追读（最多再 1-2 篇）

### Level 3 — 全景扫读（仅在用户明确要求"梳理全局"时）

1. 顶层 README
2. 顶层导航表里列出的所有子 README
3. `docs/README.md` + 它指向的核心规范文档（CURRICULUM / SECURITY / DEPLOYMENT 等）

这一档适合做重构规划、写新手入门材料、项目交接；日常小任务不应触发。

## 永远不读的目录（强制跳过名单）

不要读这些目录下的 README（即使存在也要跳过）：

- `node_modules/`, `venv/`, `.venv/`, `Include/`, `Lib/`, `Scripts/`, `site-packages/`
- `__pycache__/`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`
- `dist/`, `build/_work/`, `build/Output/`, `target/`
- `volumes/` 下的容器数据子目录（Dify / Postgres / Redis 等持久化）
- `.git/`

## 阅读顺序的标准模板

```
Phase 1: Orient     (Level 1 默认)
  └─ Read README.md (项目根)

Phase 2: Focus      (Level 2 按需)
  ├─ Read <dir_a>/README.md
  ├─ Read <dir_b>/README.md
  └─ （必要时）Read docs/<relevant>.md

Phase 3: Execute    (开始真正的查代码/改代码)
  └─ 到这里才用 Read 具体源码、Grep、SemanticSearch 等
```

## 反模式（不要这么做）

- **预读后还盲搜**：已经读了 README 知道"出题逻辑在 `backend/routes/question.py`"，就不要再用 SemanticSearch "where is question generation"
- **Level 1 被当 Level 3 使**：单纯改 1 个方法的小任务却读了 15 个 README，浪费令牌
- **重复预读**：同一会话里 README 内容不会变，读过就不要再读
- **忽略 README 直冲代码**：陌生项目不读 README 就开始 Glob，信息密度低而且容易误会模块边界
- **读依赖目录的 README**：`Lib/site-packages/xxx/README.md` 是第三方库文档，不是你的项目信息

## 在任务回复中的体现

预读完成后，首次回应用户的内容里应当包含：

- 对项目/相关模块的**一句话自我定位**，让用户知道你已经理解上下文
- 不需要事无巨细说你读了哪些 README（除非用户问过程）
- 后续不要再为"了解项目"而做广搜

## 与其它 skill 的配合

| 协同 skill | 触发时机 |
|---|---|
| `maintain-folder-readmes` | 完成改动后，根据本 skill 读过的 README 反向校对：哪些 README 与新现实不符需要更新 |
| `cleanup-deprecated-artifacts` | 如果本 skill 预读时发现某 README 里提到的文件已经不存在，顺手列入清理候选 |

## 实战示例

用户：「帮我给答疑模块加一个管理员查询接口。」

**正确做法（Level 2）**：

1. Read 项目根 `README.md` → 看到 `backend/routes/` 里有 `qa.py`
2. Read `backend/routes/README.md` → 确认 `qa.py` 前缀 `/api/qa`，权限走 `require_permission`
3. Read `backend/security/README.md` → 确认 `require_permission("qa:xxx")` 的用法
4. 这时才 Read `backend/routes/qa.py` 找 `router` 对象，加新端点

**错误做法**：

1. SemanticSearch "where is QA handler defined"（20 KB 噪声）
2. Glob `**/qa*.py`（拿到一堆测试文件也要分辨）
3. SemanticSearch "how to add permission check"（又一堆碎片）
4. 在一堆零散结果里拼出该怎么做

前者每次任务稳定省掉 50% 以上的探索令牌，后者每次都在重新摸黑。

## 最后一条规则

**当有了 README 这个结构化索引，就优先用它**。把 SemanticSearch 留给"README 之外仍需要确认的具体实现细节"，而不是"从零理解项目"的用途。