notebook

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Notebook

Project trail system. Initialize, save, recover, migrate, and manage project notes.

项目轨迹系统，支持初始化、保存、恢复、迁移和管理项目笔记。

When NOT to use this skill

请勿使用此技能的场景

No active project context (no git repo, no project root) — say so, don't create a floating notebook
User wants to summarize or extract knowledge from content — use
```
/extract
```
instead
Notes already exist and user just wants to read them — read directly with Read tool, skip the skill

无活跃项目上下文（无git仓库、无项目根目录）——直接告知用户，不要创建无归属的笔记本
用户想要对内容做总结或知识提取——改用
```
/extract
```
命令
笔记已存在且用户仅需阅读——直接使用读取工具打开即可，无需调用此技能

Quick Reference

快速参考

Proactive save rule: Save after every significant decision, failure, or constraint discovered — without being asked. Every ~20 tool calls without a save is too long. If you would say "I should remember this," write it now.

Command	Action
`/notebook`	Init (new project) or status (existing)
`/notebook save`	Write a note immediately — never prompts, just writes
`/notebook save resolved: <desc>`	Save a note and resolve the matching lesson
`/notebook recover`	Read index + lessons + flagged notes, summarize state
`/notebook migrate [path]`	Convert messy notes into notebook format

主动保存规则： 每当做出重大决策、遇到失败或发现限制条件时，无需用户指示自动保存。每调用约20次工具仍未保存就属于间隔过长。如果你有「我应该记住这个内容」的想法，现在就写下来。

命令	操作
`/notebook`	初始化（新项目）或查询状态（已有项目）
`/notebook save`	立即写入笔记——无需提示，直接写入
`/notebook save resolved: <desc>`	保存笔记并标记匹配的经验教训为已解决
`/notebook recover`	读取索引+经验教训+标记的笔记，总结项目状态
`/notebook migrate [path]`	将零散杂乱的笔记转换为笔记本格式

/notebook — Init & Status

/notebook — 初始化与状态查询

If notebook/ doesn't exist (new project):

若 notebook/ 目录不存在（新项目）：

Locate project root — walk up from cwd looking for:

PROJECT_STATE.md

CLAUDE.md

.git/

package.json

Cargo.toml

pyproject.toml

go.mod

If no project root found: tell the user "No project root detected — create a project first."

Create:

notebook/
├── _index.md
└── lessons.md

Initialize

_index.md

markdown

# Notes Index

Project trail — read this first on context recovery.

Initialize

lessons.md

markdown

# Lessons

What not to do. Read this every session.

Add
```
notebook/
```
to
```
.gitignore
```
(process notes are AI working memory, not public docs)

Confirm:

Notebook initialized at {project_root}/notebook/
notebook/ added to .gitignore — remove to track in git.

Retroactive save — scan the current conversation for any decisions, failures, constraints, or learnings that have already occurred. Save each one as a note immediately. If the notebook is being initialized mid-session, there is almost certainly unsaved context. Do not wait to be asked.

定位项目根目录——从当前工作目录向上层级查找以下文件/目录：
```
PROJECT_STATE.md
```
、
```
CLAUDE.md
```
、
```
.git/
```
、
```
package.json
```
/
```
Cargo.toml
```
/
```
pyproject.toml
```
/
```
go.mod
```
若未找到项目根目录：告知用户「未检测到项目根目录，请先创建项目。」

创建如下目录结构：

notebook/
├── _index.md
└── lessons.md

初始化

_index.md

：

markdown

# Notes Index

Project trail — read this first on context recovery.

初始化

lessons.md

：

markdown

# Lessons

What not to do. Read this every session.

将
```
notebook/
```
加入
```
.gitignore
```
（流程笔记属于AI工作记忆，不属于公开文档）

返回确认信息：

Notebook initialized at {project_root}/notebook/
notebook/ added to .gitignore — remove to track in git.

回溯保存——扫描当前会话中已产生的所有决策、失败、限制条件或经验总结，立即将每一条内容保存为笔记。如果是在会话中途初始化笔记本，几乎必然存在未保存的上下文，无需等待用户指令。

If notebook/ already exists (status):

若 notebook/ 目录已存在（状态查询）：

Read
```
_index.md
```
Read
```
lessons.md
```
Report: number of notes, number of lessons, last note date, count of ⚑-flagged notes
Show the last 5 index entries

读取
```
_index.md
```
读取
```
lessons.md
```
汇报：笔记总数、经验教训总数、最后一条笔记的日期、带⚑标记的笔记数量
展示最近5条索引条目

/notebook save — Write a Note

/notebook save — 写入笔记

Never prompt. Never ask questions. Just write.

无需提示，无需询问，直接写入。

Step 1: Locate Project Root

步骤1：定位项目根目录

Walk up from cwd:

PROJECT_STATE.md

→

CLAUDE.md

→

.git/

→

package.json

Cargo.toml

pyproject.toml

go.mod

No root found → "No project root detected. Run

/notebook

from within a project first."

从当前工作目录向上层级查找：

PROJECT_STATE.md

→

CLAUDE.md

→

.git/

→

package.json

Cargo.toml

pyproject.toml

go.mod

未找到根目录 → 返回「未检测到项目根目录，请先在项目目录内运行

/notebook

命令。」

Step 2: Ensure Infrastructure

步骤2：确保基础结构存在

notebook/

doesn't exist, create it with

_index.md

and

lessons.md

silently.

Initialize

_index.md

markdown

undefined

如果

notebook/

_index.md

、

lessons.md

文件。

初始化

_index.md

：

markdown

undefined

Notes Index

Project trail — read this first on context recovery.


Initialize `lessons.md`:
```markdown

Project trail — read this first on context recovery.


初始化 `lessons.md`：
```markdown

Lessons

What not to do. Read this every session.


Add `notebook/` to `.gitignore` if not already present.

What not to do. Read this every session.


如果`notebook/`尚未加入`.gitignore`，则自动添加。

Step 3: Next Note Number

步骤3：确定下一条笔记的编号

Read

_index.md

, find highest note number, increment. Start at

if empty.

读取

_index.md

，找到最大的笔记编号后加1。如果为空则从

开始。

Step 4: Infer Content

步骤4：推断笔记内容

Priority order:

Explicit argument —

/notebook save constraint: RLS can't do cross-schema joins

Conversation context — if bare
```
/notebook save
```
, synthesize from recent exchanges
Both — user hint + contextual expansion

优先级顺序：

显式参数 — 比如

/notebook save constraint: RLS can't do cross-schema joins

会话上下文 — 如果是无参数的
```
/notebook save
```
，从最近的对话中合成内容
两者结合 — 用户提示+上下文补充

Step 5: Classify Type

步骤5：分类笔记类型

Infer from content. Never ask.

Type	Signal
`decision`	Chose between options, committed to approach
`learning`	Non-obvious gotcha, unexpected behavior
`constraint`	Hard limitation (library, API, platform)
`pivot`	Changing direction from previous approach
`investigation`	Research findings, benchmarks, comparisons
`failure`	Tried something, didn't work — and why
`resolved`	A previous lesson/constraint no longer applies

Default:

learning

从内容推断类型，无需询问用户。

类型	判定特征
`decision`	在多个选项中做出选择，确定了后续执行方案
`learning`	不明显的坑、不符合预期的行为
`constraint`	硬性限制（库、API、平台层面）
`pivot`	改变之前的执行方向
`investigation`	调研结果、基准测试、对比结论
`failure`	尝试某方案失败，以及失败原因
`resolved`	之前的经验教训/限制条件不再生效

默认类型：

learning

。

Step 6: Write the Note

步骤6：写入笔记

File:

notebook/NNNN-type-short-title.md

Quick format (default):

markdown

undefined

文件路径：

notebook/NNNN-type-short-title.md

快速格式（默认）：

markdown

undefined

NNNN: Short Descriptive Title

Type: type | Date: YYYY-MM-DD

Content. 1-5 lines. Be specific — library names, error messages, version numbers. What happened, what it means going forward.


**Full format (major architectural decisions only):**

```markdown

Type: type | Date: YYYY-MM-DD

Content. 1-5 lines. Be specific — library names, error messages, version numbers. What happened, what it means going forward.


**完整格式（仅用于重大架构决策）：**

```markdown

NNNN: Short Descriptive Title

Type: decision | Date: YYYY-MM-DD Status: accepted

Context

What prompted this? (1-3 sentences)

Decision

What we decided. Be specific.

Rationale

Why this over alternatives.

Alternatives Considered

Alternative A: Rejected because X

Alternative A: Rejected because X

Consequences

What this means going forward.


Threshold: meaningful alternatives considered AND hard to reverse → full format. Everything else → quick.

What this means going forward.


使用阈值：考量了多个可行方案且决策难以回退 → 使用完整格式，其他所有场景 → 使用快速格式。

Step 7: Update Index

步骤7：更新索引

Append a rich one-line summary to

_index.md

- NNNN type: Detailed one-liner useful standalone

⚑ flag for critical constraints, breaking discoveries, architectural decisions:

- NNNN ⚑ constraint: Critical thing every session must know

在

_index.md

末尾追加信息完整的单行总结：

- NNNN type: Detailed one-liner useful standalone

对于关键限制、突破性发现、架构决策添加⚑标记：

- NNNN ⚑ constraint: Critical thing every session must know

Step 8: Update Lessons (conditional)

步骤8：更新经验教训（条件触发）

For types
failure
,
learning
,
constraint
: append a distilled one-liner to

lessons.md

Format — pure signal, no metadata:

- Concise lesson. What not to do and why, or what to do instead.

The full note has context and details. The lesson is the takeaway — one line a model can scan in a second.

For type
resolved
: write the note as usual, then find the matching lesson in

lessons.md

and strike it:

- ~~Prisma doesn't work with edge runtime~~ → Resolved in 0047

How to match: use the content of the

/notebook save resolved:

argument to find the most relevant lesson line. Match on key terms (library names, error descriptions, the constraint being resolved). If no clear match is found, write the note but warn:

Note saved but no matching lesson found to resolve.

Strikethrough preserves history — a model sees what used to be a problem and knows to skip it. The note reference lets anyone find the resolution details.

对于
failure
、
learning
、
constraint
类型：将提炼后的单行总结追加到

lessons.md

中。

格式——仅保留核心信息，无元数据：

- Concise lesson. What not to do and why, or what to do instead.

完整笔记包含上下文和细节，经验教训是提炼的结论——模型一秒就能扫描完的单行内容。

对于
resolved
类型：按常规流程写入笔记，然后在

lessons.md

中找到匹配的经验教训，添加删除线：

- ~~Prisma doesn't work with edge runtime~~ → Resolved in 0047

匹配规则：使用

/notebook save resolved:

的参数内容查找最相关的经验教训行，基于关键词匹配（库名、错误描述、待解决的限制条件）。如果没有明确匹配项，保存笔记但给出警告：

Note saved but no matching lesson found to resolve.

删除线会保留历史记录——模型可以看到曾经存在的问题并知道可以跳过，笔记引用也方便任何人查看解决细节。

Step 9: Update PROJECT_STATE.md (conditional)

步骤9：更新PROJECT_STATE.md（条件触发）

Only if the note materially changes project state (blocking constraint, architecture change, pivot). If no

PROJECT_STATE.md

exists, skip.

仅当笔记内容实质性改变了项目状态时触发（阻塞性限制、架构变更、方向调整）。如果不存在

PROJECT_STATE.md

则跳过。

Output

输出

Single line confirmation:

Saved: notebook/NNNN-type-short-title.md

Nothing else.

单行确认信息：

Saved: notebook/NNNN-type-short-title.md

无其他内容。

/notebook recover

Read full
```
_index.md
```
Read full
```
lessons.md
```
Open all ⚑-flagged notes
Open the last 3 notes
Read
```
PROJECT_STATE.md
```
if it exists
Summarize: what the project is, key decisions, active constraints, known pitfalls, current state
Ask: "What's changed since this was last updated?"

读取完整的
```
_index.md
```
读取完整的
```
lessons.md
```
打开所有带⚑标记的笔记
打开最近3条笔记
如果存在
```
PROJECT_STATE.md
```
则读取
总结内容：项目定位、关键决策、活跃限制、已知坑、当前状态
询问：「上次更新后有什么变动吗？」

/notebook migrate

Convert existing messy notes into notebook format. One-time onboarding for projects with pre-existing notes.

Scan the target folder (cwd or specified path) for markdown and text files
Read each file
Classify each: decision, learning, constraint, failure, investigation, or pivot
Write each as a properly numbered notebook note in
```
notebook/
```
Build
```
_index.md
```
from scratch with rich one-line summaries
Extract lessons from anything that looks like a failure, constraint, or learning → populate
```
lessons.md
```
Leave originals untouched. User deletes them when satisfied.

notebook/

already has notes, continue numbering from the highest existing. Migrate never overwrites existing notes.

After migration, report: how many files found, how many converted, how many lessons extracted. Show the generated index.

将已有的零散笔记转换为笔记本格式，用于已有历史笔记的项目的一次性初始化。

扫描目标文件夹（当前工作目录或指定路径）下的markdown和文本文件
读取每个文件
为每个文件分类：decision、learning、constraint、failure、investigation、pivot
将每个内容按编号规则写入
```
notebook/
```
目录下的规范笔记文件
从零构建
```
_index.md
```
，添加完整的单行总结
从所有failure、constraint、learning类内容中提取经验教训，填充到
```
lessons.md
```
原始文件保持不变，用户确认无误后可自行删除。

如果

notebook/

中已有笔记，从现有最大编号开始继续排序，迁移操作永远不会覆盖已有笔记。

迁移完成后汇报：找到的文件总数、转换的笔记数量、提取的经验教训数量，展示生成的索引。

Resolving Lessons

标记经验教训为已解决

To mark a lesson as resolved use:

/notebook save resolved: <exact phrase or lesson number>

Matching rules:

Prefer exact phrase match from lessons.md
If ambiguous or no match found, list the open lessons and ask the user to confirm which one
Never silently skip — always confirm what was resolved

Mark resolved lessons with strikethrough in

lessons.md

markdown

~~Lesson text here~~ *(resolved: [date or brief reason])*

Archiving: When

lessons.md

exceeds 50 resolved (struck-through) entries, move all resolved lessons to

lessons-archive-YYYY-MM.md

and remove them from the active file. Keep only open lessons in the active file.

使用以下命令标记经验教训为已解决：

/notebook save resolved: <精确短语或经验教训编号>

匹配规则：

优先匹配lessons.md中的精确短语
如果存在歧义或未找到匹配项，列出所有未解决的经验教训，请用户确认要标记的条目
永远不要静默跳过——始终确认已解决的内容

在

lessons.md

中为已解决的经验教训添加删除线：

markdown

~~Lesson text here~~ *(resolved: [date or brief reason])*

归档： 当

lessons.md

中已解决（带删除线）的条目超过50条时，将所有已解决的经验教训移动到

lessons-archive-YYYY-MM.md

中，从活跃文件中移除，仅保留未解决的经验教训在活跃文件中。

Stale Lesson Detection

过时经验教训检测

When reading

lessons.md

during context recovery, check if any lessons are outdated — library upgrades, removed constraints, resolved workarounds. Flag to the user: "Lesson [X] may be stale — [reason]. Want me to resolve it?"

在上下文恢复阶段读取

lessons.md

时，检查是否存在过时的经验教训——库升级、限制移除、 workaround已解决等。向用户发出提示：「经验教训[X]可能已过时——[原因]，需要我将其标记为已解决吗？」

Context Recovery Priority

上下文恢复优先级

On any new session or

/notebook recover

, read in this order:

```
_index.md
```
— what is this project, what happened
```
lessons.md
```
— what not to do
⚑-flagged notes — critical details the index can't capture
Last 3 notes — recent context
```
PROJECT_STATE.md
```
— current snapshot (if exists)

每次新会话启动或执行

/notebook recover

时，按以下顺序读取内容：

```
_index.md
```
—— 项目是什么，发生过什么
```
lessons.md
```
—— 不能做什么
带⚑标记的笔记 —— 索引无法覆盖的关键细节
最近3条笔记 —— 近期上下文
```
PROJECT_STATE.md
```
—— 当前状态快照（如果存在）

Rules

规则

Never prompt on /notebook save. Infer everything from context and arguments.
Quick format by default. Full format is rare — major architectural decisions only.
Rich index entries. The index alone should be sufficient for context recovery.
Be specific. Library names, error messages, versions > vague descriptions.
Failures are gold. "Tried X, failed because Y" prevents loops. Always save these.
One note per save. Don't batch multiple insights.
⚑ sparingly. Only for things every future session must read.
Notes are append-only. New moment = new note. Update existing only to mark superseded.
Lessons are distilled. One line, pure signal. If you need context, open the note.

执行/notebook save时永远不要提示用户，从上下文和参数中推断所有信息。
默认使用快速格式，完整格式仅用于罕见的重大架构决策场景。
索引条目信息要完整，仅靠索引就应该足以完成上下文恢复。
内容要具体，库名、错误信息、版本号 > 模糊描述。
失败记录价值很高，「尝试了X方案，因为Y原因失败」可以避免重复循环，务必保存。
每次保存仅写一条笔记，不要批量合并多个洞察。
谨慎使用⚑标记，仅标记所有未来会话都必须阅读的内容。
笔记是仅追加模式，新的时间节点对应新的笔记，仅当标记内容被取代时才修改已有笔记。
经验教训要提炼，单行纯核心信息，需要上下文时再打开对应笔记。