briqt Knowledge Project
将知识工作组织为自描述项目——任何 Agent 打开即可理解和继续，无需外部记忆系统。
Philosophy
核心理念：项目本身携带完整上下文。不依赖特定平台、记忆服务或对话历史。
设计原则：
- 纯文件 + 约定：markdown + YAML frontmatter，零工具依赖，git 友好
- 自包含：每个文档独立可理解，项目整体打开即可继续
- 最小约束：只规定互操作必需的结构，其余由项目自行演化
- 写的人花 2 分钟，读的人省 20 分钟：信息密度优先，格式服务检索
- 单一权威源：规则只在一处定义，其他文件引用不复述
格式基础：Open Knowledge Format (OKF) v0.2 —— 知识用 markdown + YAML frontmatter 目录表示，人和 Agent 用同一份文件。
底线：项目目录是唯一的持久化载体。换 Agent、换平台、清空记忆、本 skill 未安装，打开项目目录即可继续。
Agent Directives
本 skill 被触发后，Agent 的首要职责是维护项目的自描述能力和自迭代能力。
触发行为
根据用户意图自动分流：
| 意图 | Agent 行为 |
|---|---|
| 创建新项目 | 执行 Initialize workflow |
| 恢复/继续项目 | 执行 Resume workflow |
| 整理/优化项目 | 执行 Health Check → 按诊断结果执行 Milestone Review 或 Distill |
| 回顾方法论 | 执行 Meta-Iteration 的信号检测 |
触发时，Agent 应主动对照 Health Check 清单扫描项目现状，发现可改进项时向用户提出。
维护自描述
项目的所有上下文落在项目文件中（CLAUDE.md/AGENTS.md、log.md、内容文件），不依赖外部记忆系统。不要将项目信息写入 Agent 自身的 memory——项目文件就是记忆。
产出物不得反向依赖本 skill，也不得引用本 skill：由本方法论创建或维护的项目，其自足性不得以"本 skill 在场"为前提，项目文件中不出现本 skill 的名字，也不留指向任何外部方法论的指针——无例外（2026-08-17 用户定，废除此前的三档自足制；理由见 Seed §关键约束）。
Agent 在工作过程中持续确保项目上下文自足——进展、决策、文件元数据随工作产生同步落地。最终检验：结束工作时，log.md 最后一条的"下一步"足以让任意 Agent 从零接手。
推动自迭代
Agent 在项目中工作时，持续感知结构摩擦并推动改进：
- 发现规则与实际操作不一致 → 提出 CLAUDE.md/AGENTS.md 修改建议
- 发现导航不够高效 → 提出结构调整
- 发现重复模式 → 提出新规则或模板
改进走 proposal 模式：诊断 → 提案 → 用户确认 → 执行 → 记录到 log。
Epistemics
知识工作的认知纪律。贯穿所有工作流，优先级高于具体流程步骤。
- 基于证据：判断、选择、结论须追溯到可观测的依据。没有证据时承认不确定，而非填充看似合理的假设。委派或其他 Agent 的产出同样是候选输入而非既定事实——引用它做不可逆动作（删除、归档、改权威源）前先复核源头。
- 在行动点决策：不提前锁定依赖未知信息的决定。确定方向，开始行动，让工作本身产生下一个决策点。
- 完整执行：不跳步骤，不用"以此类推"代替实际工作。产出是做出来的，不是规划出来的。
- 对齐优先于执行：目标有歧义、存在矛盾、或涉及方向性取舍时，先澄清再行动。推断可以替代追问，但推断必须显式呈现供纠正——不用默认值静默填充。
Project Structure
规模适配
不是所有工作都需要完整项目结构：
| 规模 | 结构 | 适用场景 |
|---|---|---|
| 单文件 | 一个带 frontmatter 的 .md 文件 | 研究笔记、单篇报告、小 topic |
| 最小项目 | CLAUDE.md/AGENTS.md + log.md + 内容文件 | 短期调研、原型验证、小型写作 |
| 标准项目 | 完整目录结构 | 多文档协作、长期项目、团队共享 |
| 规则密集项目 | 标准结构 + 规则分层加载 + 准入退出机制 | 规则本身多到成为需要治理的资产 |
当文件增长到需要拆分、或需要跨 session 维护上下文时，从当前规模升级到下一级。
最小项目（3 个文件）
project-root/
├── CLAUDE.md / AGENTS.md # 项目规范（两文件内容保持一致，见下方说明）
├── log.md # 工作日志（OKF 保留文件名）
└── <content>.md # 至少一个带 frontmatter 的内容文件
标准项目结构
project-root/
├── CLAUDE.md / AGENTS.md # 项目规范（两文件内容完全一致）
├── index.md # 全局导航（文件 >3 个时创建）
├── log.md # 工作日志
├── .scratch/ # 探索期临时文件（gitignore，蒸馏时处理）
├── <目录>/ # 按职能分组的内容
│ ├── index.md # 目录导航（>3 文件时创建）
│ └── <content>.md
└── 归档/ # 已废弃内容（可选）
CLAUDE.md/AGENTS.md
不同 Agent 平台读取不同的项目规范文件名，因此两个文件必须同时存在且内容完全一致。修改任一文件时同步更新另一个。
CLAUDE.md/AGENTS.md 是项目的单一权威规则源，其他文件的规则与之冲突时以此为准。
CLAUDE.md/AGENTS.md vs index.md
| 文件 | 职责 | 内容类型 |
|---|---|---|
| CLAUDE.md/AGENTS.md | 规则 + 高层路由 | 项目约定、按事项/职能的入口指引、Agent 行为规范 |
| index.md | 文件清单 + 导航 | 按目录结构列出具体文件及其 description |
CLAUDE.md/AGENTS.md 引用 index.md（"详见 index.md"），不复述其内容。两者共存时，CLAUDE.md/AGENTS.md 告诉你"去哪个方向"，index.md 告诉你"那个方向有什么"。
"文件 >3 个"只数内容文件（本节是该阈值的唯一定义处，其余各处只写阈值不复述）：harness 契约文件（CLAUDE.md/AGENTS.md/README.md）与 OKF 保留名（index.md/log.md）不计入——它们不是 index.md 要导航的对象，数进去会催生一份全是噪音的索引。
规则的分层加载
规则文件随项目增长而膨胀，膨胀到一定程度就不再被完整阅读。按"对多少类任务成立"分三层，按需加载：
| 层 | 放什么 | 何时被读 |
|---|---|---|
| 常驻层（CLAUDE.md/AGENTS.md） | 对每一类任务都成立的规则 + 任务路由表 | 每次 session |
任务层（如 rules/<任务>.md） |
只对某类任务成立的规则全文 | 按路由表，做该类任务时 |
理由层（如 rationale.md） |
判据的来历、实证、被否方案 | 只在改规则时 |
常驻层对下层只写指针不复述。任务路由表是"要做 X → 先读哪几个文件（按顺序）"的映射，是任务层唯一的入口。
配对约束——规则必须在执行路径上：判据是删掉它，有没有任何动作会做得不一样？ 会 ⇒ 它必须留在干这件事的 Agent 实际会读到的文件集合里。
- 把一条仍在生效的规则移进"只在改规则时读"的理由层，等于删除它——而且不报错。
- 定义了一个角色、流程或检查，却没有任何路由指向承载它的文件，那份文件是零人加载的。点名一个角色不等于接上它的执行体。
- 规则搬家后要问的不是"它还在不在"，而是"谁会读到它"。
分层与"单一权威源"配套使用：不复述是为了防漂移，但不复述 + 下沉到无人读的深处 = 静默失效。两者必须一起满足。
自包含的判据
"自包含"要能被检查，否则只是口号：
- 不引用项目外的机器路径——绝对路径、临时下载目录这类换台机器即失效，读的人也无从取得。
- 外部材料二选一：要么存进项目（凭据类进 gitignore 的目录），要么写清怎么获得（哪个系统、哪个页面、找谁要）。
- 一次性路径只用于"我这次从哪儿拿的"这类动作，不进沉淀文本。
- 生成物不得反向依赖、不得引用生成器：项目的自足性不以任何外部方法论在场为前提，项目文本零外部方法论引用（见 Seed §关键约束）。
项目与 OKF bundle 的边界
OKF 的合规单位是 bundle（一棵 concept 目录树），不是整个仓库：
- 纯知识项目：项目根即 bundle root，无须额外声明
- 混合仓库（代码与知识共存）：在 CLAUDE.md/AGENTS.md 声明哪个子目录是 bundle root（如
knowledge/、docs/）；边界外的代码、配置、包装文件不按 concept 要求，不为凑格式强行加 frontmatter - 未声明边界时，不把仓库里所有 .md 自动当作 OKF concept 检查
Frontmatter Schema
遵循 OKF v0.2 字段约定。
---
type: 架构设计 # 必填（OKF 唯一必填），概念类型，自由文本
description: 一句话摘要 # 推荐，Agent 判断相关性
tags: [tag1, tag2] # 推荐，跨目录检索
generated: # 推荐，取代 v0.1 的 timestamp
by: human:alice # actor：human:<id> 或 <产出者>/<版本>
at: 2026-08-13T10:00:00+08:00 # 最后实质修改（ISO 8601 datetime）
status: stable # 可选，draft | stable | deprecated（缺省 stable）
verified: # 可选，谁复核过
- { by: human:alice, at: 2026-08-13T18:00:00+08:00 }
relates: # 可选，强关联文档路径
- path/to/related.md
---
规则：
type是唯一必填字段，值为自由文本- 只写有值的字段，宁缺勿空
- 无 frontmatter 时 Agent 从标题和正文推断，不报错
- actor 约定：
human:<id>表示人，<产出者>/<版本>表示 Agent 或工具。与 log.md 的@操作人是同一套身份语义 generated取代timestamp：旧文档的timestamp仍可读（OKF 允许回退），新写文件与顺手更新时改用generated。迁移旧文档时 actor 无从确认就保留timestamp，不编造generated.by——读旧文档做宽容消费者，自己写入做严格生产者status: deprecated是"归档即关闭"的元数据表达（见 Context System）verified决定可信档：无该字段 = 未复核；仅非 human actor = 机器确认；含human:<id>= 人已复核。这与"门禁分层"是同一个区分——可机械校验的由机器确认，只能语义判断的须人复核index.md不带 frontmatter，唯一例外：项目根 index.md 可写okf_version: "0.2"- 其余可选族按需采用：
sources（来源清单，正文逐条归因用与sources[].id同名的脚注；v0.1 的正文# Citations迁入此字段，无法核实的条目标注待核验）、stale_after（绝对过期日期）。研究型项目值得用；不写不违规，写就只写已核实的值——来源、actor、时间、核验一律不伪造 - 正文中用标准 markdown 链接表达概念关联
与 OKF 的显式分歧
以下三处有意偏离 OKF，理由记在此处，不静默违反：
| 处 | OKF | 我们 | 理由 |
|---|---|---|---|
log.md 顺序与格式 |
日期分组、最新在前、条目为散文 | 最新在底部（append-only）、条目为四字段结构 | append-only 的 diff 只在末尾增长、冲突少；"下一步"恒定落在文件末尾，是 session 接力的取用点 |
CLAUDE.md/AGENTS.md/README.md 的 frontmatter |
非保留名 ⇒ 要求有 frontmatter | 不带 | 它们是 harness 契约文件（面向运行时的 Agent 与人），不是知识 concept |
| Attested Computation（OKF §10） | 可选族 | 不采用 | 面向可执行的数据口径，超出知识项目范围 |
log.md 的日期标题统一用 ###，不与 ## 混用——混用会让任何按标题定位条目的检查失效。
Context System
信息职责边界
项目中承载"接下来做什么"的信息分三层，职责正交：
| 载体 | 回答什么 | 维护频率 |
|---|---|---|
| 需求/规划文档 | Scope：做什么、完成标准、依赖 | 规划时写，大变更时改 |
| 任务清单（如有） | Assignment：谁在做、优先级、状态（派生，见下） | 状态变更时改 |
| log.md | Progress：做了什么、卡在哪、细节 | 每次有实质进展时追加 |
同一轮工作不跨层复述：职责正交只约束「各层答什么」，不阻止同一件事在三层各写一遍——而重复的动力是「想写全」，是尽责才会犯的错，不是偷懒。取材判据与 §规则的分层加载 同一把尺子：删掉这段，读者会不会做错事？ 答不出就删；重叠部分删到只剩一处，其余靠链接。过程叙事、证据链、数字比对属于工作记录，不进常驻文档。一个可检出的信号：把别处已有的通用判据在新文档里再复述一遍并注明「与既有判据同形」——那句注明本身就说明它该删。
完成状态是派生量：一个事项是否完成，可从进度源头推出（事项自身文档的「当前下一步」或 log 的「下一步」＝无/完结）。任务清单的「状态」是这个事实的派生视图（便于总览），不是独立权威——与 live 进度冲突时以进度记录为准。
推广：易变量不落静态文本。凡会漂的量——计数、进度、状态、日期水位——要么现算，要么只存一处。复制到第二处的那一刻就开始漂，而漂移不报错、测试也不会红。派生视图（台账状态列、索引里的进度数字）与源头冲突时一律以源头为准；最强形式是不存，需要时现推。
log.md（工作日志）
### YYYY-MM-DD 事项名称 @操作人
**进展**：本次完成了什么
**决策**：做了什么选择、为什么（无则省略）
**阻塞**：卡在什么上（无则省略）
**下一步**：接下来该做什么
规则：
- 一条 = 一次实质进展，没有实质内容不写
- 每条不超过 5 行
- 最新在底部（append-only，git diff 友好）
@操作人用 git 用户名，AI Agent 用@ai下一步是 session 接力的核心机制——写法标准：一个新 Agent 只读这一条就知道该做什么- 归档阈值 = 装得下 Resume 所需的最近窗口（约 2-3 天或 10-15 条），默认 200 行。条目密度高的项目按此上调并在 CLAUDE.md/AGENTS.md 写明覆盖值——阈值卡在绝对行数上会把接力需要的上下文一起归档掉
决策记录
内联到相关文档末尾的 ## 决策记录 章节。
### YYYY-MM-DD 结论短语
**背景**：面临什么选择
**结论**：选了什么
**理由**：为什么
**排除**：为什么不选其他方案
只记有多个可行方案的决策。排除理由必写。
归档即关闭
归档 = 该事项在本项目告一段落，状态一律视为已完成。条目里记录的缺口、未尽、未发版、待外部处理项均为历史态：不作为待办，不再主动注意、复述、扫描或提议处理（状态分析与 Health Check 亦不纳入）。唯一复活入口是用户主动提起。
对应的 frontmatter 表达是 status: deprecated（OKF §5.4：保留链接与历史，不再是当前）。
收口是原子操作：关闭一个事项必须在同一次操作内完成——① 源头的"下一步"置为完结；② log 追一条收口；③ 移出活跃视图。缺一不算收口，留下的就是"假活跃"。
Workflows
Initialize（创建新项目）
- 创建项目目录
- 写 CLAUDE.md/AGENTS.md：
- 项目目标、结构约定
- 内联种子规则（见 Seed 章节）——确保后续 Agent 在没有任何外部方法论在场时也能维护项目
- 种子包含自足声明（见下）
- 创建 log.md，第一条记录"项目创建 + 目标"
- 创建第一个内容文件（带 frontmatter）
产出：一个自包含项目，任何 Agent 打开 CLAUDE.md/AGENTS.md 即可开始工作——不需要知道这套方法论从哪来。
Seed（种子机制）
Initialize 时将核心行为规则内联进项目 CLAUDE.md/AGENTS.md，使项目在没有外部方法论在场时仍能自维护。
原理：本 skill = 完整方法论（基因库）；项目里的 Agent 行为规则 = 精简的表达型规则（表型）；Initialize = 提取关键规则内联进项目（繁殖）。
关键约束——生成物不得反向依赖、不得引用生成器：项目文件中不出现任何外部方法论的名字或指针——规则要么内联进项目，要么就不是这个项目的规则。两问都要过：
- 删掉项目里涉及外部方法论的那句话，项目是否仍然完整？ 不完整 ⇒ 那是依赖，必须内联；
- 仍完整但那句话还留着？ ⇒ 同样不合规——指针会随上游演化变成半真半假的话；升级入口本就不需要落在项目文本里（方法论随环境安装、按意图触发，维护它的人就是升级通道）。
为什么禁「活依赖」而不是只要求「声明依赖」（2026-08-17 用户定，取代此前的三档自足制 A/B/C）：内联种子 = vendoring——项目任何时刻内部自洽，与上游的分歧只在主动升级、对照 seed-version 复核 diff 时暴露，那是有人在场的受控动作；引用外部方法论 = 动态链接一个可变权威——上游一动，项目文本就半对齐半冲突，而暴露时机是随机的（往往是某次 Resume 撞上才发现）。落后要落后得自洽。曾允许的"声明式依赖"（旧档 C）在实践中恰好产出了它想避免的事故形态，故废除。
种子内容：自足声明、项目文件即记忆、log 追加规则、Resume 阅读协议、frontmatter 基本要求、双文件同步、感知偏差与对齐。
种子模板（模板版本：2026-08-17）：
## Agent 行为规则
<!-- seed-version: YYYY-MM-DD -->
**自足声明**：本项目的规则完整落在项目文件中，不依赖任何外部方法论在场——换 Agent、换平台、清空记忆，打开项目目录即可继续。
### 核心纪律
- **项目文件即记忆**：所有上下文落在项目文件中，不写入 Agent 外部 memory
- **有进展就写 log**：完成实质工作 → 追加 log.md 条目（进展/决策/下一步）
- **log 条目自足**：每条不超 5 行，"下一步"足以让任意 Agent 从零接手
- **新建文件写 frontmatter**：至少 `type` 字段
- **易变量不落静态文本**：计数、进度、状态要么现算、要么只存一处
- **CLAUDE.md 与 AGENTS.md 保持同步**：修改一方时更新另一方
### 恢复上下文（Resume）
新 session 阅读顺序：CLAUDE.md/AGENTS.md → 任务清单（如有）→ log.md 尾部 → 进入工作。
若 log 描述与当前文件实际状态冲突，以文件为准，更新过时描述。
### 感知偏差与对齐
- **目标有歧义时对齐优先于执行**：方向性取舍、矛盾、模糊 → 先澄清再动手
- **方向偏离暂停**：当前工作与项目声明目标不一致时暂停确认
- **规则漂移 → proposal**：实际操作与本文件规则不一致 → 提出修改建议（proposal → 确认 → 执行）
- 发现导航不够高效或出现重复模式 → 提出结构调整
- 改进记录到 log.md
### log.md 格式
### YYYY-MM-DD 事项名称 @操作人
**进展**：… **决策**：…（无则省略） **下一步**：…
种子块不含任何指向本 skill 的页脚或署名；项目也不另写任何"中性指针"——升级路径由环境承担（本 skill 按意图触发），不落项目文本。seed-version 是唯一的版本锚点。
演化一致性：
- 上方的种子模板版本日期是比对锚点。Health Check 比对项目
seed-version与该日期，早于它即判过时 - 只有种子模板内容变化才 bump 模板版本；本文档其他流程细节的变化不触发
- 更新走 proposal：展示变更 → 用户确认 → 替换种子块 → 记录到 log
Resume（恢复上下文）
新 session 阅读协议：
- CLAUDE.md/AGENTS.md → 理解项目结构和约定
- 任务路由表（如有）→ 按本次任务加载对应的任务层规则
- 任务清单（如有）→ 知道当前活跃任务
- log.md 尾部 5-10 条 → 知道最近进展和阻塞
- 进入具体工作
Health Check（项目健康检查）
打开已有项目或用户要求"整理/优化"时执行。对照以下清单诊断：
| 检查项 | 标准 | 不达标时 |
|---|---|---|
| CLAUDE.md/AGENTS.md 存在且有效 | 包含目标、结构约定、Agent 行为指引 | 建议补全 |
| 自足性 | 种子块存在（含自足声明与 seed-version）；项目文件零外部方法论引用（名字与指针都算） |
列出违规句，建议内联或删除 |
| log.md 存在 | 有至少一条记录 | 建议创建 |
| 内容文件有 frontmatter | 至少有 type 字段 |
列出缺失文件，建议补 |
| index.md 一致性 | 目录 >3 文件时存在、与实际文件一致、且不带 frontmatter（根 index 仅可带 okf_version） |
建议创建或更新 |
| 派生视图一致性 | 台账状态、索引里的进度数字等派生量未与源头冲突 | 提示更新或改为现算 |
| 规则在执行路径上 | 每份规则/角色文件都有路由指向；无零人加载的文件 | 列出孤儿文件，建议接上路由或退役 |
| 门禁有效性 | 每道机械检查都有配套的证伪用例 | 建议补证伪用例 |
| log.md 长度 | ≤ 项目声明的归档阈值（默认 200 行） | 建议归档旧条目 |
| .scratch/ 积压 | ≤10 文件 | 建议执行 Distill |
| CLAUDE.md 与 AGENTS.md 同步 | 内容一致 | 建议同步 |
| 种子版本 | seed-version 不早于本 skill 的种子模板版本 |
提示更新种子 |
流程：扫描项目 → 生成诊断报告 → 向用户展示问题和建议 → 用户确认后执行修复 → 记录到 log。
已归档内容不纳入扫描（见 Context System §归档即关闭）——把历史态重新报成待办，是健康检查最常见的噪音来源。
Daily Operations（日常维护）
| 场景 | 动作 |
|---|---|
| 完成有实质进展的工作 | 追加 log 条目 |
| 修改了文档 | 更新 generated.at |
| 做了多选一决策 | 追加决策记录 |
| 新建文件 | 写 frontmatter（至少 type） |
| 发现 frontmatter 过时 | 顺手更新 |
| 目录 >3 文件且无 index.md | 创建 index.md |
| 发现 index.md 与目录实际不一致 | 顺手更新（index.md 允许滞后） |
| 发现派生视图与源头不一致 | 顺手更新，或改为现算 |
| 关闭一个事项 | 执行收口原子三连（置完结 + 记 log + 出活跃视图） |
| 新增一条常驻规则 | 先过三行自证与零和检查（见 Self-Iteration） |
Milestone Review（里程碑回顾）
触发：阶段完成、方向变更、或 log.md 积累到一定量。
- 回顾 log 近期条目，识别模式
- 更新 CLAUDE.md/AGENTS.md 中的规则（如果有过时的）
- 生成规则退出候选清单，交用户打勾（见 Self-Iteration §规则的准入与退出）
- 归档已废弃内容
- 重组 index.md
- 在 log 中记录"回顾"条目
Distill（探索→沉淀）
知识工作先发散（试错、临时文件、死胡同）后收敛（提炼、丢弃噪音）。只留最终结果 → 失去"怎么做到的"；什么都留 → 噪音淹没信号。
与 Milestone Review 的区分：有 .scratch/ 或临时产物要处理 → Distill；正式目录的文档要维护 → Milestone Review。
触发：有明确"走通了"的时刻立即蒸馏；长期项目每 2 周、或 .scratch/ 超过 10 个文件时做一次局部蒸馏（不必等全部走通）。
流程：① log 记"开始沉淀" → ② 按四类分拣 → ③ 丢弃噪音 → ④ 更新 index.md → ⑤ log 记沉淀了什么、丢弃了什么（一句话）。
| 类别 | 处理 |
|---|---|
| 最终成果（成品文档、可用脚本、数据集） | 归入正式目录，加 frontmatter |
| 可复现路径（"如何部署 X"、"评测流程"） | 写成方法/步骤文档 |
| 关键教训（为什么不用方案 B、踩过什么坑） | 写入 lessons.md 或决策记录 |
| 有参考价值的中间产物（调研数据、对比表） | 精简后保留，标 type: 参考 |
保留判据：能回答"下次遇到类似问题怎么办""这个结论是怎么得出的""能否被未来项目直接复用" → 保留；都不满足 → 丢弃（git 历史兜底）。
.scratch/ 约定：位于项目根目录、gitignore、不加 frontmatter、不写入 index.md；蒸馏时挑走有价值的，其余清理。/tmp/ 仅用于真正一次性的计算。
Self-Iteration
项目在使用过程中自我改进，不依赖外部回顾会。
Agent Directives 中的"推动自迭代"定义了日常感知职责（工作中随时识别摩擦）。本节定义何时启动正式的结构性迭代，以及具体流程。
触发条件
不用 session 结束触发（避免噪音），而是：
- Resume 摩擦：恢复上下文时需要打开超过 5 个文件才能定位当前工作状态 → 导航结构需优化
- 规则漂移：实际操作与 CLAUDE.md/AGENTS.md 规则不一致（Agent 做了规则没覆盖的事，或规则要求了没人做的事）
- 目标漂移：实际工作方向与声明的项目目标明显偏离 → 确认是目标需要更新还是工作需要拉回
- 里程碑完成：阶段性工作结束，自然的回顾时机
- 阈值触发：log 超过归档阈值 → 归档；单目录超 7 文件且无 index → 补导航；决策记录超 10 条 → 归纳模式
- 用户显式要求："回顾一下项目结构"、"这个方法论哪里不顺"
流程
感知摩擦 → 诊断问题 → 提出改进提案 → 用户确认 → 执行变更 → 记录到 log
可迭代的层次
| 层 | 改什么 | 例子 |
|---|---|---|
| 内容 | 文档本身 | 描述过时，更新 |
| 结构 | 文件组织 | 目录太深，扁平化 |
| 规则 | CLAUDE.md/AGENTS.md 的约定 | 某条规则太死板 |
| 模式 | 工作方式 | 发现新的有效模式 |
经验沉淀（可选）
对需要持续改进的项目，维护双通道经验记录：
- lessons.md：做了什么 → 效果差 → 原因 → 以后如何避免
- wins.md：做了什么 → 效果好 → 原因 → 如何复制
与决策记录的区分：决策记录是单次选择的快照（"选了 A 而非 B"）。lessons/wins 是跨多次实践的模式总结（"三次用 X 方案都失败了，根因是 Y"）。前者记录在相关文档中，后者作为独立文件供全局参考。
方法论 changelog（可选）：方法论/规则高频迭代的项目，可维护独立 changelog 记录规则级变更（日期｜变更 → 原因 → 预期），与 work log 分流；轻量/任务执行型项目 log.md 足矣，不必另立。
从教训到规则：复发即固化 + 门禁分层
lessons/wins 是参考，什么时候升级成规则？判据是复发：
- 复发即固化：同类问题复发 ≥3 次 → 停止逐次救火，固化成规则（写进 CLAUDE.md/AGENTS.md 或专门检查），并全量扫描清存量（别只修当下那一处）。
- 门禁分层：固化时分两类——可机械校验的（格式/命名/数值/禁用项）优先做成确定性检查（清单 → 脚本/CI），此时机器结论压过 agent 判断，不给"我觉得没问题"留口子；只能语义判断的（风格/事实/取舍）留人审。零工具项目止于清单即可，不强制脚本化。
- ⚠ 谁来数复发：靠记性的规则，它的复发同样靠记性才能被发现——于是漏一次和漏五次没有区别。凡"顺手更新 X"这类规则，要么把它挂到某个必经动作上，要么直接做成检查。
门禁的有效性
"机器结论压过 agent 判断"只在门禁确实在守它声称守的那件事时成立。守卫度量的对象与要防的事不是同一件时，绿灯比没有守卫更坏——它替你提供了不看的理由。
- 立门禁先写清度量单位，并问一句"怎么绕过它而仍然合规"。答得出的那条路就是它的盲区，须一并守住或写进注释。
- 上线当轮做证伪测试：故意把它该抓的东西弄坏，确认它真的叫。"跑一遍是绿的"不构成有效性证据——零触发面的门禁跑出来也是绿的。证伪用例与门禁一起留存，否则它会静默退化成空操作。
- 触发面挂在单调不回退的事实上，不挂会变动的瞬时状态——状态一旦离开触发集，守卫就再也看不到那一项。
- 改规则的位置 = 改了守卫的输入面：搬完当轮重跑它，确认既没把条文本身判成违规，也没把新位置漏出扫描范围。
- 当前观测不到 ≠ 不存在：门禁提前返回、样本恰好为空，都会让盲区隐身。用构造的样本把潜伏路径逼出来再下结论。
规则的准入与退出
只加不减的规则集会膨胀到不被遵守。加法（复发即固化）必须配一套减法。
准入——新增规则须给三行自证：
- 防哪类：偏离目标 / 重复付出 / 口径混乱（三者都答不上 ⇒ 只能进 lessons.md 当参考，不得转正为规则）
- 可感损害：没有它，坏处具体长什么样（不需要数字；机器测不出的损害照样算）
- 成本相称：执行它的代价配得上那个损害吗
- 「禁止/删除/限频」类另答一问：这条会不会把某个加分项一起删掉？ 答不出不许进
零和——常驻层是有限的：新增一条常驻规则，必须同时指出从常驻层搬走或删掉哪一条。答不出就不许进常驻，放任务层或 lessons.md。
退出——候选自动生成（任一触发即列入清单）：
- 零命中：一条规则连续若干个审查周期从未拦下过真实问题 → 降级候选
- 计数：一批新增条目远多于关闭条目 → 该批收尾强制加一步清库复审
- 反向：某条限制被反复判定为"这是资产不是问题" → 放宽候选
权限分层：新增由 Agent 直接做（门槛 = 三行自证）；降级与删除由用户拍板，但形式是里程碑时给一份候选清单让他打勾（保留 / 降级 / 关闭）——把用户成本从"主动想起来审查"降到做选择题。
落点严管、总量只报：对"规则放在哪一层"严格执行（落点错误即时判失败：常驻层混进任务专属规则、热目录混进过程性产物）；对"总量多少"只报数不拦截——内容随项目自然增长，把总量设成硬线只会逼出抬基线或违规两条路。总量靠定期结算（到期就按退出候选退役），不靠即时拦截。
Meta-Iteration
方法论本身（这个 SKILL.md）如何改进。
信号
- 多个项目发明了相同规则 → SKILL 缺少这个通用规则
- 多个项目覆盖了 SKILL 的同一条规则 → 默认值不对
- 多个项目对 SKILL 的同一条规则得出互相矛盾的读法 → 该条不清晰，须消歧而非补充
- 新项目创建后立即改 CLAUDE.md/AGENTS.md → 初始化模板有问题
安全性
- 必须显式触发（用户说"改进这个方法论"）
- proposal 模式：提案 → 影响范围声明 → 确认 → 执行
- 版本化：SKILL.md 在 git 中，任何时候可
git revert回退 - 渐进验证：先在项目 CLAUDE.md/AGENTS.md 中局部覆盖新规则试行；使用 3 次以上未被再次覆盖 → 视为有效，可合入 SKILL.md；若无多项目可验证，试行 2 周无摩擦即可合入
- 自身遵守零和：向 SKILL.md 新增规则时同样适用 §规则的准入与退出——纯追加会让方法论本身长成它所反对的样子
Customization
不同项目类型可以调整结构。SKILL.md 定义通用骨架，项目 CLAUDE.md/AGENTS.md 按需扩展：
| 项目类型 | 典型扩展 | 说明 |
|---|---|---|
| 写作项目 | state/（运行时变量如进度、角色设定）、works/（具体作品）、prompts/（Agent 角色定义） | 方法论/角色/知识/作品四层分离 |
| 软件项目 | 产品需求/、设计文档/、信息职责边界 | 按需求→设计→信息职责边界分层 |
| 研究项目 | references/（文献来源）、findings/（发现与结论） | 按调研→结论组织 |
| 知识库 | tags 体系、跨文档链接网络 | 偏图结构而非树结构 |
任务较重的项目：复杂事项拆结构化任务资产（需求/边界 · 上下文 · 实施清单 · 决策记录，分区或分 {task}/ 目录），简单事项 inline。这是轻量任务管理——只借任务资产的结构，重编排另用专门工具（见 Boundaries）。
覆盖 SKILL.md 默认规则时，在 CLAUDE.md/AGENTS.md 中写明覆盖了什么和为什么。
Boundaries
不是：
- 记忆系统（不做向量检索、不跨项目同步状态）
- 重编排 / 多 agent 调度器——但轻量结构化任务资产（复杂事项拆 需求/设计/实施清单/决策记录）是标准项目的一等组成，见 Customization
- git 的替代品（版本管理就是 git）
- 强制模板（最小约束，项目自行演化）
是：
- 方法论指南（告诉 Agent "如何组织知识项目"）
- 结构规范（OKF 兼容的文件约定）
- 生命周期管理（从创建到归档的过程定义）
- 自我改进框架（项目和方法论都能迭代）