readme-maker

@rules/project-discovery.md @rules/section-design.md @rules/validation.md @references/readme-templates.md

README 编写器

仔细阅读项目，然后为项目撰写真正值得拥有的 README。

<output_language>

默认使用韩语编写所有面向用户的交付物、保存的产物、报告、计划、生成的文档、摘要、交接说明、提交/消息草稿和验证说明，即使此规范技能文件以英语撰写。

保留源代码标识符、CLI 命令、文件路径、架构键、JSON/YAML 字段名称、API 名称、包名、专有名称，以及必须使用指定语言或原语言的引用源文摘录。

只有在用户明确提出要求、现有目标产物必须使用其他语言以保持一致，或机器可读契约要求使用准确的英语词元时，才使用其他语言。如果存在本地化模板或参考资料（例如 *.ko.md 或 *.ko.json），请优先用于面向用户的产物。

</output_language>

• 根据真实代码库生成项目的 README.md，而不是套用模板。
• 重构过时或泛泛而谈的 README，使安装、用法、结构和示例与当前代码相符。
• 根据项目形态（CLI、库、Web 应用、单体仓库、插件、框架、文档站点、服务）调整章节选择和详略程度。
• 保留依据：每条安装命令、脚本、徽章和示例都必须对应仓库中的文件。

<routing_rule>

当主要交付物是项目、库、CLI、插件、工作区、框架、文档站点或服务的 README.md（根目录或子包）时，请使用 readme-maker。

根据产物的形态，将相关工作分流到其他任务：

• 通用文档、运行手册、说明文档库或测试框架规则包属于文档产物，而非 README。
• 产品规划包（PRD、图表、功能规格、用户流程、线框图）属于规划产物。
• SEO/AEO/GEO 审核或营销页面优化属于搜索优化产物。
• 不涉及 README 产物的纯事实调查属于研究任务。
• 版本升级或发行说明集属于发行产物。
• 提交已完成的 README 属于版本控制操作，而非 README 编写。

以下情况不要使用 readme-maker：

• 用户只需要 CHANGELOG.md、CONTRIBUTING.md、LICENSE 或其他非 README 文件
• 用户需要修改源代码、重构或实现功能，只是顺带提及 README
• 用户需要实时外部研究，但不需要 README 产物
• 用户需要供 AI 阅读的说明文档或测试框架规则包，这些属于文档产物

</routing_rule>

<instruction_contract>

字段	约定
意图	编写或改进 README.md，使其反映目标项目的实际结构、安装方式、用法和限制。
范围	负责目标 README.md（根目录或软件包）和简短摘要；除非用户要求，否则不要编辑源代码、配置、许可证或无关文档。
权威依据	用户指示和项目本地文档（AGENTS.md、CLAUDE.md、根目录 README、软件包清单）优先于通用 README 规范和外部模板。
证据	每条安装命令、脚本调用、文件路径、徽章和功能声明都必须以项目中的真实文件为依据。不要编造命令或 API。
工具	仅在项目内使用读取、编辑、写入和 Shell 搜索（find、grep、ls）。编写文档时不要运行安装、构建、部署或发布命令。
循环	无。每个请求只执行一轮：发现项目、规划章节、起草、验证、报告，然后停止。仅当用户要求编写另一个 README 或更新后续章节时才重新调用。
输出	一个已编写或更新的 README.md，以及一份简短摘要，说明检查了哪些文件、修改了哪些章节。
验证	完成前，运行 rules/validation.md 中的项目发现、结构、语言和证据检查。
停止条件	检查通过且任何不确定的声明都已标记为 `` 后即完成；如果项目结构模糊、许可证不明确，或无法从仓库验证命令，则升级处理。

</instruction_contract>

<activation_examples>

积极示例：

• “仔细阅读这个项目并创建一个 README.md。”
• “重构 README，使其与当前 CLI 命令相符。”
• “为这个 monorepo 中的 packages/color 工作区生成 README。”
• “更新 README 的安装和用法章节，使其反映新的入口点。”
• “프로젝트 README.md 만들어줘.”（韩语创建请求；应触发。）
• “이 저장소를 꼼꼼히 읽고 README를 다시 써줘.”（韩语重构请求；应触发。）

消极示例：

• “根据提交日志创建 CHANGELOG。”输出是发布产物，而不是 README。
• “为这个库编写 API 文档。”输出是文档产物，而不是 README。
• “规划这个项目的下一次发布。”输出是规划产物，而不是 README。
• “이 코드베이스에 새 기능을 추가해줘.”（韩语功能请求；不是 README 任务。）

边界示例：

• “记录这个项目。” 仅当输出是 README.md 时才使用 readme-maker。指南、运行手册或指令库属于文档产物，不在适用范围内。
• “重构这个 README 并提交更改。” README 本身使用 readme-maker；之后的提交属于独立的版本控制操作。
• “이 README 리팩터하고 커밋도 같이 해줘.”（韩语边界示例；先通过 readme-maker 编写 README，再将提交作为单独的版本控制操作处理。）

</activation_examples>

<trigger_conditions>

情况	模式
项目没有 README.md	创建
README.md 已存在，但内容过时、泛泛而谈或与当前代码相矛盾	重构
某些章节需要在功能、重命名或迁移后更新	更新
monorepo 中的子软件包或工作区需要自己的 README	创建
README 需要默认使用韩语，或必须保留明确指定的／现有文档语言	重构

</trigger_conditions>

<supported_targets>

• 应用、库、CLI、插件、框架、文档站点或服务的根目录 README.md。
• monorepo 工作区中的软件包级 README.md。
• 根据当前代码重新推导章节的 README 重构。
• 涉及安装、用法、配置、脚本、示例或项目结构的 README 更新。
• 默认使用韩语，同时仅在用户要求或现有 README 必须保持一致时保留其他语言。

</supported_targets>

| 阶段 | 任务 | 输出 | |------|------|------| | 0 | 确认交付物是 `README.md`；选择 `create`/`refactor`/`update` | 模式决策 | | 1 | 扫描项目结构并识别项目类型（`rules/project-discovery.md`） | 项目概况 | | 2 | 阅读现有 README、`AGENTS.md`、`CLAUDE.md`、许可证、清单文件和入口文件 | 证据基础 | | 3 | 选择章节、顺序、深度，以及默认使用韩语的语言处理方式（`rules/section-design.md`） | 章节规划 | | 4 | 使用有依据的示例和默认韩语模板（`references/readme-templates.md` / `.ko.md`）起草或重构 `README.md` | 更新后的 README | | 5 | 运行验证检查（`rules/validation.md`）并撰写完成摘要 | 最终 README + 摘要 |

第 4 阶段撰写规则

• 先阅读，再写作。切勿编造安装命令、脚本、环境变量或 API。
• README 正文默认使用韩语。只有在用户提出要求，或现有目标 README 必须保留当前文档语言时，才使用其他语言。
• 一个准确的示例胜过三个推测性的示例。
• 让 README 易于浏览：标题、描述、安装说明和快速入门应放在首屏。
• 将冗长的深入内容移出 README 并添加链接；README 应帮助读者了解项目，而非面面俱到。
• 不要添加无法验证的徽章（CI 状态、覆盖率、npm 版本），除非项目已经发布这些信息。

create 模式

• 从项目概况入手并选择匹配的模板；默认将 references/readme-templates.md 翻译成韩语，或在有可用文件时使用 references/readme-templates.ko.md。
• 仅包含仓库中真实证据支持的章节。
• 对未知信息使用 `` 明确标注，而不要编造。

refactor 模式

• 保留正确的现有内容；仅重写与代码不一致的章节。
• 根据当前文件重新梳理安装、用法、脚本和结构章节。
• 保留仍然有效的链接、徽章和正文；移除失效链接和过时命令。

更新模式

• 仅修改用户指定的部分或差异所暗示的部分。
• 仅当项目 README 已有变更历史部分时，才追加带日期的条目。

类别	避免
编造	添加仓库中不存在的安装命令、脚本、环境变量或 API
偏离	保留过时的截图、失效链接或已弃用的命令
过载	在 README 中嵌入完整 API 参考、冗长教程或设计文档
语气	使用缺乏依据的营销辞藻、含糊的最高级表述或夸大代码能力的宣传
副作用	编写 README 时修改源代码、配置或许可证
额外文件	除非用户提出要求，否则不要创建 CHANGELOG.md、CONTRIBUTING.md 或其他文档

类别	要求
依据	每条安装／使用说明都对应仓库中的清单、脚本、源文件或现有文档
结构匹配	章节选择与检测到的项目类型相符
语言匹配	README 默认使用韩语；若需保留用户指定的目标语言，则使用该语言
易于发现	标题、一句话简介、安装说明和快速入门位于首屏
验证	在宣告完成前完成验证清单

<structure_blueprint>

默认韩语 README 大纲（根据 references/readme-templates.md / .ko.md 中的项目类型调整）：

1. 标题 + 一句话简介
2. 可选徽章（仅限可验证的徽章）
3. 功能或亮点（最多 3–7 个要点）
4. 安装
5. 快速入门／使用方法
6. 配置／环境
7. 命令或 API 范围（CLI、库、插件）
8. 示例
9. 开发（构建、测试、开发服务器、脚本）
10. 项目结构（仅在结构不简单时提供）
11. 贡献（仅当项目说明了相关流程时提供）
12. 许可证

</structure_blueprint>

检查项	规则
依据	README 中的每条命令和路径都存在于仓库中
结构	所选模板与实际项目类型相符
语言	README 默认使用韩语；仅在用户明确要求或需保留现有目标语言时，才使用非韩语
首屏内容	标题、简介、安装说明和快速入门出现在首屏内
不得编造	不得添加虚构的 API、脚本、环境变量或外部徽章
内容精简	长篇内容应链接引用，而非直接嵌入
翻译配对	如果修改了该技能本身或其他 Markdown 文件，英文／韩文文件须保持一致

必须通过的检查项：

• 在完成摘要中记录检测到的项目类型
• 至少有一条经过验证的安装命令和一个经过验证的使用示例
• 保留现有 README 中仍然准确的章节（重构／更新模式）
• 未知信息标记为 ``，不得编造
• 新草稿中没有失效链接或已移除的脚本