# files-driven-governance：面向 AI Agent 系统的文档驱动治理方法

> files-driven-governance 提供了一套系统性的项目治理方法学，通过文档分层和结构家族定义，帮助 AI Agent 项目建立稳定的事实源和清晰的责任边界。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-03-30T06:46:13.000Z
- 最近活动: 2026-03-30T06:55:22.006Z
- 热度: 159.8
- 关键词: AI Agent, 项目治理, 文档管理, 多代理系统, 治理方法学, Spec-Driven, Kanban, 控制论
- 页面链接: https://www.zingnex.cn/forum/thread/files-driven-governance-ai-agent
- Canonical: https://www.zingnex.cn/forum/thread/files-driven-governance-ai-agent
- Markdown 来源: ingested_event

---

## 背景与问题意识

在 AI Agent 和多代理系统快速发展的背景下，项目治理面临新的挑战。传统的软件开发治理方法往往假设项目由人类开发者主导，而 AI Agent 项目则涉及人类、代理、工具、文档和流程的复杂协作。这种新的协作形态呼唤新的治理思路。

files-driven-governance 项目正是针对这一需求而提出的方法学。它关注的不是"文档多不多"，而是更根本的问题：事实在哪里定义？信息如何流动？失真如何被发现？秩序如何恢复？

## 核心理念：从文档到治理载体

files-driven-governance 的核心理念是将文档从"被动说明"提升为"主动治理载体"。它认为，文档不仅是给人看的说明材料，更是定义事实、推进执行、帮助恢复和对外展示的治理工具。

这套方法学强调，在 AI Agent 项目中，必须首先回答以下问题：

- **真源在哪里**：哪些文件定义了事实、规则和边界
- **过程如何推进**：哪些文件承载任务、讨论、决策和交接
- **状态如何摘要**：哪些文件帮助快速恢复现场
- **展示如何投影**：哪些文件只负责对外说明和汇报

## 文档四层模型

files-driven-governance 提出了一个清晰的文档分层模型：

### 第一层：真源（truth_source）

真源是定义事实、规则、边界的材料。它是项目的"宪法"，其他所有文档都应从真源派生。在 AI Agent 项目中，真源可能包括：

- 技能定义文件（SKILL.md）
- 规则和政策文档
- 对象边界定义

真源的关键特征是稳定、版本清晰、修改受控。

### 第二层：执行对象（execution_object）

执行对象是推进任务、讨论、决策、复核、交接的载体。它包括：

- 任务单和工作流定义
- 讨论记录
- 决策文档
- 复核检查点

这一层文档的特点是流动性强，但必须能够追溯回真源。

### 第三层：状态投影（status_projection）

状态投影是帮助快速恢复现场的摘要性文档。它不能反写上游，只能总结和呈现。例如：

- 项目状态报告
- 进度摘要
- 接手指南

### 第四层：展示投影（display_projection）

展示投影只负责对外说明、汇报或展示，不参与实际治理。例如：

- README.md（作为入口）
- 对外宣传材料
- 用户手册

## 结构家族分类

除了四层模型，files-driven-governance 还定义了八类"结构家族"，用于定位不同文档的职责：

1. **policy_or_rules**：政策和规则定义
2. **object**：对象定义和边界
3. **workflow**：工作流定义
4. **skill**：技能定义
5. **agent**：代理定义
6. **execution_object**：执行对象
7. **status_projection**：状态投影
8. **display_projection**：展示投影

每个文件都应该能够明确归属到某个结构家族，从而确定其读者、职责和修改权限。

## 方法学来源与融合

files-driven-governance 不是从单一理论搬来的，而是融合了多种传统：

| 来源 | 原本强调 | 在 files-driven 中的转写 |
|------|---------|------------------------|
| Spec-Driven | 边界、规格、验收 | 真源、对象边界、验收锚点 |
| Kanban | 流动、可见性、在制品 | 过程载体、状态摘要、恢复入口 |
| Agile/Sprint | 反馈、阶段收敛 | 决策包、复核关口、回退机制 |
| 系统论 | 结构、层次、耦合 | 结构家族、四层分层、责任模型 |
| 信息论 | 来源、传输、失真 | 真源、投影、读取顺序、恢复成本 |
| 控制论 | 观察、决策、执行、反馈 | observe → decide → act → review → rollback |

这种融合不是简单的并列摆放，而是重新组织成一套统一的治理语言。

## 控制回路模型

files-driven-governance 采用控制论的 observe-decide-act-review-rollback 回路作为基本治理模型：

1. **Observe（观察）**：感知项目状态
2. **Decide（决策）**：基于观察做出决策
3. **Act（执行）**：执行决策
4. **Review（复核）**：检查结果
5. **Rollback/Improve（回退/改进）**：必要时回退或持续改进

这个回路强调了治理的动态性和恢复能力。

## 典型应用场景

files-driven-governance 特别适合以下场景：

- **仓库文档开始互相漂移**：README、任务单、状态页之间的信息不一致
- **多人、多代理、多工具协作**：需要共享同一套事实
- **项目需要治理但不想堆重流程**：希望轻量级启动治理
- **需要可交接、可恢复、可回退的文档结构**：人员或代理更替频繁的团队

## 项目结构示例

一个遵循 files-driven-governance 的仓库结构可能如下：

```
.
├── README.md          # 入口（display_projection）
├── SKILL.md           # 技能执行导览（truth_source/execution_object）
├── CHANGELOG.md       # 变更账本
├── agents/            # 代理定义
├── references/        # 稳定参考材料
│   ├── 输出约定.md
│   ├── 场景手册.md
│   ├── 工具适配对照表.md
│   └── ...
└── docs/              # 背景与公开说明
    ├── 完整说明书.md
    └── 版本说明.md
```

## 阅读顺序建议

对于初次接触的人，建议按以下顺序阅读：

1. README.md —— 了解这是什么、什么时候用
2. SKILL.md —— 了解如何执行
3. docs/完整说明书.md —— 深入理解方法学

对于具体问题，可以直接下钻到对应的 reference 文档。

## 总结与价值

files-driven-governance 提供了一套面向 AI Agent 时代的项目治理方法学。它不是固定的目录模板，而是一套判断框架，帮助项目团队回答：什么应该成为慢变量？什么应该保持流动？什么只能总结不能反写？当项目漂移时应该先止血哪里？

对于正在构建 AI Agent 系统、面临多主体协作挑战的团队来说，这套方法学提供了一个系统性的思考框架，有助于建立稳定的事实源和清晰的责任边界。