# Maintain Folder Readmes

> Keeps every folder README.md in sync with the actual content after code changes. Use when the agent finishes a coding task that added, removed, moved, renamed, or changed the responsibility of files in any business folder, or when the user asks to "update the README", "sync folder docs", "整理文件夹 说明", "更新 README", or "每次改动后同步文件夹说明". Identifies touched folders, reviews each against the README template matching its category (business / tool / data-artifact), and updates the corresponding README.md so that file lists, responsibilities, and cross-links stay accurate.

- Skill: `playerrch/maintain-folder-readmes` (Agent Skill)
- Install (CLI): `npx skillmds@latest add playerrch/maintain-folder-readmes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/playerrch/maintain-folder-readmes/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/maintain-folder-readmes

---


# Maintain Folder READMEs

每次完成代码改动后，自动识别变动涉及的目录，并把各目录 `README.md` 与真实内容保持一致。

## 核心流程

```
改动完成 → 识别受影响目录 → 对每个目录按模板校对 README → 必要时更新 → 校验与顶层导航一致
```

## 何时触发

- 新增 / 删除 / 重命名 / 移动文件（非缓存、非产物）
- 新增或删除模块、路由、页面、迁移脚本、skill、配置
- 目录职责发生变化（比如把某个功能从 A 拆到 B）
- 用户明确说「更新 README」「整理结构」「同步文件夹说明」

## 何时**不**触发

- 纯注释 / 格式化 / 重命名变量而未涉及文件增删
- 只改测试用例没有影响源码文件清单
- 只改 `__pycache__/`、`*.pyc`、`logs/`、`volumes/` 等产物
- 改动限定在 `Include/`、`Lib/`、`Scripts/`、`.venv/` 等 venv 产物

## 工作步骤

1. **列出本轮改动** — 回忆会话中被 Write/StrReplace/Delete 触碰过的文件路径，或跑 `git status`（若是 git repo）
2. **归并到目录** — 去重后得到受影响目录列表，排除"不触发"范围
3. **对每个目录** — 按以下决策：

   ```
   目录有 README.md?
     ├─ 是 → 按分类模板校对"文件清单"、"职责"、"关键入口"；有变化就更新
     └─ 否 →
         是业务/工具/数据产物目录吗?
           ├─ 是 → 按分类模板新建 README.md
           └─ 否（缓存 / venv 产物） → 跳过
   ```

4. **回流顶层导航** — 若目录新增/删除/更名，还要更新项目根 `README.md` 的"目录导航"表
5. **回流跨目录引用** — 被移动的文件若被其它 README 链接引用，逐个修正这些链接
6. **最小必要改动** — 只改实质变化的段落；不要借机重写历史内容

## 分类模板

### 业务目录模板（例如 `backend/routes/`、`frontend/`）

```markdown
# <dir-name>/ — <一句话定位>

<两三句话交代目的、在整体架构中的位置>

## 文件清单 | 架构图

<按职责列关键文件，每行 1-2 句；若文件超过 6 个建议用表格>

## 约束 / 修改规范

<必须遵守的硬规则：禁止直连 SQL、必须走唯一出口、必须加权限检查...>
<可选：指向 .cursor/rules/*.mdc 或 docs/ 对应规范>

## 新增/改动步骤

<分 3-6 步说清楚"如果我要加一个新 X，我应该..."
```

### 工具目录模板（例如 `deploy/`、`build/`、`ssrf_proxy/`）

```markdown
# <dir-name>/ — <一句话定位>

<交代什么场景用>

## 文件清单

<每个文件 1-2 句说明>

## 典型使用 / 运行方式

<给 1-3 个最常见用法的命令块>

## 注意 / 改动要点

<配置重启、权限要求、与其他模块的契约>
```

### 数据/产物目录模板（例如 `logs/`、`volumes/`、`knowledge_base/`）

```markdown
# <dir-name>/ — <一句话定位>

<它是什么、由谁生成、谁消费>

## 结构 / 文件类型

<说清楚命名规则或子目录含义>

## 管理原则

<是否可手动改、是否可删、是否 gitignore、如何备份>
```

### 产物目录（venv 等）极简模板（1 句话）

```markdown
# <dir-name>/ — <venv 产物 / 容器持久化 / 完整性快照等>

由 `<谁>` 生成，**请勿手动修改**，**不要提交到版本库**（已 gitignore）。
误删后 `<恢复命令>` 即可重建。
```

## 关键约束

- **改动 minimal**：只更新"事实不一致"的地方，保持原有写作风格
- **不重复**：子 README 覆盖细节时，顶层 README 只放导航，不要重抄文件清单
- **链接用相对路径**：`[backend/routes/README.md](backend/routes/README.md)`，不要用绝对盘符路径
- **禁用时效性表述**：不要写"上周新增了 X"；改用"v1.4 新增 X"这种版本化表述
- **跳过名单**：`__pycache__/`、`.pytest_cache/`、`Include/`、`Lib/`、`Scripts/`、`volumes/`（数据子目录）、`node_modules/`

## 校验步骤

1. 新/旧 README 都用 ReadLints 过一遍，确保 Markdown 无语法错误
2. 在每个被修改/新建的 README 里抽样点进 1-2 个相对链接，确保目标存在
3. 若顶层 README 被改了目录导航表，抽样点 3 个子 README 链接

## 最小产出格式

当任务完成，给用户一张"本轮 README 变更清单"的汇总表：

```
新建：
  - backend/routes/README.md
  - frontend/README.md
更新：
  - README.md（目录导航表加入 frontend/ 链接）
  - backend/README.md（routes 子目录新加路由的 1 行说明）
跳过：
  - Include/、Lib/ （venv 产物，不触发）
```