Harness 与记忆策略：配置心智与方案对照

先认清：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 才有机会真的变乖。

三层：执行 / 上下文 / 治理

审查 Agent 只给只读工具；写码和测试 Agent 的权限要分开。两周搓浏览器那种活，靠的是：执行层给工具、上下文层用文档交接子任务、治理层拆写测角色。

Memory：半规则式是当下甜点

CC 侧两个机制值得记：

• Stop Hook：干完一轮，影子 Agent 决定写进哪些 Markdown
• Auto-Dream：定期深整理，合并重复、纠错，类似「做梦整理记忆」

Skill 的经验提取和 Memory 更新哲学很近，别死磕名词边界，都算上下文工程。

上下文压缩不是「能删就删」

源码视角常见三招：

1. 踢掉垃圾工具输出
2. 窗口只用到约 80%，留 20% 余量
3. 进展与目标写进文档，交给下一任 Agent

哪些留、哪些丢、下一棒要读什么，才是难点。好的管理常常是「少做多余管理」：别随意裁历史以至于弄坏 prompt caching。

Native vs Prompt Flow

判断 Harness 好不好，看两件事：和当前自回归推理是否自洽；会不会挡住模型以后变强。每一步手把手指定「下一步干什么」，短期可控，长期往往是累赘。

相关阅读

• 全栈别让 AI 凭空造：先拴住，再并行
• Spec 定边界，PLAN 定路线，别混成一锅

素材来源：CSDN 原文

先把前后端放进同一工作区

仓拆开开时，生成后端看不到前端调用，生成前端猜不到返回结构。同一 Cursor Workspace 有三件事值钱：

1. Codebase Indexing 覆盖两侧，语义检索能串整条链路
2. 字段名、命名风格自然对齐
3. 前后端 SDD 文档放一起，接口契约好对表

索引没跑完就别急着让它写大块代码。

SDD：两份文档，契约对齐

全栈不是一份 SDD 打天下。前端一份、后端一份；前端调用 vs 后端定义、VO 字段 vs JSON 字段必须一一对应。

常见产出：

生成 SDD 前，把设计歧义写成清单逼它先答：主键传什么、优先级谁自增、批量排序接口怎么设计、嵌套对象拆表还是 JSON、isNextDay 怎么映射。前端给足 UI 细节，后端先把模糊点钉死。

OpenSpec 类流程再长，日常可压成三步：propose → apply → archive。

多 Agent：文档齐了再并行

前后端 SDD 落地后，两侧实现天然可并行：

• Cursor：两个 Tab，前/后端各一个 Agent
• Claude Code：Subagent 分读各侧 tasks.md；Mock 可用更轻模型

Subagent 配置里把 tools / model / skills / permissionMode 绑死角色，别让审查员拿删除权限。

联调别一上来就端到端

三阶段更省命：

1. 前端 + Mock：字段类型对齐后端 SDD，覆盖空列表/极值
2. 后端独立：mvn clean compile（或等价）过编译再部署
3. 再连测试环境做端到端

Mock 要抄真实返回模板，别随手编字段。

SDD 不是测试终点

AI 会从参照实现「偷」隐性行为：关弹窗清表单、永久有效清日期、优先级自增……文档没写，代码里已经有。测试侧要把 SDD 当起点，专门问一句：参照功能有哪些隐性行为，新功能要不要？

相关阅读

• Spec 定边界，PLAN 定路线，别混成一锅
• 「模型以外都是 Harness」：拆开才好装

素材来源：CSDN 原文

Spec 六块别漏

原文给的模板够用：

1. 需求背景（为什么要做）
2. 核心能力（必须实现）
3. 输入输出约束
4. 业务规则与边界
5. 异常与报错
6. 可量化验收标准

没有第 6 条，Agent 就会「感觉写完了」。PLAN 则要对齐 Spec：总目标、原子任务、依赖、代理指派、分步验证点。复杂任务先 PLAN 再动手，比直接开写省返工。

协作怎么加码

• SubAgent：.cursor/agents/ 或工具内置子代理；描述里写 Use proactively 可主动召；适合审查/测试/调研这类忌「自己审自己」的活
• agentTeams：固定架构师 / 前后端 / 测试 / 安全一类角色，适合更大工程
• Claude Code 气质：渐进式披露，入口 + 搜索工具，别一次塞满仓库；Codex 气质更偏插件补全与全量上下文（原文对比，作选型参考）

日常避坑

相关阅读

• 全栈别让 AI 凭空造：先拴住，再并行
• 「模型以外都是 Harness」：拆开才好装

素材来源：CSDN 原文

选型先盯四根轴

四根轴拉满再谈「要不要上向量库 / 图谱」。好策略会给 Skill 留接口——检索、压缩、分层写入都能做成可调用能力包；烂选型则是把整段历史硬塞进 prompt，Skill 也救不回来。

八招对照

读表时别只盯「优势」列——劣势列往往才是账单和翻车点。

怎么叠，别怎么吹

可组合：窗口管当下，摘要管中程，向量管「以前说过啥」，图谱只留给真有关系推理的域。

无银弹：宣传里的「无限记忆」多半是某一层换了一种存法，不是免费无限上下文。

上线前先估峰值 token；上线后盯误召回 / 误摘要。记忆策略决定上下文从哪来；Skill 决定拿到上下文后怎么做事——前者选型错了，后者再漂亮也是在噪声里干活。

和五种 RAG 架构怎么选是邻居题：那边问「检索会在哪失败」，这边问「历史塞进上下文要付什么账」。两张表可以并排看，别当成同一张考卷。

先说结论：属实，而且是设计如此

Kiro（IDE / CLI）接 Claude 时，会注入自己的 System Prompt + Agent Harness，不会让 Claude 以「原生 Claude Code / 官方默认」状态跑。

官方自己就把这层叫 agent harness：管 agent loop、工具执行、子代理、会话、配置加载、和模型通信。模型只是引擎；方向盘在 Kiro 手里。

体感上：按 Spec 落地、生产级流程更稳；自由发挥、深度乱聊、高创造性 coding，很多人会觉得「没有原生 Claude 那么猛」。

证据链：不是道听途说

官方承认 harness 才是产品本体

One agent, every surface：how we built the Kiro agent harness 里，AWS 工程师把 harness 定义写清楚了：IDE / CLI / Web 曾各自为政，后来合成统一 harness + ACP。Spec、权限、hooks、compaction，全是这层的事。

官网首页也把卖点钉在 Spec-driven、property-based tests、parallel agents，而不是「最原汁原味的 Claude」。

这层套子里到底塞了什么

说人话，进 Kiro 的 Claude 要先穿这身制服：

算不算「篡改 / 削弱」？

「削弱」这个词偏情绪。更准的说法是：能力被重新分配了。稳、可协作、可审计的那一侧变强；松、野、贴模型原生上限的那一侧变弱。

和 Claude Code 比，差在哪

Kiro 里是「被驯化过的 Claude」；Claude Code 更接近「原版 Claude + 轻 harness」。

两边没有绝对对错。你要模型上限，去 Claude Code / 原生接口；你要 Spec 闸门和团队可复现流程，Kiro 这套「篡改」反而是卖点。

什么时候你会觉得「不得劲」

• 想让它像原生 Claude 一样天马行空改架构，它却先拉你写 requirements
• 自定义 agent 写了「先展示再改」，它仍 default_to_action
• steering 写了技术栈约束，子代理执行任务时装作没看见
• 选了新款 Claude，自报 cutoff / 行为却像旧模板（社区 issue 有过，不一定当前必现，但说明「UI 选型 ≠ 你以为的裸模型」）

什么时候它反而对劲：

• 功能边界清楚，愿意走 Requirements → Design → Tasks
• 团队要把规范沉到 steering / hooks，而不是每人一套口头约定
• 你要的是可回看的 Spec 产物，不是一次性聊天记录

认清撞上哪一层就行

别把「不得劲」当成 Kiro 骗子或 Claude 变弱。先认清你买的是哪一层：

1. 要模型原生手感 → Claude Code / API，少套 Spec 宗教
2. 要可交付、可评审的大功能 → Kiro Spec，别跟 harness 对着干
3. 两边都用也行：探索用轻 harness，落地再搬进 Spec

认清撞上的是 harness，不是「今天 Claude 抽风」，焦虑会少一半。

参考

• 官方：kiro.dev · harness 博文 · Specs 文档
• 泄露归档：EliFuzz/awesome-system-prompts · Kiro
• 源码分析：ghuntley/amazon-kiro.kiro-agent-source-code-analysis
• Issues：#7792 · #1404 · #6425 · #5754