文档维护
何时使用
- 新增/修改子命令后,同步 help 文本和 docs 项目说明
- 发版时更新 changelog
- 检查文档与代码实现的一致性
流程
1. Help 文本一致性检查
运行所有命令的 --help,对比 README 命令说明与 docs/development.md:
node bin/devkeel.js --help
node bin/devkeel.js init --help
node bin/devkeel.js doctor --help
node bin/devkeel.js update --help
node bin/devkeel.js sync --help
node bin/devkeel.js evidence --help
检查点:
- README 与 docs 中列出的命令是否与实际一致
- 选项(--fix, --force, --dry-run)是否都有记录
- 不得只用退出码判断命令存在;未知命令可能退回 root help,必须确认输出的 Usage/Options 属于目标子命令
2. 项目知识同步
对比 src/ 实际目录结构与 docs/architecture.md,确认:
- 新增的 commands/lib 文件已记录
- 文件职责描述准确
- 测试入口与环境变化同步
docs/testing.md,规则复用已有测试策略 - AGENTS/CLAUDE 只维护文档入口与读取条件,不复制正文
- 当前规范保留在
openspec/specs/,任务过程保留在openspec/changes/
3. Changelog 维护
按 .harness/skills/changelog/ 规范,先确认 CLI 或 Templates 独立版本流,再只创建对应文件:
web/public/versions/cli/X.Y.Z.jsonweb/public/versions/templates/X.Y.Z.json
文件名必须匹配 versions 最后一项,group type、label、item 顺序和受限 Markdown 均须通过目录校验。不得编辑旧静态 Changelog HTML、手工 latest/Update Tip 或 web/dist/。
创建后执行:
pnpm --dir web exec vitest run tests/version-catalog.test.ts tests/changelog-data.test.ts
pnpm --dir web build
# 将 STREAM 设为 cli 或 templates,并使用实际版本号
STREAM=cli
VERSION=X.Y.Z
CHANGELOG_JSON="web/public/versions/${STREAM}/${VERSION}.json"
test -f "$CHANGELOG_JSON"
git add "$CHANGELOG_JSON"
git diff --cached --name-only
web build 内置 public→dist 文件集合与内容校验;只暂存源码 JSON,不暂存 web/dist/。
4. AGENTS.md 更新
若流程变更影响执行契约(新命令、新 skill、资产路径变化),同步更新 AGENTS.md。
检查清单
- --help 输出与 README、docs 中的说明一致
- 相关模块职责已在 docs/architecture.md 更新
- changelog 已更新(如有版本发布)
- 新版本 JSON 已通过 catalog/data 测试和 web build 一致性校验
- 暂存区仅包含实际版本流的
web/public/versions/{cli,templates}/*.json,不含旧静态 Changelog HTML 或web/dist/ - AGENTS.md 文档入口有效,docs 与 rules 按职责分离
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |