diff --git a/.claude/skills/doc/SKILL.md b/.claude/skills/doc/SKILL.md new file mode 100644 index 0000000..926af6d --- /dev/null +++ b/.claude/skills/doc/SKILL.md @@ -0,0 +1,101 @@ +--- +name: doc +description: 渐进式文档生成器。首次只写精炼梗概（≤300字），后续通过迭代不断完善。 +--- + +# Doc - 渐进式文档生成器 + +> **核心理念**：文档是缝缝补补长出来的，不是一步到位写出来的。首次只写最重要的梗概，后续通过讨论和迭代逐步完善。 + +当用户调用 `/doc` 或 `/doc <指令>` 时，执行以下步骤： + +## 1. 理解需求 + +如果用户提供了参数，使用该描述。否则询问要写什么文档。 + +快速确认（已知的不重复问）： + +| 项目 | 默认值 | +|------|--------| +| 文档主题 | 用户指令 | +| 输出路径 | 询问用户 | +| 作者署名 | 询问用户 | + +简短讨论文档边界：列出你理解的覆盖范围，标注不确定的点，让用户拍板。 + +> 你是执笔人，不是决策者。"写什么、不写什么"由用户决定。 + +## 2. 快速调研 + +聚焦调研，不求面面俱到： +- 扫描相关代码和现有文档 +- 提取核心概念、关键接口、主要数据流 +- 了解项目现有文档风格（命名、格式） + +调研完成后，用 2-3 句话告诉用户你发现了什么，有什么存疑的点。**不需要正式的大纲确认环节**，直接写梗概，快速拿到反馈比完美大纲更重要。 + +## 3. 生成梗概 + +### 3.1 写作原则 + +**首次写作（默认模式）**： +- **言简意赅**，建议控制在 300 字以内 +- 只写最重要的骨架：是什么、为什么、怎么用 +- 留白是刻意的，后续迭代会填充细节 +- 不需要面面俱到，抓住核心价值 + +**迭代补充**（用户再次调用 `/doc` 指向同一文件时）： +- 读取现有内容，在此基础上增量补充 +- 递增版本号，更新 `updated` 日期 +- 每次迭代聚焦一个方面，不要一次补太多 + +### 3.2 文档头部 + +```markdown +--- +title: {文档标题} +version: v1.0 +created: {YYYY-MM-DD} +updated: {YYYY-MM-DD} +author: {作者署名} +--- +``` + +### 3.3 内容要求 + +- **准确**：基于实际代码，不编造 +- **精炼**：一句话能说清的不用两句 +- **实用**：面向读者，提供可操作的信息 +- 善用表格、代码块、ASCII 图示（但首次不强求） + +## 4. 保存并输出 + +保存到用户指定路径。如果文件已存在，先询问是覆盖还是增量更新。 + +输出摘要： + +```text +文档: {标题} | 版本: v1.0 | 路径: {path} +字数: ~{N}字（首版梗概） + +后续可以通过 /doc 继续补充完善。 +主人，用不用我沉淀 or git 提交？ +``` + +## 工作流总览 + +```text +/doc <指令> + │ + ├── 1. 理解需求（简短确认主题、路径、署名） + ├── 2. 快速调研（聚焦核心，不求全面） + ├── 3. 生成梗概（≤300字，抓骨架） + └── 4. 保存输出（鼓励后续迭代） +``` + +## 注意事项 + +- **少即是多**：首版宁短勿长，300 字是指导建议而非硬限制 +- **鼓励迭代**：每次 `/doc` 都是一次对话机会，文档在讨论中成长 +- **不做代码改动**：本 skill 只生成文档 +- **风格一致**：与项目已有文档风格保持一致 diff --git a/.codex/skills/AGENTS.md.template b/.codex/skills/AGENTS.md.template index 147d4c9..3e419ed 100644 --- a/.codex/skills/AGENTS.md.template +++ b/.codex/skills/AGENTS.md.template @@ -25,6 +25,7 @@ - `mt`: 增量修改 tasks.md，根据用户指令在现有内容基础上更新任务列表。 (file: `./.codex/skills/mt/SKILL.md`) - `go`: 终极执行按钮，激进模式一口气完成开发任务，兼容 0->1 和 1->100 场景。 (file: `./.codex/skills/go/SKILL.md`) - `iter`: 迭代变更入口，调研问题后更新 PRD.md 和 tasks.md，支持 Bug 修复、功能迭代、技术重构。 (file: `./.codex/skills/iter/SKILL.md`) +- `doc`: 渐进式文档生成器。首次只写精炼梗概（≤300字），后续通过迭代不断完善。 (file: `./.codex/skills/doc/SKILL.md`) - `update`: 收集用户反馈并更新最近使用的 skill。别名：`up`。 (file: `./.codex/skills/up/SKILL.md`) - `deploy`: Drone CI + 服务器 CD 全流程引导：从基础设施检查到生成配置文件到验证部署，交互式完成。 (file: `./.codex/skills/deploy/SKILL.md`) - `changelog`: 一键发版：生成更新日志 → commit → 打 tag，全流程自动化。 (file: `./.codex/skills/changelog/SKILL.md`) diff --git a/.codex/skills/doc/SKILL.md b/.codex/skills/doc/SKILL.md new file mode 100644 index 0000000..2307bf2 --- /dev/null +++ b/.codex/skills/doc/SKILL.md @@ -0,0 +1,101 @@ +--- +name: doc +description: 渐进式文档生成器。首次只写精炼梗概（≤300字），后续通过迭代不断完善。 +--- + +# Doc - 渐进式文档生成器 + +> **核心理念**：文档是缝缝补补长出来的，不是一步到位写出来的。首次只写最重要的梗概，后续通过讨论和迭代逐步完善。 + +当用户调用 `doc` skill、`$doc`，或自然语言要求“用 doc 写文档”时，执行以下步骤： + +## 1. 理解需求 + +如果用户提供了参数，使用该描述。否则询问要写什么文档。 + +快速确认（已知的不重复问）： + +| 项目 | 默认值 | +|------|--------| +| 文档主题 | 用户指令 | +| 输出路径 | 询问用户 | +| 作者署名 | 询问用户 | + +简短讨论文档边界：列出你理解的覆盖范围，标注不确定的点，让用户拍板。 + +> 你是执笔人，不是决策者。"写什么、不写什么"由用户决定。 + +## 2. 快速调研 + +聚焦调研，不求面面俱到： +- 扫描相关代码和现有文档 +- 提取核心概念、关键接口、主要数据流 +- 了解项目现有文档风格（命名、格式） + +调研完成后，用 2-3 句话告诉用户你发现了什么，有什么存疑的点。**不需要正式的大纲确认环节**，直接写梗概，快速拿到反馈比完美大纲更重要。 + +## 3. 生成梗概 + +### 3.1 写作原则 + +**首次写作（默认模式）**： +- **言简意赅**，建议控制在 300 字以内 +- 只写最重要的骨架：是什么、为什么、怎么用 +- 留白是刻意的，后续迭代会填充细节 +- 不需要面面俱到，抓住核心价值 + +**迭代补充**（用户再次调用 `doc` 指向同一文件时）： +- 读取现有内容，在此基础上增量补充 +- 递增版本号，更新 `updated` 日期 +- 每次迭代聚焦一个方面，不要一次补太多 + +### 3.2 文档头部 + +```markdown +--- +title: {文档标题} +version: v1.0 +created: {YYYY-MM-DD} +updated: {YYYY-MM-DD} +author: {作者署名} +--- +``` + +### 3.3 内容要求 + +- **准确**：基于实际代码，不编造 +- **精炼**：一句话能说清的不用两句 +- **实用**：面向读者，提供可操作的信息 +- 善用表格、代码块、ASCII 图示（但首次不强求） + +## 4. 保存并输出 + +保存到用户指定路径。如果文件已存在，先询问是覆盖还是增量更新。 + +输出摘要： + +```text +文档: {标题} | 版本: v1.0 | 路径: {path} +字数: ~{N}字（首版梗概） + +后续可以通过 $doc 继续补充完善。 +主人，用不用我沉淀 or git 提交？ +``` + +## 工作流总览 + +```text +$doc <指令> + │ + ├── 1. 理解需求（简短确认主题、路径、署名） + ├── 2. 快速调研（聚焦核心，不求全面） + ├── 3. 生成梗概（≤300字，抓骨架） + └── 4. 保存输出（鼓励后续迭代） +``` + +## 注意事项 + +- **少即是多**：首版宁短勿长，300 字是指导建议而非硬限制 +- **鼓励迭代**：每次 `doc` 都是一次对话机会，文档在讨论中成长 +- **不做代码改动**：本 skill 只生成文档 +- **风格一致**：与项目已有文档风格保持一致 diff --git a/.gitignore b/.gitignore index 4db4617..e0d28a2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ # 文档目录（各项目自己生成） -doc/ +/doc/ # 其他开发文件 write-skills/ diff --git a/AGENTS.md b/AGENTS.md index dd2e9fb..8665d42 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,6 +21,7 @@ - `mt`: 增量修改 tasks.md，根据用户指令在现有内容基础上更新任务列表。 (file: `./.codex/skills/mt/SKILL.md`) - `go`: 终极执行按钮，激进模式一口气完成开发任务，兼容 0->1 和 1->100 场景。 (file: `./.codex/skills/go/SKILL.md`) - `iter`: 迭代变更入口，调研问题后更新 PRD.md 和 tasks.md，支持 Bug 修复、功能迭代、技术重构。 (file: `./.codex/skills/iter/SKILL.md`) +- `doc`: 渐进式文档生成器。首次只写精炼梗概（≤300字），后续通过迭代不断完善。 (file: `./.codex/skills/doc/SKILL.md`) - `update`: 收集用户反馈并更新最近使用的 skill。别名：`up`。 (file: `./.codex/skills/up/SKILL.md`) - `deploy`: Drone CI + 服务器 CD 全流程引导：从基础设施检查到生成配置文件到验证部署，交互式完成。 (file: `./.codex/skills/deploy/SKILL.md`) - `changelog`: 一键发版：生成更新日志 → commit → 打 tag，全流程自动化。 (file: `./.codex/skills/changelog/SKILL.md`) diff --git a/AGENTS.md.template b/AGENTS.md.template index 147d4c9..3e419ed 100644 --- a/AGENTS.md.template +++ b/AGENTS.md.template @@ -25,6 +25,7 @@ - `mt`: 增量修改 tasks.md，根据用户指令在现有内容基础上更新任务列表。 (file: `./.codex/skills/mt/SKILL.md`) - `go`: 终极执行按钮，激进模式一口气完成开发任务，兼容 0->1 和 1->100 场景。 (file: `./.codex/skills/go/SKILL.md`) - `iter`: 迭代变更入口，调研问题后更新 PRD.md 和 tasks.md，支持 Bug 修复、功能迭代、技术重构。 (file: `./.codex/skills/iter/SKILL.md`) +- `doc`: 渐进式文档生成器。首次只写精炼梗概（≤300字），后续通过迭代不断完善。 (file: `./.codex/skills/doc/SKILL.md`) - `update`: 收集用户反馈并更新最近使用的 skill。别名：`up`。 (file: `./.codex/skills/up/SKILL.md`) - `deploy`: Drone CI + 服务器 CD 全流程引导：从基础设施检查到生成配置文件到验证部署，交互式完成。 (file: `./.codex/skills/deploy/SKILL.md`) - `changelog`: 一键发版：生成更新日志 → commit → 打 tag，全流程自动化。 (file: `./.codex/skills/changelog/SKILL.md`) diff --git a/README.md b/README.md index 3b531c0..f440f71 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,7 @@ RequirementsDoc ──▶ PRD ──▶ FeatureSummary ──▶ DevelopmentPlan | | `mt` | `/mt` | `$mt` | 增量修改 tasks | | **执行** | `go` | `/go` | `$go` | 🚀 发射按钮，激进模式一口气完成开发 | | **辅助** | `iter` | `/iter` | `$iter` | 迭代变更入口（Bug/功能/重构） | +| | `doc` | `/doc` | `$doc` | 渐进式文档生成器，先写梗概再迭代完善 | | | `update` | `/up` | `$update` 或 `$up` | Skill 升级优化 | | | `deploy` | `/deploy` | `$deploy` | Drone CI/CD 全流程部署引导 | | | `changelog` | `/changelog` | `$changelog` | 一键发版（日志 + commit + tag） | @@ -131,6 +132,7 @@ $go 请用 rr skill 评审 doc/RequirementsDoc.md 请用 wf skill 根据 PRD 生成 FeatureSummary 请用 go skill 按 doc/tasks.md 执行未完成任务 +请用 doc skill 为认证模块写一份 300 字以内的使用说明 ``` ### 工作流总览