prelude

Prelude

为 AI Agent 提供项目记忆和代码地图：该看哪里、代码为何如此编写，以及一次更改会影响什么。

使用 grep 的 Agent 能找到某个词出现在哪里，却无法知道代码为何如此编写、哪些测试覆盖某个文件、还有多少其他文件依赖它，或上一次会话学到了什么。这些知识并不在源代码中。

Prelude 将这些内容保存在代码仓库中。它会扫描一次项目，并将一小组 JSON 文件写入 .context/：技术栈、架构、约束、决策，以及包含每个模块、其导出内容和导入关系的代码地图。你提交这些文件，Agent 会在工作时继续补充。之后的每次会话都可以通过 MCP 服务、生成的 CLAUDE.md / AGENTS.md，或直接从标准输出读取这些内容。

无需嵌入、无需托管服务，也不会发起网络请求。通过正则表达式启发式规则分析 TypeScript/JavaScript、Python、Go 和 Rust。

快速开始

cd your-project
npx prelude-context init        # writes .context/

或者安装它，即可获得本 README 其余部分使用的 prelude 命令：

npm install -g prelude-context
prelude init

然后为它提供一个任务描述：

prelude locate preserve manual edits during update --limit 2

1. src/core/merger.ts  ·  src/core (Core business logic)  ·  score 32
   exports: MergeResult, MergeChange, ContextMerger, trackMapFields
   why: decision: Manual edits are sacred, content preserve×25, manual×31, edit×9, update×6, matches all terms
   impact: imported by 4 files  ·  tests: tests/map-merge.test.ts, tests/mcp-server.test.ts, tests/merge-preserve.test.ts
   decisions: Manual edits are sacred
2. src/core/state-manager.ts  ·  src/core (Core business logic)  ·  score 26
   exports: StateManager
   why: decision: Manual edits are sacred, content manual×9, edit×4, update×6, matches all terms
   impact: imported by 7 files  ·  tests: tests/map-merge.test.ts, tests/mcp-server.test.ts, tests/merge-preserve.test.ts
   decisions: Manual edits are sacred

一次调用即可返回要阅读的文件、每个文件入选的理由、依赖这些文件的内容、之后要运行的测试，以及约束本次更改的已记录决策。这是本代码仓库的真实输出，它会将自己的 .context/ 纳入版本控制。浏览其中的内容，即可了解 Prelude 会写入什么。

需要 Node.js >= 20.19。

你将获得什么

your-project/
└── .context/
    ├── project.json        what the project is
    ├── stack.json          language, runtime, frameworks, tooling
    ├── architecture.json   type, patterns, directories, entry points, routes
    ├── constraints.json    rules and preferences
    ├── decisions.json      architecture decisions and their rationale
    ├── map.json            modules, exports, import graph, hub files
    ├── changelog.md        project timeline
    └── .prelude/           state: which fields were inferred, which you edited

提交 .context/。将 .context/*.session.json 加入 Git 忽略列表。

prelude compact 会将所有内容压缩为每个部分一行的紧凑格式，适合放入系统提示词（对于此代码仓库，只需几百个 token）：

[project] prelude-context | The open standard for expressing and maintaining machine-readable context about a codebase
[stack] TypeScript/JavaScript Node.js >=20.19.0 | pnpm | testing: Vitest
[arch] type=cli | patterns: Utility modules | entry: bin/prelude.ts | dirs: bin (Executable entry points), src/commands (Command handlers), src/core (Core business logic), src/mcp (MCP server), ...
[decisions] Manual edits are sacred (accepted); Regex heuristics, not AST parsers (accepted); Schemas are the contract (accepted); ...
[map] hubs: src/utils/fs.ts(25), src/runtime/context.ts(20), src/schema/index.ts(18), ... | src/core (Core business logic): state-manager.ts, infer.ts, map-scanner.ts +15 | ...

grep 无法告诉 Agent 的信息

问题	Prelude 从哪里获取答案
这段代码为何如此编写？	decisions.json：由你或使用 prelude_record_decision 的 Agent 记录的决策及其理由
有哪些内容依赖此文件？	map.json：已解析的导入图、导入者数量和枢纽文件
哪些测试覆盖它？	map.json：导入此文件的测试文件
上一次会话对这个模块有什么新发现？	模块备注，通过 prelude annotate 或 prelude_annotate_module 编写，且绝不会被覆盖
在这里必须避免什么？	constraints.json
此代码仓库如何与另一个仓库交互？	project.json 中的 relatedProjects，在工作区模式下跨仓库提供

prelude locate 会将前四项附加到它返回的每个文件中。对于刚完成初始化的项目，决策和备注为空；首次运行后，导入图和测试信息便已就绪，其余内容则会随着开发者和 Agent 不断记录而逐步积累。

locate 查找文件的效果如何？

bench/locate-bench.ts 会重放一个仓库的 Git 历史：每条提交主题作为查询，该提交修改的文件作为答案，并将仓库检出到父提交，这样就不会看到此次修改。基线方案是在相同文件中搜索每个查询词，并按匹配到的不同词数排序。前 8 个结果中包含正确文件的查询占比：

Repo	源文件数	排序后的 grep	prelude locate
cobra (Go)	37	95%	96%
flask (Python)	82	83%	86%
hono (TypeScript)	361	88%	97%
ripgrep (Rust)	100	64%	79%
typer (Python)	629	76%	74%
express (JavaScript)	147	87%	90%
平均值		82%	87%

首个结果有 48% 的概率正确，而 grep 为 39%。每个仓库最多使用 100 条提交。评分权重是根据这六个仓库选定的，因此这些数字属于样本内结果；请在自己的仓库上运行脚本进行验证（参见 CONTRIBUTING.md）。这里将查找文件作为基线，而非重点：重点是上表。

为什么不直接编写 CLAUDE.md 或 AGENTS.md？

保留它们。Prelude 可以生成这两种文件（prelude export --format claude-md、--format agents-md），也可以基于已有文件进行初始化（prelude init --from-claude-md）。区别在于底层的实现：

• 不会悄无声息地过时。 手写的上下文文件在写下的那天是正确的。若已提交的上下文与代码不再一致，prelude diff --check 会以状态码 1 退出，因此 CI 能捕捉到偏差。
• 结构化。 JSON 带有公开的 schema，因此工具可以查询单个部分、目录或模块，而不必加载整个 Markdown 文件。
• 能回答“在哪里”和“还有什么”。 prelude locate 会将任务描述转换为简短的文件列表，并说明选中每个文件的原因、覆盖它的测试以及适用的决策。纯文本文件做不到这一点。
• 你的编辑会保留。 Prelude 会跟踪哪些字段是推断得出的，哪些是你编写的。prelude update 会刷新前者，绝不会改动后者。
• 适用于多个项目。 注册多个仓库后，只需一个 MCP 服务即可查询所有仓库，包括它们之间的关系。
• 不绑定单一工具。 同一批文件可供 Claude Code、Cursor、Codex、Claude Desktop 或任何能读取 JSON 的工具使用。

与其他方案的关系

• 会话内生成的仓库映射（例如 Aider 的映射）会在会话开始时生成，并在会话结束时丢弃。Prelude 的映射是一个文件：可以在拉取请求中查看差异、手动修正，并由整个团队共享。
• 托管式代码搜索和索引服务提供更强大的检索能力，但需要运行或付费使用。Prelude 则是静态文件和本地 CLI。
• 基于嵌入的检索能找到 Prelude 的词项匹配会遗漏的语义匹配。Prelude 的结果具有确定性且会说明原因，并且生成它们不花费任何成本。

在 Agent 中使用（MCP）

Prelude 会通过 stdio 作为 MCP 服务运行。

一个项目

在包含 .context/ 目录的项目中，向 Claude Code 注册该服务：

claude mcp add prelude-context -- npx -y prelude-context serve

对于其他客户端，服务命令为 npx -y prelude-context serve --root /path/to/project：

{
  "mcpServers": {
    "prelude-context": {
      "command": "npx",
      "args": ["-y", "prelude-context", "serve", "--root", "/path/to/project"]
    }
  }
}

prelude mcp-config --client claude-code | cursor | codex | claude-desktop 会输出适用于你的设备和客户端的准确配置片段。读取工具已标注为只读，因此支持工具注释的客户端可以直接运行，无需询问。

工具	Agent 可获取的内容
prelude_compact	按令牌预算生成的概览（默认约 800 个令牌），包含 [map] 行
prelude_locate	与任务描述最相关的文件，每个文件附带相关原因、导入者数量、覆盖测试、适用决策和备注
prelude_map	枢纽和模块、某个模块的详细信息，或某个文件的导出内容和导入者
prelude_query	按主题、目录范围或类型筛选的上下文
prelude_record_decision	将一项决策追加到 decisions.json，供后续会话沿用
prelude_annotate_module	更正模块用途或在 map.json 中添加备注；更新时绝不会覆盖
prelude_status	哪些上下文文件已存在

资源：prelude://context/full、prelude://context/compact、prelude://context/map，以及用于单个文件的 prelude://context/{type}。

机器上的每个项目

每个代码库只需注册一次，在 Agent 框架中只需注册一次 Prelude，这样每个会话都能查看你的所有项目：每个项目的用途、彼此之间的关系，以及项目内部的查找位置。

# once per repo
cd ~/code/backend  && prelude init && prelude workspace add .
cd ~/code/frontend && prelude init && prelude workspace add .

# once per machine
prelude mcp-config --workspace --client claude-code
# prints:  claude mcp add --scope user prelude -- prelude serve --workspace

在工作区模式下，每个工具都接受可选的 project 参数，并会多出三个工具：

Agent 调用	返回内容
prelude_projects	每个项目对应一个信息块：用途、技术栈、入口点、API 范围、枢纽文件、相关项目
prelude_locate(query="billing checkout")	省略 project 时，会搜索所有项目
prelude_link_projects(from="frontend", to="backend", relation="consumes", contract="REST /api/v1, JWT bearer")	在 frontend 的 project.json 中记录项目关系
prelude_workspace_refresh	重建工作区索引

prelude workspace list | index | status | remove <name> 用于管理 ~/.prelude/ 中的注册表（可通过 PRELUDE_HOME 覆盖）。

在 CI 中确保内容准确

GitHub Action 有两种模式。Guard（check: "true"）运行 prelude diff --check；当已提交的 .context/ 与代码不一致时，作业会失败。Update（默认模式）运行 prelude update，并在 .context/ 有变更时创建拉取请求。两种模式搭配使用：用 Guard 检查拉取请求，在 main 上运行 Update。

# .github/workflows/prelude.yml
name: Prelude Context
on:
  pull_request:
  push:
    branches: [main]
    paths: [package.json, pyproject.toml, Cargo.toml, go.mod, "src/**"]

jobs:
  check:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: adjective-rob/prelude@v1
        with:
          check: "true"

  update:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v7
      - uses: adjective-rob/prelude@v1

输入参数（version、args、working-directory、check）请参阅 action.yml。

命令

命令	功能
prelude init	分析项目并写入 .context/
prelude update	重新分析并合并，同时保留手动编辑
prelude diff	显示 update 会进行哪些更改，但不写入
prelude history	显示近期更新所做的更改
prelude hook install	添加一个在发现偏差时会失败的 git 提交前钩子
prelude locate <query>	为某项任务排列相关文件，并列出每个文件的测试、导入方和决策
prelude compact	每个章节压缩为一行，用于提示词注入
prelude query	按主题、目录或类型筛选上下文
prelude export	导出为 Markdown、JSON、CLAUDE.md、AGENTS.md 或 .cursorrules
prelude annotate <module>	在映射中设置模块用途或备注
prelude decision <title>	记录一项架构决策
prelude validate	根据 JSON Schemas 检查 .context/ 文件
prelude workspace <action>	管理多项目注册表
prelude serve	运行 MCP 服务
prelude mcp-config	输出客户端的 MCP 配置
prelude watch	监控文件更改并记录工作会话
prelude share	将上下文复制到剪贴板，并提供预览

运行任何命令时，都可以使用 --help 查看其标志。

prelude init

prelude init
prelude init --from-claude-md              # seed from ./CLAUDE.md
prelude init --from-claude-md docs/AI.md   # or another file

使用 --from-claude-md 时，Prelude 会从 Markdown 中提取项目信息、技术栈、架构和约束，并与推断出的内容合并。

prelude update 和 prelude diff

prelude update              # smart merge; backs up the previous state first
prelude update --dry-run    # preview
prelude update --force      # overwrite everything except decisions and changelog

prelude diff                # drift, grouped by file
prelude diff --all          # also show preserved manual edits
prelude diff --format json  # { changed, count, changes }
prelude diff --check        # exit 1 on drift

prelude history             # what each recent update changed, newest first
prelude hook install        # pre-commit hook that runs diff --check
prelude hook uninstall

update 会在 .context/.prelude/history/ 中保留最近 10 次运行前的状态；history 会读取这些备份。hook install 会向仓库的提交前钩子添加一个带标记的代码块：如果现有钩子存在，则添加在 shebang 之后；如果使用 husky，则添加到 .husky/pre-commit。在未安装 prelude 的计算机上会跳过检查。

prelude locate <query...>

根据两类证据为每个文件评分：映射中的信息（导出项、路径、模块用途、架构职责，以及提及该文件的决策），以及对文件内容进行的查询词扫描；稀有词的权重更高。每条结果都会列出其入选原因，随后是 impact 行（有多少文件导入了该文件、哪些测试覆盖了该文件）、提及该文件的已记录 decisions，以及任何模块 notes。--format json 会返回相同的字段。

prelude locate billing checkout webhook
prelude locate mcp server tools --limit 3
prelude locate "query engine" --scope src/core --format json

标志	描述
--limit <n>	最多返回的文件数（默认值：8）
--scope <dir>	仅考虑此目录下的文件
--tests	包含测试文件（默认情况下，仅当查询提及测试时才包含）
--format <text|json>	输出格式（默认值：text）

没有匹配结果时，Prelude 会打印枢纽文件，供你作为起点。

prelude query <topic> [options]

prelude query "error handling"              # topic search across everything
prelude query --scope src/api/              # architecture + constraints for a directory
prelude query --type constraints            # just constraints
prelude query "prisma" --type decisions --format json
prelude query --type stack --max-tokens 500 # budget-capped output

标志	描述
<topic>	在所有上下文文件中搜索的关键词
--scope <path>	与某个目录相关的架构和约束
--type <type>	可选值：project、stack、architecture、constraints、decisions、map
--format <md|json>	输出格式（默认值：md）
--max-tokens <n>	截断输出，使其符合 token 预算

输出会写入 stdout，token 估算值会写入 stderr，因此可以顺畅地通过管道传递。必须至少提供 topic、scope 或 type 中的一项。

prelude export

prelude export                      # markdown, copied to the clipboard
prelude export --format claude-md   # CLAUDE.md
prelude export --format agents-md   # AGENTS.md
prelude export --format cursorrules # .cursorrules
prelude export --format json        # structured JSON

claude-md 和 agents-md 格式会包含一个 先阅读 列表，其中列出枢纽文件，并提供每个模块占一行的映射。

prelude annotate <module>

prelude annotate src/core --purpose "Inference, merge, query and export engine"
prelude annotate src/core --notes "Regex heuristics only, no AST"
prelude annotate src/core --clear-notes

prelude decision <title>

prelude decision "Use Drizzle ORM instead of Prisma"   # opens your editor for the rationale

根据 JSON Schema 验证每个 .context/ 文件；如果有任何文件验证失败，则以状态码 1 退出。

prelude workspace <action>

prelude workspace add . --alias backend   # register (requires .context/)
prelude workspace list
prelude workspace index                   # rebuild ~/.prelude/index.json
prelude workspace status
prelude workspace remove backend

格式

Prelude 是一个 CLI，也是一种格式。该格式在 spec.md 中定义，并为 schemas/ 中的每个文件提供了 JSON Schema。这些 Schema 随 npm 包一起发布，并允许添加额外属性，因此你可以添加自己的字段。

代码地图：map.json

每个模块及其简短用途、每个文件导出的内容、解析后的内部导入关系图，以及代码库中大多数代码所依赖的枢纽文件。结果是确定性的（数组已排序，不含时间戳），因此在 git 中可以清晰地查看差异。

{
  "stats": { "files": 47, "modules": 10, "edges": 116, "unresolvedImports": 0 },
  "modules": [
    {
      "path": "src/core",
      "purpose": "Core business logic",
      "fileCount": 12,
      "files": [{ "file": "src/core/merger.ts", "lang": "ts", "lines": 349, "exports": ["ContextMerger"] }],
      "dependsOn": ["src/schema", "src/utils"],
      "tests": ["tests/merge-preserve.test.ts"]
    }
  ],
  "hubs": [{ "file": "src/utils/fs.ts", "importedBy": 18, "rank": 1 }]
}

手动编辑

.context/ 文件是纯 JSON。可直接编辑：

{
  "$schema": "https://adjective.us/prelude/schemas/v1/constraints.schema.json",
  "version": "1.0.0",
  "mustUse": ["TypeScript strict mode", "Server Components by default"],
  "preferences": [
    {
      "category": "state-management",
      "preference": "Prefer URL state over client state",
      "rationale": "Improves sharability and reduces bugs"
    }
  ]
}

prelude update 会保留你编写的内容，只刷新推断出的内容。

外部上下文目录

将 PRELUDE_ROOT 设置为项目外的目录，即可在该目录中读取和写入上下文，适用于无法或不想提交 .context/ 的仓库。

语言支持

	技术栈和架构推断	代码地图（导出、导入、枢纽）
TypeScript / JavaScript	✅ package.json、monorepo、tsconfig	✅ 包括 tsconfig paths
Python	✅ pyproject.toml、requirements.txt	✅
Rust	✅ Cargo.toml	✅
Go	✅ go.mod	✅

格式本身与语言无关。为扫描器添加一种语言只需进行有限范围的修改；请参阅 CONTRIBUTING.md。

常见问题

会遵循 .gitignore 吗？ 会。它会读取根目录的 .gitignore。被忽略的文件和目录不会出现在代码地图和架构中。目前还不会读取嵌套的 .gitignore 文件。

我应该提交 .context/ 吗？ 应该。它是机器可读的项目文档。只需在 gitignore 中忽略 .context/*.session.json。

我应该多久运行一次 prelude update？ 添加依赖项或重组项目后运行即可。GitHub Action 会替你执行，守护模式会提醒你何时忘记运行。

如果推断有误怎么办？ 有时确实会出错，因为这是启发式推断。编辑 JSON 或使用 prelude annotate 即可。之后每次更新都会保留你的更正。如果这个问题是 Prelude 不应该出现的错误，请提交 issue。

它会把我的代码发送到其他地方吗？ 不会。推断、locate 和 MCP 服务都不会发起网络请求。

它适用于任何大模型吗？ 适用。输出是文本和 JSON。

路线图

• 为 locate 实现基于图权重的排序
• 端到端基准测试：衡量 Agent 完成任务所需的 token 和工具调用次数，并比较使用 Prelude 与不使用 Prelude 的情况
• 在代码地图中支持更多语言
• 从 Agent 使用情况中学习启发式规则

已发布的工作见变更日志。待处理事项记录在 issues。

贡献

欢迎贡献，尤其是针对真实项目布局修复推断、添加新的框架检测器，以及为代码地图添加新语言。CONTRIBUTING.md 中包含环境设置、约定，以及各项任务的分步指南。标记为 good first issue 的 issues 范围明确，适合新手参与。

许可证

MIT © Adjective。详见 LICENSE。