关于我用Agent治理Vibe项目的心智模型和workflow

先认清：IDE 建专属目录，不等于第二套技能源

CLI 基本是纯文件驱动，所以更愿意读共享的 AGENTS.md + .agents/skills/。

IDE 还要额外的东西：

• 更细的触发元数据（globs、alwaysApply、条件规则）
• hooks、settings、命令面板、本地覆盖
• 历史包袱（旧 .cursorrules、各家 CLAUDE.md / steering / specs）

所以 .claude、.cursor、.trae、.vscode 首先是运行时适配层。它们经常只是在指向或镜像共享内容，不该再复制一份 skill 正文。

你要盯的是：共享源有没有唯一真源；专属目录有没有偷偷长成第二份仓库。

正在收敛的三块开放标准

还没走到「全世界只认一个文件夹」，但主干已经清楚。

AGENTS.md：跨工具的项目说明书

AGENTS.md 是给人看的 README 之外、专给 coding agent 的说明：怎么构建、怎么测、哪些约定别踩。现在由 Linux Foundation 旗下的 Agentic AI Foundation 托管，Codex、Cursor、GitHub Copilot、Jules、Amp 等一长串工具都认。

Claude Code 不原生读它，读 CLAUDE.md。务实做法是：AGENTS.md 当 SSOT，CLAUDE.md 顶部 @AGENTS.md 或薄封装一层加载序。

Matt 自己也提醒过：别把 AGENTS.md 养成泥球。每条指令都占「instruction budget」，路径级细节又最容易过期。短、可执行、偏能力描述，细节丢给 skills 渐进加载。

三层心智模型（我每个项目都按这个长）

共享真相层：能力与跨工具规范只维护一份。
治理账本层：领域语言、决策、tracker 配置随项目生长。
工具适配层：只放该工具真正需要的 rules / settings / hooks；skills 用 junction 指回共享源。

展开成目录，大概是这样：

1
project/
2
├── AGENTS.md                 # 跨工具通用指令（优先维护）
3
├── CLAUDE.md                 # @AGENTS.md + Claude 专属加载序
4
├── CONTEXT.md                # 领域事实 / 术语（单上下文）
5
├── CONTEXT-MAP.md            # （可选）多上下文索引
6
├── LANGUAGES.md              # 共享用词（本仓加厚；见下）
7
│
8
├── docs/
9
│   ├── adr/                  # 难逆转决策（懒创建）
10
│   └── agents/               # 项目配置层
11
│       ├── issue-tracker.md
12
│       ├── domain.md
13
│       ├── triage-labels.md
14
│       └── workflow.md       # 你自己的任务流细节
15
│
16
├── .agents/
17
│   └── skills/               # 真正的 skill 源（只维护这里）
18
│
19
# --- 下面全部可选：你用到哪个工具再加哪个 ---
20
├── .claude/                  # Claude Code
21
├── .cursor/                  # Cursor（rules / skills→junction）
22
├── .trae/                    # Trae
23
├── .kiro/                    # Kiro（steering / specs）
24
├── .codex/ · .gemini/ · .junie/ · .windsurf/
25
├── .vscode/                  # 编辑器集成默认值
26
├── .github/                  # Copilot instructions / prompts
27
└── src/

别被列表吓到。根上先有 AGENTS.md + CLAUDE.md + CONTEXT.md + .agents/skills/，已经能跑；其余按痛点长，不按焦虑长。

Matt 的治理资产：嵌进日常，而不是换掉你的流程

mattpocock/skills 标语写得很直：Skills for Real Engineers，从他自己的 .agents 目录抽出来。调研日量级大约二十万星，release 已到 v1.2.x。主站目录在 AIHero Skills。

它不是「全流程接管框架」。哲学是：小、可组合、模型无关，人始终握着过程。针对的是对齐失败、术语漂移、代码质量、架构泥球，而不是再发明一套必须服从的瀑布。

一次性 /setup-matt-pocock-skills 在仓里落的，主要是这些：

技能文件本身尽量零硬编码：跨仓差异都读 docs/agents/*。这点很工程。

主流程我日常记成：

1
Align  → /grill-with-docs（有代码库）或 /grill-me
2
Spec   → /to-spec
3
Plan   → /to-tickets
4
Build  → /implement + 模型侧 tdd / code-review
5
Upkeep → /improve-codebase-architecture …
6
迷路时 → /ask-matt

技能拆解、grilling 引擎、v1.2 细节见旧帖；这里只强调一句：治理文件是活的。你不更新 CONTEXT.md，整套技能就退化为「会喊口号的斜杠命令」。

不同阶段，养哪一层

核心纪律只有两条：共享层永远是真相源；工具目录禁止再复制同一套 skill 正文。

Agent 怎么读，才能把 harness 用满

机制可以简化成：

1
会话启动
2
  → 读根 AGENTS.md / CLAUDE.md（嵌套时最近者优先）
3
  → IDE 再叠 alwaysApply rules
4
Skills 发现
5
  → 扫 .agents/skills + 工具专属 skills（先 metadata，后全文）
6
运行时
7
  → 你触发的 skill：显式改 CONTEXT / 写 ADR / 更新 docs/agents
8
  → 模型触发的 skill：tdd、code-review… 带着账本干活
9
工具面
10
  → MCP 接外部能力；Plugins 负责安装与更新通道

想放大效果，我实际就做这几件：

1. 全局 / 项目 skills 用 junction，避免三份漂移
2. AGENTS.md 写明：工程技能优先走 Matt 系，并维护 CONTEXT
3. Claude：CLAUDE.md 指向 AGENTS，不另起炉灶
4. 迷路先 /ask-matt，别靠背技能名
5. grilling 结束若没改 CONTEXT，算这次对齐失败

Harness 不是「装得越多越强」。是 Agent 每次醒来都能摸到同一份项目记忆。

和 Superpowers、ECC 怎么处

社区里比较清醒的用法是：按任务形状选，不要按星数选。不确定、要深对齐，先 Matt 的 grill；要防 agent 偷懒的长程交付，可叠 Superpowers 的纪律；要某一类垂直能力，再从 ECC 里偷单件。

我自己的默认：Matt 治理骨架 + 开放标准目录当底座；Superpowers / ECC 只吸收真痛点对应的招，绝不三个 meta-router 同时开。

本站是怎么长出来的（实证，不是示意图）

这套不是 PPT。博客仓现在就是按三层养的：

• 根上：AGENTS.md、CLAUDE.md、CONTEXT.md、LANGUAGES.md
• 账本：docs/adr/、docs/agents/（Matt 三件套之外，还加了 workflow / deliver / archive / voice）
• 共享技能：.agents/skills/
• Cursor 适配：.cursor/rules 只放站点专有规则；.cursor/skills 用 junction，正文不双开

内容流水线也挂在同一治理层上，而不是另起一套玄学：

1
甲 · Obsidian 笔记 → ob2blog → posts/<slug> → site-cascade
2
乙 · 会话/调研   → knowledge-extract → knowledge-output → site-cascade

再加一条多 agent 并行纪律：壁纸、音乐、配图、发文各管各的模块，看到别人的未提交改动别瞎慌。这是「项目记忆」的一部分，写进 AGENTS 比写进某次聊天有用得多。

近几天上游还在吵什么

扫 mattpocock/skills 近几日的 issue，味道很成熟库：不是「这套废了」，而是「再好用一点」。

例如可恢复的 grilling 状态、plugin 通道下 setup 漏写 triage-labels、并行分支 ADR 编号撞车、skills 目录拍平并靠拢 Agent Plugins 1.0。对使用者的启示很具体：setup 跑完检查 docs/agents/ 是否真写全；多分支时 ADR 编号别裸冲。

认清边界再开工

小改别强行 grill→tickets→implement 全套。
skill 正文只维护一份，专属目录用链接。
AGENTS.md 变厚时做减法，别当后悔药仓库。
IDE 专属文件夹会继续存在；你要统一的是真相源，不是强迫所有工具删目录。

如果你已经在用 Matt、又同时开着 Cursor / Claude / Codex：先把共享层收干净，再谈装更多技能。目录不乱，Agent 才有机会真的变乖。