README Sync

在每次代码查询/修改工作开始前按需读取README.md了解项目状态，工作结束后按需更新README。触发场景：(1)用户询问项目相关问题（如"并发数是多少？"），(2)需要进行代码查询或修改时。读取时无需确认；写入README或代码时必须先确认。支持跨平台（Claude Code、OpenClaw、Trae、C...

Security Scan

The skill's purpose (read/update README) matches the included code, but the runtime instructions promise confirmation before writes while the shipped script performs writes (sync) and pending-item changes without interactive confirmation — an inconsistency that could lead to unprompted file modification if the agent invokes the skill autonomously.

Purpose & Capability

Name, description, SKILL.md, README.md and the included Python script all align: this skill is intended to read, scan, and update README.md and to cache pending update items. No unrelated credentials, binaries, or external services are requested.

Instruction Scope

SKILL.md repeatedly states that writes to README or code require user confirmation and that reads do not. The shipped script, however, will: (1) add pending items immediately (add_pending writes .readme_pending.json without confirmation), and (2) sync_to_readme writes README.md directly (no interactive confirmation in sync_to_readme). This is a direct mismatch between declared runtime policy and actual file operations. The script also scans the repository (iterates directories and lists code files) which is expected for the purpose but means it will access repo structure and up to 20 code file paths.

Install Mechanism

Instruction-only skill with a small Python utility included. No installers, downloads, or external packages are requested. No extracted archives or remote code installs were declared.

Credentials

The skill requests no environment variables, no credentials, and no config paths. File access is limited to the project tree (README.md and a dotfile .readme_pending.json), which is proportional to the documented functionality.

Persistence & Privilege

The skill is not force-enabled (always: false) and asks no special permissions, but it will write to repository files (.readme_pending.json and README.md). Because autonomous invocation is permitted by default on the platform, the mismatch (SKILL.md says writes require confirmation while the code performs writes without prompting) increases the risk of unintentional or unattended modifications. The skill does not modify other skills or system-wide settings.

What to consider before installing

This skill appears to do what it says (read/scan/update README), but there is a meaningful inconsistency: the documentation promises user confirmation before any write, yet the included script performs writes without prompting (adding pending items and the sync operation). Before installing or enabling it for autonomous use, consider: - Review the full scripts locally. Search for functions named sync, add, auto-init and confirm whether they prompt before writing. In particular, patch sync_to_readme to require explicit user confirmation if you expect interactive approval. - Test the tool in a disposable repository (backup your README first). Verify behavior of add, pending, sync, init, and auto-init commands. - If you plan to allow autonomous agent invocation, disable autonomous use until you can ensure writes are always gated by an explicit user prompt. Alternatively, restrict the skill to user-invoked only. - Note the skill creates a .readme_pending.json file in the project root; review that file for any cached content you may not want committed. - There is a truncated/possibly buggy section in the provided script (a partial token like "item.name.star" appears in the package listing). Verify the script runs correctly and fix any bugs before use. If the author updates the code so that all write actions prompt for explicit confirmation (or documents clearly which commands are non-interactive), the current concerns would be resolved.

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

---

工具脚本

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

# 读取指定章节（按需读取，节省 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 不存在时的处理

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

---

核心原则

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

---

按需加载策略（节省 Token）

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

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

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

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

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

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

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

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

代码文件读取原则

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

Token 节省原则

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

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

写入原则

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

---

工作流程

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

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

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

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

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

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

判断是否值得记录：

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

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

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

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

确认示例：

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

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

---

README 标准格式

# 项目名称

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

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

## 项目结构

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

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

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

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

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

近期修改记录说明

字段	说明
日期	格式 YYYY-MM-DD
修改内容	一句话描述，动词优先（新增/修复/重构/更新）
相关文件/模块	方便定位，可选

为什么需要这个章节：

• 同事 Review：快速了解近期变动，不用翻 git log
• AI 上下文：新 session 开始时快速掌握项目近况
• 历史追溯：出问题能快速定位到相关的修改

维护规则：

• 只保留最近 10 条，更早的归档到 git commit message
• 单条不超过 50 字
• 与 ## 当前进度 保持一致（完成的移到"完成"列表）

---

平台兼容性说明

平台	README 支持	额外支持
Claude Code	✅	CLAUDE.md（原生）
OpenClaw	✅	—
Trae	✅	—
Cursor	✅	.cursorrules
Copilot	⚠️	依赖用户引导

核心策略： README.md 是所有平台都能读取的标准格式，优先保证它是最新的。

---

触发指令

指令	何时用
/readme sync	手动触发同步，查看待更新内容
/readme status	查看 README 当前状态和缓存条数
/readme diff	查看 README 与实际项目的差异

---

注意事项

1. 不自动重写 README — 只更新与工作相关的章节
2. 按需加载 — 只读任务需要的部分，不全量加载
3. 最小改动 — 只写必要的更新，不过度描述
4. 中文优先 — 项目文档使用中文（README.md 中文优先，英文项目可用英文）
5. 修改记录要及时归档 — 保持最近 10 条，过期移到 git 历史