Governance模块

创建项目治理活文档的结构设计与实现方法

#tech / dev #status / growing #type / howto

[!info] related notes

BodySense 项目 MOC

Development Environment MOC

Go 高级运行时与抽象 MOC

Go 并发 MOC

Go 语言基础 MOC

Governance 模块

目标

为项目创建一个「活文档」形式的治理模块，记录项目的规则、流程、角色和审计信息，使项目管理透明化、可追溯、可持续演进。

前置条件

有一个需要规范化管理的项目（软件项目、团队协作、开源项目等）
选择文档承载平台（Git 仓库中的 Markdown、Notion、Confluence 等）
团队成员对治理文档有基本的阅读和贡献意愿

治理模块内容

1. 规则（Rules）

定义项目的硬性规则和约束条件：

## 编码规范
- 使用 ESLint + Prettier 统一代码风格
- Commit message 遵循 Conventional Commits

## 安全规则
- 不在代码中硬编码密钥
- 所有 API 端点需要认证

## 行为准则
- Code of Conduct（可引用 Contributor Covenant）

2. 流程（Processes）

记录关键流程的步骤和负责人：

## 发布流程
1. 创建 release 分支
2. 运行全量测试
3. 更新 CHANGELOG
4. 创建 Git Tag
5. 部署到生产环境
6. 通知相关方

## 问题处理流程
1. Issue 创建 → 自动打标签
2. Triage（分类、优先级）
3. 指派负责人
4. 处理 → PR → Review → 合并

3. 角色（Roles）

定义项目中的角色和权限：

角色	职责	权限
Owner	项目方向决策	Admin
Maintainer	代码审查、发布管理	Write
Contributor	提交 PR、修复 Bug	Read + Fork
User	使用、反馈问题	Issue

4. 审计（Audit）

记录关键决策和变更历史：

## 决策日志 (ADR)

### ADR-001: 选择 PostgreSQL 作为主数据库
- 日期: 2026-01-15
- 状态: 已接受
- 背景: 需要支持 JSONB 和全文搜索
- 决策: 使用 PostgreSQL 16
- 后果: 团队需要学习 PG 运维

### ADR-002: 引入 CI/CD 流水线
- 日期: 2026-02-01
- 状态: 已接受
- ...

实现方式

方案一：Git 仓库中的 Markdown（推荐）

project-root/
├── GOVERNANCE.md          # 总览
├── docs/
│   ├── rules/             # 规则文档
│   ├── processes/         # 流程文档
│   ├── roles.md           # 角色定义
│   ├── adr/               # 架构决策记录
│   │   ├── 001-xxx.md
│   │   └── 002-xxx.md
│   └── changelog.md

优点：版本控制、与代码同仓库、PR 审查机制。

方案二：使用 ADR 工具

# 使用 adr-tools 管理架构决策记录
brew install adr-tools
adr init docs/adr
adr new "选择 PostgreSQL 作为主数据库"

方案三：Obsidian 活文档

使用 Obsidian 知识库管理治理文档，利用双链和 MOC（Map of Content）组织结构。

活文档的「活」

文档不是一次写完就完事，而是持续演进：

定期审查：每季度回顾规则和流程是否仍然适用
变更记录：所有修改都有 PR 或 commit 记录
反馈机制：团队成员可以提出修改建议
自动化：CI 中检查文档是否与代码保持一致（如 API 文档）

验证

新成员入职时能通过治理文档了解项目规则
关键流程（发布、问题处理）有明确的步骤文档
角色和权限清晰定义，无歧义
决策有记录可追溯（ADR）
文档有定期更新机制，不会过时

常见问题

Q: 文档太多没人看怎么办？ A: 保持精简，只记录必要的规则和流程。使用模板减少写作负担。将文档链接放在 README 和 onboarding 流程中。

Q: 如何让团队遵守规则？ A: 将规则自动化——用 Linter 检查代码风格、用 CI 检查 commit message、用 branch protection 强制 review。能自动化的规则不要靠文档。

Q: ADR 的格式有标准吗？ A: 有。参考 Michael Nygard 的 ADR 模板或使用 adr-tools 自动生成。