0x0w1/jig

自述文件

使用此技能根据仓库实际状态创建或更新仓库的 README.md。

执行流程

1. 扫描仓库：
   • 清单和构建文件：pyproject.toml、package.json、Cargo.toml、go.mod、Makefile、锁定文件。
   • 入口点、CLI 参数定义、脚本和服务配置（Dockerfile、docker-compose*.yml）。
   • docs/ 下的现有文档以及代码中的使用示例。
2. 对项目类型进行分类：CLI 工具、库、服务/应用或其他。当未设置配置文件时，此类型将选择下面的章节布局。
3. 根据下面的配置文件合约，确定自述文件配置文件。解析后的配置文件将替换此仓库的通用默认值；当没有配置文件解析时，请提出一个配置文件，然后无论哪种方式都继续执行。
4. 根据当前状态分支：
   • 无 README.md → 创建路径：使用下面的章节布局起草自述文件。
   • README.md 存在 → 更新路径：对照仓库检查自述文件中的每个可验证声明——命令、选项、文件路径、链接、功能陈述。将不匹配项收集到漂移列表中，报告该列表，然后应用修复。保持仍然准确的章节不变。
5. 对编写的每一行应用准确性规则。
6. 按照下面的压缩规则执行压缩步骤：
   • 创建路径：在起草时应用它。尚未发布任何内容，因此无需提出任何建议。
   • 更新路径：将重复和夸大之处收集到一个提案中——命名每个事实、其重复位置以及将容纳它的详细文档——然后在移动任何内容之前征求意见。即使用户拒绝该提案，也要报告它。
7. 合并更改：
   • 当仓库具有 develop-task-flow 技能（或已安装的 jig-develop-task-flow）时，遵循它：一个 chore/<slug> 分支，带有 docs: 提交的压缩合并，然后推送 develop。
   • 否则，在当前分支上提出一个普通的提交。

配置文件合约

两个属于相同项目类型的仓库仍然以不同方式编写其自述文件：一个保留翻译镜像，另一个将安装移入指南，第三个具有其贡献者已经遵循的表格惯例。这些是决策，而不是可以通过扫描仓库获得的事实，因此它们被记录一次，并在每次后续运行时读取。

按以下顺序解析配置文件：

1. JIG_README_PROFILE 环境变量。
2. git config --local --get jig.readmeProfile。
3. .jig/readme.md。

当配置文件解析时，它会覆盖该仓库的章节布局和语言规则；它未提及的任何内容都将回退到这些规则。读取它，遵循它，并在报告中命名它。

当没有配置文件解析时，根据扫描结果草拟一份并提出：分类的类型、仓库已使用的语言、是否存在镜像、当前自述文件所暗示的章节顺序，以及哪些详细文档已经容纳了溢出内容。仅在用户接受后才写入 .jig/readme.md。如果用户拒绝或不回答，则继续使用通用默认值并说明情况——缺少配置文件是正常状态，而不是障碍。

文件仅记录决策。它不包含阈值或检查清单；自述文件质量仍然是此技能在仓库面前做出的判断。

# 自述文件配置文件

> 依据：<决策依据>，<YYYY-MM-DD>

## 语言

规范语言：`README.md`（英语）。镜像：`README.ko.md`（韩语），在同一任务中更新。

## 章节

标题和链接行、这是什么、快速入门、技能、文档、许可。

## 详细文档

安装选项 → `docs/installation.md`。路线图和设计记录 → `docs/roadmap.md`，仅从文档主页链接。

## 惯例

标识符表格将描述单元格限制为一个从句。贡献者命令保持在 `<details>` 块中。

章节标题是合约；其下的散文属于该仓库。如果使用这些标题，则在此标题存在之前编写的配置文件仍然可以正确读取。

章节布局

必需章节，按顺序排列：

1. 标题加一行描述。
2. 简介：项目做什么以及为何存在。
3. 安装。
4. 用法。

按项目类型的补充：

• CLI 工具：命令和选项表。
• 库：带有示例代码的 API 摘要。
• 服务/应用：如何运行（开发和生产）以及所需的环境变量。

可选：文档链接、许可。

布局规则

• 对于人们复制的内容——技能名称、命令、选项、路径——表格是不错的选择。破坏此类名称的是列之间的宽度比例：GitHub 按内容调整列大小，因此比标识符列长几倍的描述列会挤压标识符，直到它在中间换行，读者看到的名称并不存在。
• 保持描述单元格与标识符大致一样短，大约一个从句。当描述过长时，要么修剪它们，要么将整个内容移至列表中：- **\name`** — 描述`。
• 描述内的换行是预期行为，无需处理。

压缩规则

自述文件是在读者决定使用项目之前阅读的。其中的所有内容都在争夺这种注意力，因此长度是一种症状：长自述文件几乎总是一个事实写在多个地方，而不是一个项目有很多话要说。

移动，不要删除。 当同一事实出现多次时，将其保留在读者首先到达的一个位置，并将其余内容移至已涵盖该事实的详细文档中，仅当不存在此类文档时才创建它。没有丢失任何东西；自述文件不再重复自身。没有要达成的行数——包含其真正需要的 API 示例的库自述文件并不算长，而一个简短但重复说的同一件事的自述文件仍然有问题。

以读者获得的收益开头。 简介说明什么变得更容易，而不是存在哪些功能。记录合并时的分级发布说明 是一个功能；你不再需要重构版本为何是次要版本 是读者获得的收益。按证据的强弱对声明进行排序，最强的在前，并让周围的散文按相同顺序列出它们——段落及其项目符号不得暗示不同的优先级。

只声称仓库可以支持的内容，并说明何时适用。 仓库无法证明的声明将被省略，而不是被软化。说明价值出现的条件，以便处于该条件之外的读者可以快速排除项目，而不是稍后发现它。

删除安装前不会阅读的内容。 路线图、设计记录和方向说明是项目为自己保留的内容。从文档主页链接它们，而不是从自述文件。

折叠贡献者材料。 构建、重新生成和验证命令服务于已经克隆仓库的人。将它们放在 <details> 块或贡献文档中。

合并仅因一个值而不同的块。 针对不同平台或目标的单独命令块，如果仅因参数而异，则合并为一个块，其中命名该参数。

为读者提供越过顶部的方法。 当自述文件有超过大约四个章节时，在标题下放置一行链接行，以便返回的读者直接跳转到他们要找的章节。

准确性规则

• 只编写针对仓库验证过的安装和运行命令：脚本、清单或锁定文件必须显示它们。
• 验证每个链接的文件路径是否存在。
• 不要描述仓库不包含的功能、徽章或集成。
• 当声明无法验证时，将其省略并报告。

安全规则

• 仅在用户接受提案后才编写 .jig/readme.md，并且绝不会作为普通自述文件更新的副产品。
• 未经明确确认，绝不覆盖现有的 .jig/readme.md。提出更改并说明它所替换的内容。
• 不触及 .jig/ 下的其他任何内容。version-rubric 拥有 .jig/versioning.md。
• 永远不会静默地重构已发布的自述文件；压缩步骤会等待并征求意见。
• 保留不相关的用户更改。

语言规则

• 保留现有自述文件的语言。
• 新自述文件使用该仓库已有的文档语言编写，默认为英语，技术术语使用反引号。
• 用户的明确语言请求优先于两者。

报告

• 项目类型以及所采取路径（创建或更新）。
• 自述文件配置文件：路径和来源，或已提出但被拒绝，或不存在并运行通用默认值。
• 对于更新路径：漂移列表以及已修复的内容。
• 压缩提案：每个在多个地方重复的事实，其移动位置，以及用户是否接受。
• 无法验证并被省略的声明。