Claudeに「過去」を与える 〜3年分のプロジェクト履歴をAIの判断材料にする〜

はじめに

こんにちは、くりメガネです。株式会社センシンロボティクスでロボット運用支援ツールの開発とスクラムマスターを担当しているソフトウェアエンジニアです。

この記事は、Claude Codeを使ってコードを書くエンジニアはもちろん、仕様ドラフトの作成やQAのテスト設計、新規参画者のキャッチアップといった、職種をまたいだ知識管理の課題を抱えるチームに向けて書いています。

特に次のような状態にある組織には、この仕組みが効きます。

• 設計判断の背景をADRなどに残す習慣がない、あるいは定着しないまま途切れた
• 過去の情報がJira・Slack・Confluenceに散らばりすぎて、検索してもたどり着けない

「AIにコンテキストを渡さないと仕事が進まない」という課題を高い温度感で抱えている組織なら、この記事の仕組みはそのまま適用できます。

何が問題か

この記事がやりたいのは、「過去の文脈をClaudeの判断材料として渡す」ことです。目指しているのは、いつでも・誰が使っても、Claudeが同じ質で仕事を進められる状態です。ですが、いまのClaudeには知らないことがたくさんあります。

• 変更の背景や設計変更の意図を知らない
• 顧客の要求を知らない
• 過去の失敗を知らない

しかも、こうした過去の文脈には2つの壁があります。

• 量が大きい：数年分の履歴はそのままAIに渡せる量をはるかに超える
• 散らばっている：同じ経緯の情報が複数のツールに分かれて残り一箇所にまとまっていない

過去は日々増え続けるので、一度きりの手渡しでは追いつきません。この壁をどう越えるかが、この記事のテーマです。

Claudeは「今」しか知らない

Claude Codeにコードを書かせると、目の前のリポジトリの「今」はよく読んでくれます。ですが、そのプロダクトが長年かけて積み上げてきた「過去」は、何ひとつ知りません。過去に起きた本番障害、レビューで何度も指摘されたアンチパターン、顧客から届いた問い合わせ、「この仕様はこういう経緯でこうなっている」という意思決定。そうした文脈です。

これはAIに限った話ではありません。新しくチームに入ったメンバーも、最初は同じように「過去ゼロ」からのスタートです。過去の文脈はJira・Slack・Confluence・GitHubに加え、会議の議事録(Geminiの自動メモ)やエラー監視(Sentry)にまで散らばっていて、検索してもたどり着けず、結局「その場にいた人しか知らない」暗黙知になっていきます。

この記事で紹介するのは、その 過去をClaudeに与える仕組み です。過去を集め、使える知識に変え、仕様・レビュー・QAに供給し、そこで生まれた新しい事例をまた集め直す。この一連の流れを、実際に運用しているところまで含めて書きます。

目指しているのは、特定の人の頭の中にしかない暗黙知を、AIがいつでも参照できる形に変え、チームの共有資産にすることです。

何が変わったか：過去を与えると起きること

仕組みの説明より先に、過去を与えると開発の現場が具体的にどう変わるかを並べます。

• 仕様ドラフトが過去の障害を自動で織り込む：新しい仕様書をClaudeに下書きさせると、関連する過去の不具合・障害・問い合わせを検索して「この観点は過去に同種の問題が起きているので異常系として書いておくべき」という項目を最初から埋めて出してくれる

• プルリクエストレビューが過去の指摘パターンを自動で適用する：繰り返し出たアンチパターンを1行ずつ蓄積したチェックリストをClaudeが参照して同じ轍を踏むのを防ぎ、新しく出た再発性のある指摘はその場で1行追記されて次から自動で効く

• QAのテスト観点が開発と同じ過去事例を見て決まる：テスト観点抽出スキルが開発の仕様ドラフトと同じ過去事例カタログを参照するので「過去のインシデントの再発防止観点」が開発とQAでバラバラにならず一本化される

• 新規参画者のキャッチアップが速くなる：用語集・ドメイン知識・関係者・全体像といった引き継ぎドキュメント一式が自動で維持されConfluenceにも同期されるので「まず何を読めばいいか」が常に最新の状態で置いてある

ポイントは、これらがスキルを作って終わりではなく、開発とQAの両方で実際に日々使われていることです。作った本人しか使わないツールは資産になりません。

全体像：過去を回す「知識の循環」

仕組み全体は、次の一周でできています。

• 収集：散らばった過去データをトークンを溢れさせずに集める
• 蒸留：生データを「使える知識」つまり引き継ぎ資料・インシデント事例集・チェックリストに変える
• 活用：その知識を仕様・レビュー・QAに効かせる

大事なのは最後の矢印です。活用の中で生まれた新しい障害やレビュー指摘は、そのままJiraやSlackといった記録に残ります。それを次の収集が拾い、また知識へと変えていく。特別な「還元ステップ」を用意しなくても、日々の記録がそのまま次の入力になる、という循環です。

なお、収集の仕組み自体は各自の手元のマシン(LaunchAgent＋ローカルキャッシュ)で動くため、収集結果は人によって異なります。チームで共有されるのは、蒸留後の引き継ぎ資料・チェックリスト・インシデント事例集です。「いつでも・誰が使っても同じ質」とは、この蒸留された知識をチームの共有の場(Confluence)に同期し、全員が同じ土台で判断できる状態を指しています。

以下、収集・蒸留・活用の順に見ていきます。

収集：過去を「安全に」集める

巨大なデータを、そのままClaudeに渡さない

過去データの収集で最初にぶつかる壁は、データがとにかく巨大なことです。Slackチャンネルの数か月分、Jiraの検索結果、Confluenceページの本文、会議の議事録、Sentryのエラーイベント。これらをMCP(Claudeと外部サービスをつなぐ仕組み)で取得し、Claudeが一度に扱えるコンテキスト(AIの作業メモリ)にそのまま流し込むと、あっという間に溢れます。要約のやり直しが始まり、トークンだけが溶けていきます。

そこで、共有データアクセス層を1枚かませています。役割はシンプルで、

1. MCPから巨大なデータを受け取り、
2. それをローカルのキャッシュに ファイルとして書き出し、
3. ディスク上で grep や範囲の切り出しで 必要な部分だけ選別し、
4. 呼び出し側には 「どのファイルにあるか」という参照と、小さな抜粋だけを返す

この層の存在理由そのものが「巨大な生データを、呼び出し側のコンテキストに絶対に戻さないこと」です。

生データはあくまでローカルキャッシュにだけ残し、返す情報の中では顧客名などを一般化したIDに置き換えます。「重い生データはディスクへ、コンテキストには軽い参照だけ」。この原則が、以降のすべての土台になります。

なお、生データが置かれるのは作業している自分の手元のマシンだけで、これは自分が読むための一時的な控えです。チームで共有したり社外に公開したりする成果物は、後述のとおり顧客名などを一般化し、秘匿情報の検査を通したうえで切り出すので、生データそのものが手元の外へ出ることはありません。

キャッシュはたとえばこんな構成です。生データ本体はここに置き、呼び出し側には「どのファイルのどこか」という参照だけを渡します。

.project-cache/
├── jira/            … 取得済みチケット
├── slack/           … チャンネル×期間ごとの要約
├── confluence/      … ページ本文
├── github/          … プルリクエスト・レビュー
├── calendar-gemini/ … 会議の議事録(カレンダー連携)
├── sentry/          … エラー・障害イベント
└── manifest.json    … どのファイルが最新かの索引

重い読み込みをサブエージェントに任せたときも、親(呼び出し元)が受け取るのはこの1行だけです。

{ "wrote": 128, "path": ".project-cache/pr/2024-h2.md" }

収集は2系統

収集は性質の違う2系統に分けています。

• 直近データの鮮度維持：数日から数週間の直近ぶんを平日に自動で温めておく（日々の作業で参照するのはこちら）
• 過去3年分の一括バックフィル：プロダクト誕生からの全履歴を後述の仕組みでじわじわ埋める

このようにして私が担当したプロダクトの過去3年分という膨大な量のデータを処理できました。次はこの掘り起こしをどうやって無人でやり切ったかの話です。

無人で3年分を集める：定時起動の工夫

過去3年分の収集を「1回の実行」でやろうとすると、必ずコンテキストが尽きて失敗します。実際、試しに全期間を一括処理させたときは、何セッション使ってもキャッシュが1つもできませんでした。

そこで発想を変えて、短いセッションを、何度も、無人で回す形にしました。鍵はmacOSの定時起動(LaunchAgent)です。

30分ごとに自分で起き上がる

設定はこれだけです(要点のみ抜粋)。

<key>StartCalendarInterval</key>
<array>
    <dict><key>Minute</key><integer>0</integer></dict>
    <dict><key>Minute</key><integer>30</integer></dict>
</array>
<key>RunAtLoad</key>
<false/>

Minute を0と30の2つ登録することで、毎時00分・30分に起動します。起動されるのは薄いシェルスクリプトで、やることは次の2つです。

• /tmp にPIDのロックファイルを置き前のセッションがまだ生きていればスキップする(多重起動防止)
• Claude Codeを headless(--print) で1セッションだけ起動する

claude --print --permission-mode auto "/historical-data-collection"

--print で対話なしのワンショット実行、--permission-mode auto で確認を求めず進みます。ログイン中のClaudeで動くので、この用途のために特別な準備は要りません。

1セッションで全部やらない

この収集スキルの本体は、1セッションで全期間を処理しようとしません。やるのは「半年ぶんのウィンドウを1回だけ進める」ことです。進捗を状態ファイルに書き出し、セッションを終えます。

次のセッションは、また30分後に自動で起こされます。起きたClaudeは状態ファイルを読んで「前回どこまでやったか」を把握し、続きの半年ぶんを進める。これを延々と繰り返すだけです。

進捗ファイルの中身は、たとえばこうなっています。次に起きたセッションは、これを読んで続きの半年ぶんから再開します。

{
  "completed_windows": ["2023-01..2023-06", "2023-07..2023-12"],
  "current_window": "2024-01..2024-06",
  "current_step": "slack",
  "updated_at": "YYYY-MM-DDThh:mm:ss+09:00"
}

30分の間隔には意味があります。トークンの利用枠は一定時間で回復するので、「使い切る前に休む、回復した頃にまた起きる」というリズムを作っているわけです。

結果として、PCの前に一度も座らなくても、3年分のデータが少しずつ勝手に埋まっていきました。帰ってきたらキャッシュができている、という体験です。次の自分を起こす役目をOSに任せてしまえる、というのが個人的に気に入っている点です。

大量の履歴を、限られたコンテキストで扱う

「無人で回る」を成立させているのは、"データが巨大でコンテキストに載りきらない" という課題への解決策です。ひとつずつは小さな工夫ですが、組み合わせることで、大規模な履歴を1台のPCで扱えるようになります。

• 参照だけ渡す：生データはキャッシュに置きコンテキストには「どこにあるか」と小さな抜粋だけを渡す(前述の共有データアクセス層)

• 半年分ずつ処理して毎回終わる：全期間の一括処理はコンテキスト予算の下で必ず破綻するので半年ウィンドウに区切り、各セッションにトークン予算と外部呼び出し回数・同時に読むSlackチャンネル数の上限を設け、上限に近づいたら進捗を記録して安全に降り次の起動が続きを拾う

• 重い読み込みは別プロセスに隔離する：大量のプルリクエストコメントのような「読むと重いが要るのは要約だけ」のデータはサブエージェントに任せ、親が受け取るのは「何件書いたか」の1行だけなので親のコンテキストを汚さず1セッションで数百件規模を処理できる

• チェックリストは必要な行だけ読む：1行=1項目の形式にしておき使うときは全文を読まずキーワードで grep して一致した行だけ読む

• 軽い処理は軽いモデルで：「作業ログをセッション単位で要約する」ような定型処理には軽量モデル(Haiku)を使いMCPを一切ロードしない設定で呼ぶ（仕事に見合ったコストしかかけないを仕組みで守る）

• 枠が尽きる前に中断・再開する：利用枠のリセット時刻を検知したら潔く終了しリセット後の次の起動で再開する（無理に続けて中途半端に失敗するよりきれいに降りて次に任せる方が結果的に速い）

蒸留：過去を「使える知識」に変える

集めた生データは、そのままでは使えません。引き継ぎ資料・インシデント事例集・チェックリストという3つの形に変えます。

• 引き継ぎ資料：用語集・ドメイン知識・関係者・全体像などをまとめ「何も知らない新規参画者がいつでもキャッチアップできる」状態を維持する。生成物はローカルの作業コピーとして持ち、チームが読む共有の置き場であるConfluenceへ実行のたびに同期するので、いつ誰が見ても最新版がConfluenceにそろっている

• インシデント事例集：本番障害・バグ・頻発エラー・問い合わせを決まった書式の構造化エントリに落として蓄積する（公開・共有の前には秘匿情報の検査を通す）

• チェックリスト：インシデント事例集から「この観点は過去に同種の障害・トラブルが起きている」という確認項目を1行ずつ生成し、各行の末尾に根拠の事例IDを付けるので「なぜこの観点が要るのか」を後からたどれる

生成されるファイルの例

インシデント事例集は、1件ずつ決まった書式で積み上がります。

### QS-YYYYMMDD-001 一覧画面がタイムアウトする
- 種別: 本番障害
- 事象: データ件数が増えると一覧APIが応答しなくなる
- 原因: ページング未実装で全件を取得していた
- 再発防止観点: 一覧・検索APIは必ずページングと最大件数を設ける
- 関連: プルリクエスト #1234 / https://example.com/incident/001

チェックリストは、その事例集から1行＝1観点で生成します。末尾に根拠の事例IDが付くので、なぜその観点が要るのかを後からたどれます。

[PERF-001] 一覧・検索APIはページングと最大件数を設けているか（Basis: QS-YYYYMMDD-001）
[SEC-001]  入力値はサーバ側でも検証しているか（Basis: QS-YYYYMMDD-014）

活用：仕様・レビュー・QA に効かせる

蒸留した知識は、日々の3つの場面で効きます。

• 仕様ドラフト生成：新しい仕様書を下書きするときテーマに関連する過去事例をキーワード検索でシードしチェックリストを grep して異常系・エッジケースの観点を埋める

• プルリクエストレビュー支援：過去のアンチパターンをまとめたチェックリストを適用して同じ指摘を先回りし、新しく出た再発性のある指摘はその場で1行追記してチェックリストを育てる

開発とQAが「同じ過去」を見る

個人的に一番効いていると感じるのが、QAとの接続です。

テスト観点抽出スキルは、対象チケットを起点に仕様ページやデザインを集めてテスト観点を自動生成します。このスキルが、開発側の仕様ドラフトと同じチェックリスト(過去事例カタログ)を参照するように繋がっています。

出力される観点表のカラムも揃えてあるので、「過去のインシデントの再発防止観点」が、開発の仕様書とQAのテスト観点で分裂しません。開発が「ここは過去に同種の障害が起きたので気をつける」と書いた観点を、QAが同じ根拠から拾ってテストに落とす。過去という共通言語で、職種をまたいで整合が取れる状態です。

そしてこれは「作っただけ」ではありません。開発とQAが同じカタログを日々使い、育て合っている。チームの資産として回っていることが、この仕組みの一番の価値だと思っています。

おわりに：過去が、次の判断を助ける

集めた過去を引き継ぎ資料・インシデント事例集・チェックリストに変え、仕様・レビュー・QAで使い、そこで生まれた新しい事例がまた記録として積もっていく。この流れが回り始めると、新規参画者もAIも、同じ過去の文脈の上で仕事を進められるようになります。「その場にいた人しか知らない」だった暗黙知が、いつでも参照できる知識に変わっていきます。

そして、この仕組みにはまだ足りないものがあります。過去を与えても、Claudeはまだ「時間の感覚」、つまりスプリントの締切や、1日の残り時間、「今日はここまで終わっていないと間に合わない」というペース感を持っていません。次回作 「Claudeに『時間』を与える」 では、スプリントから週、日、そして今この瞬間へと計画を分解し、AIに時間を守らせる仕組みを書きます。