Afterpaths

Afterpaths

セッションのたびに、自動で賢くなります。

うまくいったことからルールを抽出します。うまくいかなかったことを記録します。スタックに最適なモデルを見つけます。

Claude Code、Cursor、Codex を使っていても、スタックで実際に最もよく機能するモデルはどれでしょうか？ どのアプローチが突破口につながり、どのアプローチが高くつく行き止まりにつながるのでしょうか？ エージェントが同じミスを繰り返さないようにするには、どうすればよいでしょうか？

Afterpaths では、すべての AI コーディングツールを一元的に確認できます。何がうまくいっているかを比較し、発見をルールとして記録し、エージェントチームが高くつく寄り道をしないよう導きます。

表示されている内容：

1. ap audit — セッション、使用モデル、ルールの状態を一覧表示します
2. ap show 5 --raw — セッションの生のトランスクリプト（扱いにくい JSONL データを読みやすく表示します）
3. ap show 5 — LLM が生成する要約。発見、行き止まり、決定事項を抽出します
4. head .claude/rules/gotchas.md — 自動抽出され、Claude の次のセッションですぐに使えるルールです

問題点

複数のエージェントを管理していると、重要なコンテキストを保持し、セッションから学ぶことが困難です。

• 同じミスの繰り返し — エージェントが同じ落とし穴にはまります。3 週間後、また同じ行き止まりにぶつかり、トークンを無駄にします。
• ツール横断の可視性がない — コードベースでは Opus のほうが Sonnet より本当に優れているのでしょうか？ Cursor は Claude Code より優れた結果を出しているのでしょうか？ 何も分からず、推測するしかありません。
• ルール作成が面倒 — 高くつく寄り道のあとに、いちばんやりたくないのは CLAUDE.md のルールを書くことです。そのため、結局書きません。そして知識は消えてしまいます。
• セッションが消える — セッションの内容は分かりにくい形式で記録され、取り出すのも困難です。しかも、多くの場合 30 日後に自動削除されます。画期的なアーキテクチャ上の決定も、コンテキストとともに失われます。

Afterpaths はツールをまたいでセッションを記録し、うまくいっていることを明らかにして、ルールを自動生成します。これにより、エージェントはセッションのたびに学習し、セッションの豊富なコンテキストもすべて保持できます。

仕組み

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 件のセッションが欠落する原因となったバグを、同じミスを防ぐルールに変えました。

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 を使う場合
落とし穴を見つけても、記録し忘れる	ap summarize がコンテキストごと記録します
3 週間後に同じ問題に遭遇する	.claude/rules/ のルールが再発を防ぎます
何がうまくいっているか分からない	ap stats でトークン、セッション、エラー率を確認できます
IDE ごとにセッションが分散する	ap log で Claude と Cursor の情報を一元的に確認できます
ツールごとに学びが分断される	ルールを .claude/rules/ と .cursor/rules/ に同期します

抽出される内容

カテゴリ	抽出される内容	例
行き止まり	失敗したアプローチ	「Y のため、X は使わない」
決定事項	アーキテクチャ上の選択	「…のため、Postgres ではなく Redis を選びました」
落とし穴	直感的には分かりにくい注意点	「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 サーバーが含まれています。エージェントが CLI を見つけることに頼る代わりに、MCP サーバーによって、セッション検索、要約、ルールをネイティブツールとして利用できます。

# 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	抽出されたルールを取得します（行き止まり、決定事項など）

設定が完了すると、エージェントに「これについて前にも対応したことはありますか？」や「行き止まりになった方法は何でしたか？」と尋ねて、セッション履歴から回答を得られます。

プライバシー

• すべてローカル — 要約とルールはプロジェクト内に保存されます
• 自分の API キー — 自分の Anthropic／OpenAI キーを使用します
• 読み取り専用 — ソースコードを変更することはありません
• Gitignore 対象 — .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 セッションへの対応
• セッション分析（トークン、エラー、日別の傾向）
• LLM による要約
• ルールの自動抽出
• 複数の出力先へのエクスポート（Claude、Cursor）
• Codex CLI への対応
• セッション横断検索（ap search）
• JSON 出力（--json フラグ）
• エージェント連携用 MCP サーバー
• セッション横断のセマンティック検索
• ベンチマークと生産性に関する分析

ライセンス

MIT

---

AI コーディングエージェントを管理しましょう。うまくいく方法を学び、同じ失敗を繰り返さないようにしましょう。