crafting-effective-readmes
TraeWork 内置 skill —— 写或改进 README 文件。核心理念：README 不是给自己看的，是给目标读者看的——不同读者需要不同内容。
一、定位
| 字段 | 值 |
|---|---|
| 所属 | TraeWork 内置 skill（写作类） |
| 触发条件 | 写新 README、补充新章节、更新过时内容、审查现有 README |
| 核心方法 | 先识别「任务类型」+「项目类型」，再选对应模板 |
| 核心理念 | Always ask: Who will read this, and what do they need to know? |
二、4 种任务类型
| 任务 | 何时使用 |
|---|---|
| Creating | 新项目，还没有 README |
| Adding | 项目已有 README，但需要补充新章节 |
| Updating | 能力变了，内容过时了 |
| Reviewing | 检查 README 是否仍然准确 |
三、4 种项目类型
每种项目类型的读者、关键章节、对应模板都不同：
| 项目类型 | 目标读者 | 关键章节 | 模板 |
|---|---|---|---|
| Open Source | 贡献者、全球用户 | Install、Usage、Contributing、License | templates/oss.md |
| Personal | 未来的自己、作品集访客 | What it does、Tech stack、Learnings | templates/personal.md |
| Internal | 团队同事、新人 | Setup、Architecture、Runbooks | templates/internal.md |
| Config | 未来的自己（困惑时） | What’s here、Why、How to extend、Gotchas | templates/xdg-config.md |
重要纪律：不要默认所有项目都是开源 README——每个项目的读者不同，需要的内容也不同。
四、4 个流程步骤
4.1 Step 1：识别任务
先问自己：「我现在在做哪种 README 任务？」
判断是 Creating / Adding / Updating / Reviewing 中的哪一种。
4.2 Step 2：任务专属问题
Creating 初始 README 时问：
- 什么类型的项目？（看上面的项目类型表）
- 一句话能说清解决什么问题？
- 让它跑起来的最快路径是什么？
- 有什么特别值得强调的？
Adding 新章节时问：
- 需要文档化什么？
- 应该放在现有结构的哪里？
- 谁最需要这个信息？
Updating 更新内容时问：
- 什么变了？
- 读当前 README，识别过时章节
- 提出具体修改
Reviewing 审查时问：
- 读当前 README
- 对照实际项目状态（package.json、main files）
- 标记过时章节
- 如果有「Last reviewed」日期，更新它
4.3 Step 3：总是要问
草稿完成后，永远要问用户：
「Anything else to highlight or include that I might have missed?」
（还有什么我可能漏掉的要重点说或加进去的吗？）
4.4 Step 4：所有类型都必备的章节
每个 README 至少要包含：
- Name — 自解释的标题
- Description — 1-2 句话说清「是什么」+「为什么」
- Usage — 怎么用（最好带示例）
五、AskUserQuestion 模板
在写 README 前，可以用 AskUserQuestion 工具问用户：
- 这是哪类项目（OSS / Personal / Internal / Config）？
- 目标读者是谁？
- 现在在做哪种任务（Creating / Adding / Updating / Reviewing）？
- 「一句话讲清它解决什么问题」是什么？
六、可用资源
| 文档 | 内容 |
|---|---|
section-checklist.md | 各项目类型该包含哪些章节的清单 |
style-guide.md | README 常见错误和写作建议 |
using-references.md | 怎么使用深度参考材料 |
templates/oss.md | 开源项目模板 |
templates/personal.md | 个人项目模板 |
templates/internal.md | 内部项目模板 |
templates/xdg-config.md | 配置文件模板 |
七、常见反模式
| 反模式 | 后果 | 正确做法 |
|---|---|---|
| 假设所有项目都是 OSS README | 写的内容读者不关心 | 先识别项目类型 |
| 一上来就写完整 README | 容易跑偏 | 先用模板搭骨架 |
| 写完不 Review | 内容和代码脱节 | 定期对照项目状态审查 |
| 章节全而不精 | 重点信息被淹没 | 必备 3 项 + 按需扩展 |
| 自嗨式介绍 | 读者找不到关键信息 | 1-2 句说清「做什么 + 为什么」 |
八、引用来源
- TraeWork 实际 skill 路径 —— 本文内容完全来自此文件
- 同目录下的
templates/和references/文件夹
九、一句话总结
crafting-effective-readmes 是「按读者写 README」的方法论——4 种任务类型 + 4 种项目类型 = 16 种组合，永远先问「读者是谁、他们要什么」，再选对应模板。README 不是给自己看的，是给目标读者用的。