Afterpaths

Afterpaths

每次会话后自动变得更智能。

从有效的做法中提取规则。记录无效的做法。为你的技术栈找到最佳模型。

你正在使用 Claude Code、Cursor 和 Codex，但哪个模型最适合你的技术栈？哪些方法能带来突破，哪些只会造成昂贵的弯路？怎样才能避免你的 Agent 一再犯同样的错误？

Afterpaths 为你的所有 AI 编码工具提供统一视图：对比有效的方法，将发现记录为规则，并引导你的 Agent 团队避开代价高昂的弯路。

你看到的内容：

1. ap audit — 会话、所用模型和规则状态概览
2. ap show 5 --raw — 原始会话记录（将杂乱的 JSONL 数据整理为易读内容）
3. ap show 5 — 由大模型生成的摘要，提取发现、弯路和决策
4. head .claude/rules/gotchas.md — 自动提取的规则，已准备好供 Claude 在下次会话中使用

问题所在

你要管理多个 Agent——保留关键上下文并从会话中学习非常困难：

• 重复犯错 — 你的 Agent 一再遇到相同的陷阱。三周后，又走同一条弯路，又浪费同样的 Token。
• 无法跨工具查看 — Opus 真的比 Sonnet 更适合你的代码库吗？Cursor 的表现是否优于 Claude Code？你只能靠猜。
• 编写规则很麻烦 — 走了一段代价高昂的弯路后，你最不想做的就是编写一条 CLAUDE.md 规则。所以你没有写。知识就此消失。
• 会话转瞬即逝 — 会话内容被隐晦地记录下来，很难提取，而且往往会在 30 天后自动删除。那个突破性的架构决策呢？上下文已经不复存在。

Afterpaths 会跨工具捕获会话，展示有效的方法，并自动生成规则——让你的 Agent 从每次会话中学习，同时保留丰富的会话上下文。

工作原理

Your Sessions                      Afterpaths
───────────────                    ────────────────────────────────────

Claude Code  ──► ap log      ──► Browse sessions across IDEs
Cursor           ap stats    ──► Analytics: tokens, activity, errors
Codex            ap summarize──► Session summaries (what happened)
                 ap rules    ──► Rule files (what to remember)
                 ap search   ──► Find past discussions & discoveries
                                    │
                                    ▼
                           .claude/rules/ · .cursor/rules/
                                    │
                                    ▼
                           Your next session is smarter

快速开始

pip install afterpaths

# Navigate to your project (rules are project-specific)
cd ~/code/your-project

# Run audit to see what you have
ap audit

审计会显示你在所有工具中的会话、模型表现，以及是否已设置规则。无需 API 密钥。

接下来，建议按以下流程操作：

# 1. Browse sessions and find significant work
ap log

# 2. Summarize important sessions (requires API key)
export ANTHROPIC_API_KEY="sk-ant-..."
ap summarize 1

# 3. Extract rules from summaries → .claude/rules/
ap rules

# 4. Search across past sessions
ap search "database schema"
ap search "auth" --deep    # also search raw transcripts

# 5. Track ongoing performance
ap stats
ap stats --daily

提示：ap 是 afterpaths 的简短别名。两者功能完全相同。

所有命令都支持 --json，可输出结构化数据（例如，ap log --json、ap show 1 --json、ap search "query" --json）。

完整命令参考和使用示例请参阅 docs/commands.md。

从会话到规则

真实示例：一个导致 76 个会话缺失的 Bug，最终变成了一条能防止同类错误的规则。

在构建 afterpaths 时，某个项目的会话没有显示出来。路径（姑且称为）/Users/Code/foo_bar 被解码成了 /Users/Code/foo/bar。经过调查，我们发现 Claude Code 使用有损路径编码——/ 和 _ 都会变成 -。

摘要记录了这一发现：

## Discoveries

- **Claude Code's path encoding is lossy**: Project paths in `~/.claude/projects/`
  are encoded by replacing `/` with `-`, but underscores are ALSO converted to
  hyphens. Three different paths encode identically:
  - `/Users/Code/foo_bar` → `-Users-Code-foo-bar`
  - `/Users/Code/foo-bar` → `-Users-Code-foo-bar`
  - `/Users/Code/foo/bar` → `-Users-Code-foo-bar`

ap rules 将其提取到 .claude/rules/gotchas.md 中：

- **Claude Code lossy path encoding**: Claude Code encodes project paths by
  replacing both `/` and `_` with `-`, making them indistinguishable when
  decoding. When decoding, try underscore variants alongside hyphen variants
  at each greedy step, preferring longer segments (single directories) over
  nested paths.
  _Source: 91b1ffbc_

下次 Claude 在此代码库中处理路径解码时，就已经了解这种有损编码，无需重新发现。

为什么选择 Afterpaths

不使用 Afterpaths	使用 Afterpaths
发现陷阱后，忘了记录	ap summarize 会连同完整上下文一起记录
三周后再次遇到同样的问题	.claude/rules/ 中的规则可防止问题重现
不清楚哪些方法有效	ap stats 显示 Token 数、会话数和错误率
会话散落在不同 IDE 中	ap log 统一展示 Claude + Cursor 的会话
各工具的经验彼此隔绝	规则同步到 .claude/rules/ 和 .cursor/rules/

提取内容

类别	捕获内容	示例
弯路	失败的方法	“不要使用 X，因为 Y”
决策	架构选择	“我们选择 Redis 而不是 Postgres，因为……”
注意事项	不易察觉的警告	“执行 Y 时要注意 X”
模式	有效的技术	“对于 X，使用模式 Y”

每条规则都包含源会话的引用，方便你追溯原始上下文。

支持的工具

工具	状态	位置
Claude Code	✅ 就绪	~/.claude/projects/*.jsonl
Cursor	⚠️ 部分支持	~/Library/Application Support/Cursor/User/workspaceStorage/
Codex CLI	✅ 就绪	~/.codex/

已知限制

**Cursor 会话：**适配器会读取几种已知的聊天／撰写格式 state.vscdb（包括 workbench.panel.aichat.view.aichat.chatdata、 composer.composerData 和 allComposers），但 Cursor 经常更改其存储 架构，因此即使存在 state.vscdb 文件，有些会话仍会返回 Entries: 0。 发生这种情况时，ap show <ref> --raw 和 afterpaths_show_session MCP 工具会发出警告，而不是默默返回空结果。原始文件不会被修改——如果你需要该会话，仍可直接使用 sqlite3 打开 state.vscdb。

工具来源追踪功能（ap show --artifacts、提交追踪、文件活动）仅适用于适配器能够读取条目的会话。

MCP 服务

Afterpaths 包含一个 MCP 服务，可将会话历史直接加入你的 Agent 工具列表。MCP 服务无需依赖 Agent 自行发现命令行，即可将会话搜索、摘要和规则作为原生工具提供。

# Install with MCP support
pip install afterpaths[mcp]

# Add to Claude Code
claude mcp add afterpaths -- afterpaths-mcp

# Or run directly
python -m afterpaths.mcp_server

提供的工具：

工具	描述
afterpaths_list_sessions	列出近期会话，以便恢复上下文
afterpaths_show_session	读取会话摘要和记录
afterpaths_show_artifacts	显示产物账本：记录文件的写入／编辑及其来源
afterpaths_summarize	为会话生成摘要
afterpaths_search	搜索过往会话（摘要搜索无命中时自动扩展到记录搜索）
afterpaths_get_rules	获取提取的规则（死胡同、决策等）

配置完成后，Agent 可以询问“我们以前遇到过这个吗？”或“有哪些走不通的路？”，并从你的会话历史中获取答案。

隐私

• 全部本地处理 — 摘要和规则保存在你的项目中
• 使用你的 API 密钥 — 使用你的 Anthropic/OpenAI 密钥
• 只读 — 绝不修改你的源代码
• 由 Git 忽略 — 默认排除 .afterpaths/

存储

your-project/
├── .afterpaths/           # Summaries (gitignored)
│   ├── summaries/
│   └── meta.json
├── .claude/
│   └── rules/             # Generated rules (commit these!)
│       ├── dead-ends.md
│       ├── gotchas.md
│       └── patterns.md
└── src/

规则文件中的手动编辑笔记

每个规则文件分为手动部分（在运行 ap rules 时保留）和自动部分（每次运行时重新生成）：

# Gotchas: Things to Watch For


_Add project-specific notes here — preserved across `ap rules` runs._



> Auto-generated by `afterpaths distill` | Updated: 2026-04-21 12:00
> Sources: 3 session(s)

## Rules

- **Some extracted rule**: ...
  _Source: abc12345_

将手动整理的规则或项目专属提醒放在 manual:start / manual:end 标记之间——它们会在每次运行 ap rules 时保留。这些标记之外（以及已识别的样板内容之外）的内容会触发安全检查并阻止运行。你可以传入 --force 强制覆盖，或将内容括在手动标记中以保留它。

如果你正在从早期版本升级，且规则文件中只有自动生成的内容，那么下次运行 ap rules 时会自动插入标记，并创建一个空的手动部分——无需采取任何操作。

路线图

• Claude Code 会话解析
• Cursor 会话支持
• 会话分析（令牌、错误、每日趋势）
• 大模型摘要
• 自动提取规则
• 多目标导出（Claude、Cursor）
• Codex CLI 支持
• 跨会话搜索（ap search）
• JSON 输出（--json 标志）
• 用于 Agent 集成的 MCP 服务
• 跨会话语义搜索
• 基准测试和效率洞察

许可证

MIT

---

管理你的 AI 编码 Agent。了解哪些方法有效。别再重复犯错。