README Sync

开发编程

代码查询/修改前按需读取README.md了解项目状态，结束后按需更新。触发场景：(1)用户询问项目相关问题（如并发数），(2)需进行代码查询或修改。读取无需确认，写入README或代码前必须确认。跨平台支持（Claude Code、OpenClaw、Trae等）。

代码生成

362

下载量

安装量

收藏量

★ 5.0

综合评分ⓘ

概述

更多信息

README Sync#

在代码工作前后自动同步 README.md，保持项目文档最新。

工具脚本#

本 skill 提供 scripts/readme_operations.py 工具，简化操作：

bash

# 读取指定章节（按需读取，节省 token）
python scripts/readme_operations.py read "技术栈"      # 读单个章节
python scripts/readme_operations.py read all           # 读整个 README

# 扫描项目结构（预览，不写入文件）
python scripts/readme_operations.py scan

# 初始化 README
python scripts/readme_operations.py init               # 使用空模板
python scripts/readme_operations.py auto-init           # 扫描代码后生成

# 查看待更新条目
python scripts/readme_operations.py pending

# 添加待更新条目
python scripts/readme_operations.py add changelog "新增用户认证功能" --related src/auth/
python scripts/readme_operations.py add progress "完成支付模块重构"
python scripts/readme_operations.py add trap "xxx 容易搞反，要注意 yyy"

# 同步到 README（需确认）
python scripts/readme_operations.py sync

# 清空待更新
python scripts/readme_operations.py clear

README 不存在时的处理#

情况处理方式项目有代码但无 READMEauto-init 扫描目录结构和技术栈，生成初始 README空项目（无代码）先用 init 创建空模板，任务完成后再补充任务完成时发现无 README主动询问用户是否创建

核心原则#

场景是否确认原因读取 README❌ 不确认只读，不改变任何内容写入/修改 README✅ 必须确认涉及文件变更修改代码文件✅ 必须确认涉及代码变更回答项目相关问题（纯查询）❌ 不确认仅信息输出

按需加载策略（节省 Token）#

读取策略：最小基准 + 按需叠加#

第一步：最小基准（任何任务都建议读）

场景最小基准章节原因任何代码相关任务## 一句话定位 + ## 项目结构知道项目干什么、代码在哪

第二步：按需叠加（根据任务类型追加）

用户问题类型追加读取章节原因项目概况/定位## 技术栈了解用什么做的Bug 相关## 踩坑记录 + ## 近期修改记录查类似问题和近期变动技术方案选型## 技术栈 + ## 项目结构看现有技术栈和目录API 相关## API 概览查接口说明进度状态## 当前进度了解当前进行中的工作代码修改/新增## 近期修改记录 + 相关代码了解近期改了什么

第三步：必要时扩大读取范围

以下情况应该扩大读取，不能死守最小基准：

Bug 的根因不明确 → 扩大读技术栈、踩坑记录、近期修改
代码修改涉及多个模块 → 扩大读项目结构、API 概览
技术方案影响架构 → 扩大读技术栈、进度
原则：读不懂的时候扩大读取，而不是瞎猜

代码文件读取原则#

按需小量读取：只读相关函数/类，不全量读文件
大文件用 grep：超过 200 行的文件，用 grep 定位关键行
目录结构扫描：用 ls 而非读文件列表

Token 节省原则#

不是"只读一个章节"，而是"先读最相关的，必要时扩大"

始终有最小基准（项目定位 + 结构）
按任务类型追加相关章节
读不懂/查不清楚时，扩大读取，不是瞎猜
避免全量读 README，只读任务需要的部分

写入原则#

增量更新：只改相关章节，不重写整个文件
格式保持：更新时遵循已有格式和结构
最小改动：只写必要的更新，不过度描述

工作流程#

阶段 1：工作开始前 — 按需读取 README#

text

触发条件：
- 用户询问项目相关问题
- 用户要求查看/修改代码
- 任何需要了解项目背景的任务

动作：
1. 定位项目根目录的 README.md
2. 如果 README 不存在：
   a. 有代码 → 用 `auto-init` 扫描生成
   b. 空项目 → 继续工作，任务结束后询问是否创建
3. 根据任务类型，按"最小基准 + 按需叠加"读取相关章节
4. 总结所需信息，已知的不重复读取
5. 继续工作，不打断用户

阶段 2：工作进行中 — 缓存变更#

text

触发条件：
- 发现 README 与实际不符
- 完成了一个值得记录的功能
- 修复了一个重要 bug
- 进度有了实质推进

动作：
1. 将变更内容缓存（不立即写入）
   → 使用: python scripts/readme_operations.py add <type> <content>
2. 继续当前工作，不打断
3. 记录待更新条目（最多缓存 5 条）

判断是否值得记录：

✅ 新功能完成（重要的）
✅ Bug 修复（尤其是容易踩坑的）
✅ 进度里程碑
✅ 技术栈或依赖变更
❌ 显而易见的代码命名
❌ 一次性闲聊信息
❌ 推测性内容（未经确认）

阶段 3：工作结束后 — 写入确认#

text

触发条件：
- 工作基本完成（用户说"好了"、"完成了"）
- 或积累待更新条目 ≥ 3 条
- 或 session 结束时

动作：
1. 展示待更新内容摘要
   → 使用: python scripts/readme_operations.py pending
2. 询问用户确认：
   - 全部写入 / 部分写入 / 跳过
3. 用户确认后执行写入
   → 使用: python scripts/readme_operations.py sync

确认示例：

text

📝 README 有 2 处需要更新：
1. [changelog] 新增用户认证功能 @2026-04-14
2. [progress] 完成支付模块重构

确认写入？ (全部/部分/跳过)

README 标准格式#

markdown

# 项目名称

## 一句话定位
[项目是干什么的，1-2 行]

## 技术栈
- 语言/框架：xxx
- 数据库：xxx
- 其他关键依赖：xxx

## 项目结构

├── src/ # 源代码 ├── tests/ # 测试 └── docs/ # 文档

text


## 当前进度
- [x] 完成：xxx
- [ ] 进行中：xxx
- [ ] 计划中：xxx

## API 概览（如适用）
| 接口 | 说明 |
|------|------|
| GET /xxx | xxx |

## 踩坑记录
- ⚠️ xxx 容易搞错，要注意 xxx
- ❌ xxx 会导致 xxx，解决方案是 xxx

## 近期修改记录
<!-- 最近 10 条修改，按时间倒序 -->
| 日期 | 修改内容 | 相关文件/模块 |
|------|---------|--------------|
| 2026-04-14 | 新增用户认证功能 | src/auth/ |
| 2026-04-13 | 修复支付回调并发问题 | src/payment/ |