Project Governance
> 给 AI 长期项目建立一套「项目记忆 + 文件索引 + 工作规则 + 版本记录」的管理系统，让 AI 换会话、换模型后仍能正确接着项目做，而不是重新猜项目。
目录
- 30 秒概览
- 何时使用 / 何时不用
- 记忆与治理的边界
- 使用步骤
- 输入 / 输出
- 失败处理
- 产出物
- 包结构
- 跨平台兼容
- 限制
30 秒概览
这个 Skill 给项目增加 8 个东西：
- 项目规则 —— AI 应该怎么做
- 文件地图 —— 文件在哪里
- 项目状态 —— 现在做到哪里
- 错误记录 —— 以前踩过什么坑
- 版本索引 —— 哪个版本才是真的
- 黑白名单 —— 什么能用、什么不能用
- 会话交接 —— 上一个 AI 做到哪里
- 变更记录 —— 为什么这么改
核心目标：让 AI 换会话、换模型、甚至换 Agent 后，仍然能正确接着项目做，而不是重新猜项目。
何时使用 / 何时不用
何时使用
- 用户抱怨项目太乱、文件散落、AI 总是乱放文件（"你怎么又乱放文件"）。
- 用户期望 AI 自己找文件，而不是问路径（"你自己找"）。
- AI 反复犯同样的错误，或总是用错版本。
- 用户说"你不是应该记得吗？""上次不是已经验证过了吗？""哪个才是最终版？""别重新做，之前已经跑通了"——这些是记忆与治理边界场景，仅靠记忆不可靠。
- 开始一个新的 AI 辅助项目，希望从第一天起就让 Agent 遵循稳定协议。
- 把一个 AI Agent 接入一个没有规则、错误日志、参数注册表的既有项目。
- 项目已经变乱：文件散落、参数改了没记录、过去的错误反复出现。
- 想强制落地一些持久规则，例如"先查索引再找文件""先计划后执行""文件存在 ≠ 文件有效""参数选择以注册表为准"。
何时不用
- 一次性问答或小改动，不需要项目级约定。
- 项目已有成熟的治理体系，只需要微调某条规则——直接改现有治理文件即可。
记忆与治理的边界
平台记忆（如 Trae 的用户画像 / 项目记忆）是上下文来源，不是权威事实库。治理文件才是项目执行规范。两者互补：
| 层 | 回答什么 |
|---|---|
| 平台记忆 | "以前发生过什么 / 这个用户通常怎么工作" |
| 治理文件 | "这个项目现在必须怎么工作、文件在哪里、哪个版本是权威" |
冲突时的权威优先级：
- 当前项目文件 / 冻结版本
- 项目治理文件（
AGENTS.md、index.md、VERSIONS.md、注册表） - 项目记忆
- 用户长期记忆
- AI 推测
当记忆与治理文件冲突时，治理文件优先。从记忆中学到的持久约定，必须经人工确认后沉淀进治理文件——记忆本身永远不会成为项目的权威。
使用步骤
第 1 步 —— 初始化
python scripts/governance.py init --project-dir /path/to/project --project-name "My Project"
从 templates/ 生成 11 个治理文件（除非传 --force，否则不会覆盖已有文件）。
第 2 步 —— 定制
编辑生成的 AGENTS.md：目录权限分区、自主权等级、产物存放规则，以及"项目定制"下的项目专属规则。通用核心治理规则保持原样。
第 3 步 —— 日常维护（每个会话）
- 会话开始：读
index.md→session_handoff.md→LESSONS.md；生成参数前，读blacklist.json/whitelist.json。 - 工作中：通过索引找文件（禁止盲目搜索）；优先继承
score > 0.85的 whitelist 条目；绝不使用permanent_ban: true的参数；新错误记入LESSONS.md。 - 会话结束：更新
session_handoff.md、index.md（文件变动）、CHANGELOG.md（决策）。
第 4 步 —— 校验、索引、检查
python scripts/governance.py validate --project-dir /path/to/project # 注册表是否符合 schema
python scripts/governance.py index --project-dir /path/to/project # 重建 index.md 目录地图（链接 + 备注）
python scripts/governance.py check --project-dir /path/to/project # 健康门禁：文件 + 注册表 + 索引新鲜度
输入 / 输出
- 输入：一个项目目录（有无治理文件皆可）、一个项目名称、用户的治理痛点（文件乱、版本错、反复犯错、"你自己找"）。
- 输出：一个治理工作区（
AGENTS.md、index.md、VERSIONS.md、LESSONS.md、session_handoff.md、CHANGELOG.md、whitelist.json/blacklist.json），以及一个通过校验、索引最新的目录地图。
失败处理
init失败（路径无效、权限不足）：报告失败的具体命令与原因；不要部分初始化或猜测。validate报 schema 错误：修复注册表条目；绝不绕过校验。check失败（缺文件 / 索引过期）：先运行index，再重跑check；仍失败则报告给人类。- 绝不伪造"通过"结果——如实报告哪些已验证、哪些没有。
产出物
| 文件 | 用途 |
|---|---|
AGENTS.md |
项目协议：核心治理规则、权威等级、首次运行协议、权限分区、信任边界 |
index.md + index_notes.json |
权威目录地图，带可点击链接与简短备注 |
VERSIONS.md |
稳定版本索引，含人工判断 |
LESSONS.md |
AI 错误与纠正日志 |
session_handoff.md |
会话结束交接 |
CHANGELOG.md |
决策与版本历史 |
whitelist.json / blacklist.json |
已验证 / 已失败参数注册表 |
ARCHITECTURE.md / PROJECT.md |
架构与项目卡片 |
包结构
README.md—— 完整包概览：核心 / CLI / Skill 适配结构、子命令、限制、FAQtemplates/—— 治理文件模板scripts/governance.py—— init / validate / index / check CLItests/test_governance.py—— 76 个边界测试用例（stdlib-only）
跨平台兼容
本 Skill 遵循开放 Agent Skills 规范，一套 SKILL.md 可同时用于：
- TraeWork / TraeCode（自动识别）
- Claude Code（ClawHub 市场）
- OpenClaw 兼容的任意平台
- 其他支持
AGENTS.md约定的 Agent
治理文件与 CLI 保持 Agent 中立：AGENTS.md 是业界通用约定，governance.py 仅依赖 Python 标准库，无网络、无第三方依赖。
限制
- 自动 Skill 发现 / 加载机制因平台而异：本包在 Trae 上测试最充分，其他平台可能需要手动接入
SKILL.md或AGENTS.md。 - 治理文件是"规范"，不是"自动执行器"：Agent 是否遵守，取决于平台对
AGENTS.md的支持程度。 - 复杂项目（多团队、多仓库）可能需要自行扩展模板与规则。
