GitHub IssuesをAIの「外部記憶」にしたらコンテキスト消失問題が解決した

LLMの「コンテキスト消失」問題

AIと一緒に開発していると必ずぶつかる壁があります。それがコンテキスト消失です。

Claude Code で長いセッションを続けていると、ある時点を境に「あれ、前に何をやったっけ？」という状態になります。LLMのコンテキストウィンドウは有限（Claude Sonnetで約200K tokens）で、それを超えると古い情報は切り捨てられます。

特に複数日にまたがる作業・複数リポジトリの並行管理・チームでAIを共有する場合に致命的です。

解決策：GitHub Issuesを外部記憶として使う

発想は単純です。「AIが忘れるなら、忘れない場所に書いておけばいい」。

GitHubのIssueは：

• 永続的（削除しない限り消えない）
• 検索可能（タイトル・本文・ラベルで絞り込める）
• 構造化できる（ラベル・マイルストーン・担当者）
• AIが読める（gh コマンドで取得できる）

実際の運用パターン

パターン1: 作業コンテキストをIssueに記録する

新しい機能開発を始めるとき、まずIssueを作ってそこに全ての「なぜ」「何を」「どのように」を書きます。

## 背景・目的
エージェントKIKIのヘルスチェック機能を強化する。
現状：5分おきにpingするだけ
目的：メモリ・CPU・レスポンスタイムも含む詳細監視

## 技術的判断
- WebSocketではなくHTTPポーリングを使う（理由：シンプルさ優先）
- タイムアウト3秒（理由：VMが重い時に5秒以上かかることがあった）

## 実装記録
2026-02-15: ベースコード追加 (commit: abc123)
2026-02-16: メモリ監視追加。node heapUsed を使用
2026-02-17: ⚠️ CPU計測でos.loadavg()が不安定。要調査

パターン2: エラーと解決策を記録する

ハマったエラーとその解決策をIssueコメントに残します。次のセッションでAIが同じエラーに当たったとき、Issueを参照させれば即解決できます。

# AIへの指示例
"Issue #23 の 'ディスク100%エラー' の解決策を参考に、
今回の /var/log 肥大化問題を解決してください"

パターン3: 引き継ぎIssue

セッション終了時に「引き継ぎIssue」を作成し、次のセッション開始時に読み込みます。

## 本日の作業サマリー（2026-02-20）
### 完了
- [x] KIKI ヘルスチェック強化 (#31)
- [x] Aira タスクキュー実装 (#28)

### 未完了・次回へ
- [ ] Riku のPDF取り込みが文字化けする (#35)
  → iconv-lite を試す予定

### 重要な発見
- Node.js の worker_threads が VM で不安定
  → 代替: child_process.fork() で解決済み

### 次のセッションでやること
1. Issue #35 のPDF文字化け対応
2. 全エージェントのsystemdログローテーション設定

実装：セッション開始プロトコル

CLAUDE.md に以下を書いておくと、毎セッション自動でコンテキストが復元されます。

# CLAUDE.md（抜粋）

## セッション開始プロトコル
1. 最新の引き継ぎIssueを取得して読む
   gh issue list --repo shintaku81/agent-team \
     --label "handover" --limit 1
2. 未処理のIssueを確認
   gh issue list --repo shintaku81/agent-team --state open
3. 把握できたら作業開始（ユーザーへの確認不要）

効果の計測

この方法を導入してから3週間の変化：

• 「どこまでやったっけ？」確認コスト: 15分 → 2分
• 同じエラーを繰り返す回数: 週5回 → ほぼゼロ
• 並行管理できるリポジトリ数: 2個 → 8個
• チームメンバー（AI）への引き継ぎ時間: 30分 → 5分

まとめ

GitHub Issuesを「外部記憶」として活用することで、LLMのコンテキスト制限という根本問題を実用的に解決できます。

重要なのは「AIにとって読みやすいIssue」を書く習慣を持つこと。人間用のIssueとAI用のIssueは少し書き方が違います。具体的なファイルパス・コマンド・エラーメッセージを含めることで、AIの実行精度が大幅に向上します。