# Knowledge Project

> 管理自描述的知识工作项目的结构和生命周期。当用户要创建新的知识项目、 初始化项目结构、恢复项目上下文、维护文档和日志、回顾项目方法论、 或需要指导如何让项目对 Agent 自描述时使用。也适用于：新建项目、 初始化文档结构、帮我整理这个项目、接着上次、项目怎么组织、 setup project、resume context、回顾方法论。

- Skill: `briqt/knowledge-project` (Agent Skill)
- Install (CLI): `npx skillmds@latest add briqt/knowledge-project`
- Raw SKILL.md: https://api.skillmd.com/api/skills/briqt/knowledge-project/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: briqt (https://skillmd.com/u/briqt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/briqt/knowledge-project

---


# Knowledge Project

将知识工作组织为自描述项目——任何 Agent 打开即可理解和继续，无需外部记忆系统。

## Philosophy

**核心理念**：项目本身携带完整上下文。不依赖特定平台、记忆服务或对话历史。

**设计原则：**

1. **纯文件 + 约定**：markdown + YAML frontmatter，零工具依赖，git 友好
2. **自包含**：每个文档独立可理解，项目整体打开即可继续
3. **最小约束**：只规定互操作必需的结构，其余由项目自行演化
4. **写的人花 2 分钟，读的人省 20 分钟**：信息密度优先，格式服务检索
5. **单一权威源**：规则只在一处定义，其他文件引用不复述

**格式基础**：[Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) —— 知识用 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

知识工作的认知纪律。贯穿所有工作流，优先级高于具体流程步骤。

1. **基于证据**：判断、选择、结论须追溯到可观测的依据。没有证据时承认不确定，而非填充看似合理的假设。委派或其他 Agent 的产出同样是候选输入而非既定事实——引用它做不可逆动作（删除、归档、改权威源）前先复核源头。
2. **在行动点决策**：不提前锁定依赖未知信息的决定。确定方向，开始行动，让工作本身产生下一个决策点。
3. **完整执行**：不跳步骤，不用"以此类推"代替实际工作。产出是做出来的，不是规划出来的。
4. **对齐优先于执行**：目标有歧义、存在矛盾、或涉及方向性取舍时，先澄清再行动。推断可以替代追问，但推断必须显式呈现供纠正——不用默认值静默填充。

## 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 字段约定。

```yaml
---
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（工作日志）

```markdown
### YYYY-MM-DD 事项名称 @操作人

**进展**：本次完成了什么
**决策**：做了什么选择、为什么（无则省略）
**阻塞**：卡在什么上（无则省略）
**下一步**：接下来该做什么
```

**规则：**
- 一条 = 一次实质进展，没有实质内容不写
- 每条不超过 5 行
- 最新在底部（append-only，git diff 友好）
- `@操作人` 用 git 用户名，AI Agent 用 `@ai`
- `下一步` 是 session 接力的核心机制——写法标准：一个新 Agent 只读这一条就知道该做什么
- **归档阈值 = 装得下 Resume 所需的最近窗口**（约 2-3 天或 10-15 条），默认 200 行。条目密度高的项目按此上调并在 CLAUDE.md/AGENTS.md 写明覆盖值——阈值卡在绝对行数上会把接力需要的上下文一起归档掉

### 决策记录

内联到相关文档末尾的 `## 决策记录` 章节。

```markdown
### YYYY-MM-DD 结论短语

**背景**：面临什么选择
**结论**：选了什么
**理由**：为什么
**排除**：为什么不选其他方案
```

只记有多个可行方案的决策。排除理由必写。

### 归档即关闭

归档 = 该事项在本项目告一段落，状态一律视为**已完成**。条目里记录的缺口、未尽、未发版、待外部处理项均为**历史态**：不作为待办，不再主动注意、复述、扫描或提议处理（状态分析与 Health Check 亦不纳入）。唯一复活入口是用户主动提起。

对应的 frontmatter 表达是 `status: deprecated`（OKF §5.4：保留链接与历史，不再是当前）。

**收口是原子操作**：关闭一个事项必须在同一次操作内完成——① 源头的"下一步"置为完结；② log 追一条收口；③ 移出活跃视图。缺一不算收口，留下的就是"假活跃"。

## Workflows

### Initialize（创建新项目）

1. 创建项目目录
2. 写 CLAUDE.md/AGENTS.md：
   - 项目目标、结构约定
   - **内联种子规则**（见 Seed 章节）——确保后续 Agent 在没有任何外部方法论在场时也能维护项目
   - 种子包含**自足声明**（见下）
3. 创建 log.md，第一条记录"项目创建 + 目标"
4. 创建第一个内容文件（带 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**）：

```markdown
## 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 阅读协议：
1. CLAUDE.md/AGENTS.md → 理解项目结构和约定
2. 任务路由表（如有）→ 按本次任务加载对应的任务层规则
3. 任务清单（如有）→ 知道当前活跃任务
4. log.md 尾部 5-10 条 → 知道最近进展和阻塞
5. 进入具体工作

### 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 积累到一定量。

1. 回顾 log 近期条目，识别模式
2. 更新 CLAUDE.md/AGENTS.md 中的规则（如果有过时的）
3. 生成规则退出候选清单，交用户打勾（见 Self-Iteration §规则的准入与退出）
4. 归档已废弃内容
5. 重组 index.md
6. 在 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 判断"只在门禁**确实在守它声称守的那件事**时成立。守卫度量的对象与要防的事不是同一件时，绿灯比没有守卫更坏——它替你提供了不看的理由。

- **立门禁先写清度量单位**，并问一句"怎么绕过它而仍然合规"。答得出的那条路就是它的盲区，须一并守住或写进注释。
- **上线当轮做证伪测试**：故意把它该抓的东西弄坏，确认它真的叫。"跑一遍是绿的"不构成有效性证据——零触发面的门禁跑出来也是绿的。证伪用例与门禁一起留存，否则它会静默退化成空操作。
- **触发面挂在单调不回退的事实上**，不挂会变动的瞬时状态——状态一旦离开触发集，守卫就再也看不到那一项。
- **改规则的位置 = 改了守卫的输入面**：搬完当轮重跑它，确认既没把条文本身判成违规，也没把新位置漏出扫描范围。
- **当前观测不到 ≠ 不存在**：门禁提前返回、样本恰好为空，都会让盲区隐身。用构造的样本把潜伏路径逼出来再下结论。

### 规则的准入与退出

只加不减的规则集会膨胀到不被遵守。加法（复发即固化）必须配一套减法。

**准入——新增规则须给三行自证**：

1. **防哪类**：偏离目标 / 重复付出 / 口径混乱（三者都答不上 ⇒ 只能进 lessons.md 当参考，不得转正为规则）
2. **可感损害**：没有它，坏处具体长什么样（不需要数字；机器测不出的损害照样算）
3. **成本相称**：执行它的代价配得上那个损害吗
   - 「禁止/删除/限频」类另答一问：**这条会不会把某个加分项一起删掉？** 答不出不许进

**零和——常驻层是有限的**：新增一条常驻规则，必须同时指出从常驻层搬走或删掉哪一条。答不出就不许进常驻，放任务层或 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 兼容的文件约定）
- 生命周期管理（从创建到归档的过程定义）
- 自我改进框架（项目和方法论都能迭代）