docs-vault

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

docs-vault

Every repo can carry a curated knowledge base in an in-repo Obsidian vault that describes the code and links to it. Use it to load context before working, and to record what you learn. Git is the sync layer, so this works the same locally and for remote agents: everyone has the repo, writes notes, and commits.

每个代码仓库都可以包含一个精心维护的Obsidian知识库，用于描述代码并建立代码链接。你可以在开始工作前通过它获取上下文信息，也可以将学到的内容记录其中。Git作为同步层，无论本地还是远程Agent使用，体验都是一致的：所有人都拥有仓库权限，可编写笔记并提交。

When to use this skill

何时使用本技能

Before engineering or reviewing in an unfamiliar repo: read the vault for how things actually work, the domain language, the standards, and the gotchas.
After learning something durable (a non-obvious flow, a decision, a trap): write or update a note so the next agent does not relearn it.

Do NOT put code in the vault, and do NOT mirror source files into markdown. Notes point AT code; the code stays the single source of truth.

在不熟悉的仓库中进行开发或评审前：阅读知识库，了解实际运作方式、领域术语、规范要求以及常见陷阱。
在掌握了持久有用的知识后（如非直观的流程、决策记录、易踩的陷阱）：编写或更新笔记，避免后续Agent重复踩坑。

请勿在知识库中存放代码，也请勿将源文件镜像为Markdown文件。笔记只需指向代码即可；代码始终是唯一的事实来源。

Vault location and name

知识库的位置与命名

The vault lives at

<repo-root>/docs/<repo-name>-vault/

, where

<repo-name>

is the repo's directory name. The folder is named

<repo-name>-vault

(e.g.

docs/docket-vault/

) on purpose: Obsidian takes its vault name from the opened folder, so this makes the repo name show in Obsidian's picker and title bar instead of a generic "vault". Resolve

<repo-root>

per runtime; see

references/runtimes.md

. In Claude Code:

git rev-parse --show-toplevel

If the vault does not exist yet, scaffold it (idempotent):

bash

bash <path-to-this-skill>/scripts/init-vault.sh "$(git rev-parse --show-toplevel)"

This creates

_index.md

, the category folders, and a

.gitignore

that excludes

.obsidian/

. Obsidian creates

.obsidian/

itself when first opened (per-machine UI state); you do not create it and it is not committed.

知识库位于

<repo-root>/docs/<repo-name>-vault/

，其中

<repo-name>

是仓库的目录名称。文件夹命名为

<repo-name>-vault

（例如

docs/docket-vault/

）是有意为之的：Obsidian会从打开的文件夹名称获取知识库名称，这样仓库名称会显示在Obsidian的选择器和标题栏中，而非通用的“vault”。根据运行时环境确定

<repo-root>

；可参考

references/runtimes.md

。在Claude Code中，可通过命令

git rev-parse --show-toplevel

获取。

如果知识库尚未存在，可通过以下命令初始化（幂等操作）：

bash

bash <path-to-this-skill>/scripts/init-vault.sh "$(git rev-parse --show-toplevel)"

该命令会创建

_index.md

、分类文件夹以及排除

.obsidian/

的

.gitignore

文件。

.obsidian/

是Obsidian首次打开时自动创建的（每台机器的UI状态文件）；无需手动创建，也无需提交到Git。

Layout

目录结构

docs/<repo>-vault/
├── _index.md      Map of Content: entry point; links to every note
├── architecture/  how subsystems fit together
├── domain/        domain model + ubiquitous language
├── how-it-works/  walkthroughs of real flows
├── standards/     conventions/patterns to follow in this repo
├── decisions/     light decisions; link out to ../../../docs/adr/* where present
└── gotchas/       traps and pitfalls

docs/<repo>-vault/
├── _index.md      内容索引：入口文件；链接到所有笔记
├── architecture/  子系统架构说明（各子系统如何协作）
├── domain/        领域模型 + 通用语言定义
├── how-it-works/  实际流程演练
├── standards/     本仓库需遵循的约定/模式
├── decisions/     轻量决策记录；若存在ADR文档，可链接到 ../../../docs/adr/*
└── gotchas/       常见陷阱与误区

Note format

笔记格式

Every note starts with frontmatter and links to the code it describes. A note in a category folder sits THREE levels below the repo root (

docs/<repo>-vault/<category>/note.md

), so repo-root-relative links start with

../../../

markdown

---
title: How ingestion writes the archive
aliases: [How ingestion writes the archive]
tags: [how-it-works, ingestion, archive]
updated: 2026-06-15
code: [lib/ingest/ingest-filing.ts, lib/chunk/chunks.ts]
---

每个笔记都以Frontmatter开头，并链接到它所描述的代码。分类文件夹中的笔记位于仓库根目录下三级路径（

docs/<repo>-vault/<category>/note.md

），因此相对于仓库根目录的链接需以

../../../

开头：

markdown

---
title: How ingestion writes the archive
aliases: [How ingestion writes the archive]
tags: [how-it-works, ingestion, archive]
updated: 2026-06-15
code: [lib/ingest/ingest-filing.ts, lib/chunk/chunks.ts]
---

How ingestion writes the archive

Ingestion pulls a filing from EDGAR and writes ordered [[Chunk]]s into the [[Archive]]. Entry point:

lib/ingest/ingest-filing.ts

...


Rules:
- `title`, `tags`, `updated` (today's date, `YYYY-MM-DD`), and `code` (repo-relative
  paths the note describes) are required in frontmatter.
- Link notes to each other with `[[wikilinks]]`. Obsidian resolves a wikilink by
  **filename** (or by an alias), NOT by the H1/title. So `[[glossary]]` resolves
  to `glossary.md`. If you want to link by a human title that differs from the
  filename, add `aliases: [Domain glossary]` to that note's frontmatter, then
  `[[Domain glossary]]` resolves too. Pick one convention per vault and keep it.
- Link to code and existing docs with **relative** markdown links, resolved from
  the note's own folder. From a category note (three deep), repo-root files are
  `../../../`: e.g. `../../../CONTEXT.md`, `../../../lib/ingest/ingest-filing.ts`,
  `../../../docs/adr/0003-....md`. Verify a link resolves before trusting it.
- Keep notes small and durable. State how things work and why; do not paste code.

Ingestion pulls a filing from EDGAR and writes ordered [[Chunk]]s into the [[Archive]]. Entry point:

lib/ingest/ingest-filing.ts

...


规则：
- Frontmatter中必须包含 `title`、`tags`、`updated`（格式为`YYYY-MM-DD`，即当天日期）和 `code`（笔记所描述的仓库相对路径）。
- 使用 `[[维基链接]]` 在笔记之间建立链接。Obsidian通过**文件名**（或别名）解析维基链接，而非H1标题。例如 `[[glossary]]` 会解析到 `glossary.md`。如果希望通过与文件名不同的人性化标题建立链接，可在目标笔记的Frontmatter中添加 `aliases: [Domain glossary]`，之后 `[[Domain glossary]]` 也能正确解析。每个知识库需统一使用一种命名约定。
- 使用**相对**Markdown链接指向代码和现有文档，链接路径从笔记所在文件夹开始解析。对于分类文件夹中的笔记（三级路径），仓库根目录下的文件需使用 `../../../`：例如 `../../../CONTEXT.md`、`../../../lib/ingest/ingest-filing.ts`、`../../../docs/adr/0003-....md`。在信任链接前，请先验证其是否可正常解析。
- 保持笔记简洁且持久有效。说明事物的运作方式及原因；请勿粘贴代码。

Reading / querying

阅读/查询方法

Read the vault's
```
_index.md
```
first; it maps what exists.
Then search the vault:
- Claude Code: Grep/Glob over
```
docs/<repo>-vault/**
```
  (search
```
tags:
```
  and
```
code:
```
  to find notes about a file or topic).
- Hermes:
```
search_files
```
  with
```
target: "content"
```
  and
```
file_glob: "*.md"
```
  under the vault path.

首先阅读知识库的
```
_index.md
```
文件；它包含了所有内容的索引。
然后搜索知识库：
- Claude Code：通过Grep/Glob搜索
```
docs/<repo>-vault/**
```
  （搜索
```
tags:
```
  和
```
code:
```
  字段，找到与特定文件或主题相关的笔记）。
- Hermes：使用
```
search_files
```
  命令，设置
```
target: "content"
```
  和
```
file_glob: "*.md"
```
  ，指定知识库路径。

What earns an entry

笔记收录标准

A note earns its place when it captures something expensive to re-derive from the code and stable enough not to rot. That test promotes a few kinds of note and demotes one:

Flow maps (highest value). Whenever a real flow spans several files or modules, map it: what calls what, in what order, and why. This is the note that saves the next agent from opening a dozen files to reconstruct the path. Write it at an altitude that survives refactors: name the modules, types, and contracts and the direction data flows, plus the invariants and the seams (where behaviour is chosen or extended). Do NOT make file paths or line numbers the payload; cite them as links, not as the content.
Gotchas and non-obvious constraints, decisions and their why, and the glossary all pass the same test and are worth capturing.
Do NOT write prose that restates what the code does. The code says it better, and that is exactly the note that rots into a lie.

A wrong map is worse than none, because it sends the reader the wrong way with confidence. Two habits keep maps trustworthy:

Keep them coarse (coarse maps drift slowly), and update the map in the same change that alters the flow.
Capture demand-driven: write the map the moment you have just reconstructed a flow the hard way, while it is fresh. Do not pre-map everything speculatively; the speculative notes rot unread.

当笔记记录的内容从代码中重新推导成本很高且足够稳定不会过时时，才值得收录。这个标准筛选出以下几类值得记录的内容，同时排除一类内容：

流程图谱（最高价值）。当实际流程跨越多文件或模块时，绘制流程图谱：说明调用关系、顺序及原因。这类笔记能帮助后续Agent无需打开十几个文件即可重构流程路径。编写时需保持一定的抽象高度，以适应代码重构：命名模块、类型和契约，说明数据流向、不变量和扩展点。请勿将文件路径或行号作为核心内容；只需将它们作为链接引用即可。
常见陷阱与非直观约束、决策记录及其原因、术语表都符合收录标准，值得记录。
请勿编写复述代码功能的文字。代码本身的表述更准确，这类笔记会很快过时并与实际情况不符。

错误的流程图谱比没有图谱更糟糕，因为它会误导读者并使其产生错误的信心。以下两个习惯可保持图谱的可信度：

保持图谱粗粒度（粗粒度图谱的更新频率更低），并且在同一变更中修改流程图谱和对应的代码。
按需记录：当你刚通过艰难方式重构完流程时，立即记录图谱，此时记忆还很清晰。请勿投机性地预先绘制所有流程；这类投机性笔记会无人问津并逐渐过时。

Writing / updating

编写/更新方法

Write back when you finish a unit of work that is implemented, verified, and accepted, not mid-task and not speculatively. Record durable knowledge: a non-obvious flow, a gotcha, a standard, a decision, or a corrected link. This is the write half of the self-healing loop; the repo's

AGENTS.md

carries the read-first/write-after instruction (managed by

init-vault.sh

Create or edit the
```
.md
```
note in the right category folder.
Add or update its link in
```
_index.md
```
under
```
## Notes
```
.
Set
```
updated:
```
to today.
Commit:
```
git add docs/<repo>-vault && git commit -m "docs(vault): ..."
```
. Push per the repo's policy. (Solo-dev repos: straight to the default branch unless the repo's own AGENTS.md says otherwise; check it.)

Under Hermes Docker, write to the bind-mounted container path so files reach the host. See

references/runtimes.md

请在完成已实现、验证并被接受的工作单元后再编写或更新笔记，不要在任务进行中或投机性地记录。记录持久有用的知识：如非直观的流程、常见陷阱、规范要求、决策记录或修正后的链接。这是自我完善循环的写作环节；仓库中的

AGENTS.md

文件包含了“先阅读、后写作”的指导说明（由

init-vault.sh

管理）。

在对应的分类文件夹中创建或编辑
```
.md
```
笔记。
在
```
_index.md
```
的
```
## Notes
```
部分添加或更新该笔记的链接。
将
```
updated:
```
设置为当天日期。
提交到Git：
```
git add docs/<repo>-vault && git commit -m "docs(vault): ..."
```
。根据仓库的策略推送代码。（单人开发仓库：除非仓库自身的AGENTS.md另有说明，否则直接推送到默认分支；请先查看该文件。）

在Hermes Docker环境下，请写入绑定挂载的容器路径，以便文件同步到宿主机。可参考

references/runtimes.md

。

Discovery hook

发现机制

So other agents actually find the vault, ensure the repo's

AGENTS.md

(or

CLAUDE.md

) contains a line pointing at the vault's index, e.g.:

Knowledge base: read
docs/docket-vault/_index.md
first.

Use the repo's actual vault folder name. Add it once if missing; do not duplicate.

为了让其他Agent能够找到知识库，请确保仓库的

AGENTS.md

（或

CLAUDE.md

）文件中包含指向知识库索引的行，例如：

知识库：请先阅读
docs/docket-vault/_index.md
。

请使用仓库实际的知识库文件夹名称。如果缺失则添加一次；请勿重复添加。

Accuracy

准确性要求

Notes must be verified against the code, never guessed. If a note disagrees with the code, the code wins: fix the note and bump

updated:

笔记必须与代码验证一致，切勿猜测。如果笔记与代码不符，以代码为准：修正笔记并更新

updated:

字段。