维护一个 CLI 开源项目最难的部分通常不是写代码，而是治理。一个能跑通核心流程的项目和一个能长期存活的项目之间的差距，几乎全部由治理决定。
本文整理一份最小治理模板清单：哪些文件是必需的，哪些是可选的，每个文件的最低门槛是什么。
治理的三层结构
L1：基础治理（必须有）
不写这些就别想上线：
- README.md：项目是什么、怎么用、谁在维护。少于 200 字的项目几乎没有贡献者。
- LICENSE：没有 license = 默认保留所有权利，其他人不能用你的代码。
- CHANGELOG.md：版本变更记录，让用户知道每个版本有什么变化。
- CONTRIBUTING.md：如何参与贡献。少有人会读，但读了的人节省 80% 的提问。
- CODE_OF_CONDUCT.md：社区行为准则，不是为了“看起来专业”，是为了冲突时有依据。
- SECURITY.md：安全漏洞披露流程。必须明确“不要公开 issue，请走邮箱”。
- .gitignore：防止误提交。
最低门槛：每个文件 ≤ 100 行，README ≤ 300 行。
L2：自动化与流程（应该有）
让人做的事减少到最少：
- CI/CD workflow：自动化测试、lint、build。没有 CI 的项目等于邀请 PR 破坏主分支。
- Issue 模板：把 “我的代码不工作” 变成结构化报告。
- PR 模板：标准化 PR 描述。
- Dependabot / Renovate：自动依赖更新。
- CODEOWNERS：明确“谁应该 review 这部分代码”。
- ADR（架构决策记录）：记录关键设计决策。
最低门槛：CI 跑通一次，模板写好即可使用，后续迭代。
L3：可持续性与社区（应该做）
让项目能长期存活：
- 公开 Roadmap：未来方向透明。
- 迁移指南：版本升级的破坏性变更说明。
- 公开指标：测试覆盖率、release frequency。
- 真实案例：谁在用、怎么用。
- 贡献者认可：CONTRIBUTORS、All Contributors。
- Funding 配置：FUNDING.yml。
- 故障排查手册：常见错误的解决方案。
最低门槛：Roadmap 是单页 markdown，其他可以随项目成长。
写 Issue 模板的技巧
很多人写 Issue 模板时陷入两个极端：
- 太短：“描述你的问题” → 用户写 5 个字 → 维护者花 1 小时追问
- 太长：20 个问题 → 用户中途放弃 → 维护者还是花 1 小时追问
好的 Issue 模板：
- 最多 5 个必填字段
- 每个字段都有格式提示（“环境：macOS 14 / Node.js 20”）
- 关键字段用 checkbox（“我已搜索现有 issues”）
- 不要问开放式问题（“你想怎么做？” → 用户不知道）
CI/CD 的最小配置
一个最小的 GitHub Actions workflow 只需要 30 行：
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '20' }
- run: npm ci
- run: npm test加上 lint、format check、build，就是完整的 CI。
ADR 是什么
ADR（Architecture Decision Record）是记录“为什么这样设计”的文档。一个 ADR 通常包含：
- Context：面临什么问题
- Decision：做了什么决定
- Consequences：这个决定的后果
不是所有决定都需要 ADR。只有：
- 非显而易见的选择（“为什么用 SQLite 而不是 Postgres”）
- 影响深远的选择（“为什么不用 WebAssembly”）
- 会被反复质疑的选择（“为什么不用 TypeScript”）
才需要 ADR。ADR 目录是设计决策的历史记录，让后续维护者不必重新决策。
什么时候不需要这些模板
- 项目只有一个人在用 → 不需要 ISSUE_TEMPLATE
- 项目处于 alpha 阶段 → 不需要 migration guide
- 项目没有任何外部贡献者 → 不需要 CONTRIBUTING.md
治理的强度应该匹配项目的成熟度和社区规模。盲目堆砌“治理资产”反而会让维护者疲惫。
本笔记的状态
这是一个 growing 状态的笔记。具体的模板文件已经放在 docs/templates/，可以根据需要复制到其他项目。随着在更多项目中使用这些模板，会持续补充实际遇到的问题和解决方案。
评论