session-chronicle

セッションクロニクル

Claude Code のセッションログを調査し、研究結果、ADR の決定、コードへの貢献について完全な出所情報を記録します。自動圧縮された複数のセッションにまたがる UUID の連鎖を追跡します。

重要な原則：レジストリーのエントリーは自己完結型である必要があります。コミット時にすべてのセッション UUID（メイン＋サブエージェント）を記録してください。将来のメンテナーが出所を理解するために、考古学的な調査を行う必要がないようにします。

S3 アーティファクト共有：チームでアクセスできるよう、アーティファクトを S3 にアップロードできます。S3 共有 ADRを参照してください。

自己進化型スキル：このスキルは使用を通じて改善されます。指示が誤っている、パラメーターにずれが生じた、または回避策が必要だった場合は、先送りせず、このファイルをすぐに修正してください。実際に再現できる問題がある場合にのみ更新してください。

このスキルを使用するタイミング

• ユーザーが「これは誰が作ったのか？」または「これはどこから来たのか？」と尋ねた場合
• ユーザーが完全なセッションコンテキストとともに「この調査結果を記録して」と依頼した場合
• ADR または研究結果の出所を追跡する必要がある場合
• Git コミットにセッション UUID の参照が必要な場合
• 自動圧縮された複数のセッションにまたがる編集を追跡する場合
• 研究セッションのレジストリーエントリーを作成する場合

---

ファイル所有権モデル

ディレクトリー	コミット対象？	用途
findings/registry.jsonl	YES	マスターインデックス（小さく、追記専用の NDJSON）
findings/sessions/<id>/iterations.jsonl	YES	イテレーション記録（小さく、追記専用）
outputs/research_sessions/<id>/	NO	研究アーティファクト（大容量、gitignore 対象）
tmp/	NO	S3 アップロード前の一時アーカイブ
S3 example-findings-bucket/sessions/<id>/	N/A	永続的なチーム共有アーカイブ

重要な原則：コミットするのは findings/ のみです。研究アーティファクトは gitignore 対象の outputs/ と S3 に保存します。

---

パート 0：事前確認

セッションストレージを検証し、プロジェクトのセッションを見つけ、必要なツール（jq、brotli、aws、op）を確認します。

スクリプトの全文：事前確認スクリプト

手順の概要：

1. セッションストレージを検証する - ~/.claude/projects/ が存在することを確認します
2. 現在のプロジェクトのセッションを見つける - CWD パスをエンコードし、メインおよびサブエージェントの .jsonl ファイルを列挙します
3. 必要なツールを検証する - jq、brotli、aws、op がインストールされていることを確認します

ステップ 4（S3 共有前に必須）：サニタイズ

Claude Code の生のセッション JSONL ファイルを共有するのは危険です。 スクリーンショット、環境変数のダンプ、シェルコマンドを通じてプロンプトに漏れ込んだ、実際の認証情報（AWS キー、GitHub PAT、Telegram ボットトークン、Tailscale API キー、1Password サービストークン）、内部ホスト名、Tailscale CGNAT IP、メールアドレス、その他のインフラストラクチャの秘密情報が含まれていることがよくあります。

S3 に圧縮してアップロードする前に、サニタイザーを実行してください。

SKILL_DIR="$(find $HOME/.claude/plugins/marketplaces/cc-skills -type d -name session-chronicle | head -1)"
"$SKILL_DIR/scripts/sanitize_sessions.py" \
  --input  /path/to/raw/claude-sessions-export-raw \
  --output /path/to/sanitized/claude-sessions-export \
  --report /path/to/redaction_report.txt

サニタイザーはフィールドを認識し（UUID、ツール使用 ID、為替レートの小数値を破壊しません。v1 では電話番号の正規表現が 92% の誤検出率で、構造上重要な識別子を損なっていました）、以下を対象とします。

• AWS／GitHub／OpenAI／Anthropic／Slack／Stripe／Google／JWT／Bearer／Authorization
• Tailscale API キー（tskey-*）、CGNAT IP（100.64–127.x.x）、tailnet DNS（*.ts.net）、tailnet 名
• 1Password サービストークン（ops_*）、op:// URL、op CLI のコンテキストに続く 32 文字のアイテム ID
• Cloudflare API トークン、Global API Key、CF_AppSession
• Doppler（dp.*）、Docker PAT（dckr_pat_*）、npm（npm_*）、Supabase（sbp_*）、SendGrid（SG.*）
• Telegram ボットトークン（<bot_id>:<secret> 形式）。環境変数のダンプに貼り付けられたトークンも検出します
• 認証情報が埋め込まれた ClickHouse URL
• .internal ホスト名、172.25.x.x のプライベート範囲
• PEM 秘密鍵ブロック（OPENSSH／RSA／EC／DSA／PGP／ED25519）
• JSON／YAML／環境変数形式の一般的な password=、api_key=、secret= 宣言
• メールアドレス
• 電話番号 — 区切り文字がある場合のみ（UUID／小数値の破壊を防止）

出力：パターンごとの件数を記載したマスキングレポート。パッケージ化する前にレビューし、重要なものが破壊されていないことを確認してください（健全性チェック：UUID の整合性が保たれていること）。

S3 アップロード手順：必ず raw → sanitize → zip → S3 → presigned URL の順にします。-raw/ を直接アップロードしてはいけません。

---

パート 1：AskUserQuestion フロー

フロー A：出所を追跡する対象の特定

スキルがトリガーされたら、まずユーザーが何の追跡を希望しているかを特定します。

AskUserQuestion:
  question: "What do you want to trace provenance for?"
  header: "Target"
  multiSelect: false
  options:
    - label: "Research finding/session"
      description: "Document a research session with full session context for reproducibility"
    - label: "Specific code/feature"
      description: "Trace who created a specific function, feature, or code block"
    - label: "Configuration/decision"
      description: "Trace when and why a configuration or architectural decision was made"
    - label: "Custom search"
      description: "Search session logs for specific keywords or patterns"

フロー B：GitHub の帰属情報の確認

重要：レジストリのすべてのエントリに、GitHub ユーザー名の帰属情報を含める必要があります。

AskUserQuestion:
  question: "Who should be attributed as the creator?"
  header: "Attribution"
  multiSelect: false
  options:
    - label: "Use git config user (Recommended)"
      description: "Attribute to $(git config user.name) / $(git config user.email)"
    - label: "Specify GitHub username"
      description: "I'll provide the GitHub username manually"
    - label: "Team attribution"
      description: "Multiple contributors - list all GitHub usernames"

フロー C：セッション範囲の確認

重要：デフォルトではすべてのセッションを対象にします。レジストリはそれだけで完結している必要があります。

AskUserQuestion:
  question: "Which sessions should be recorded in the registry?"
  header: "Sessions"
  multiSelect: false
  options:
    - label: "ALL sessions (main + subagent) (Recommended)"
      description: "Record every session file - complete provenance for future maintainers"
    - label: "Main sessions only"
      description: "Exclude agent-* subagent sessions (loses context)"
    - label: "Manual selection"
      description: "I'll specify which sessions to include"

重要：常に、記録対象はすべてのセッションにすることをデフォルトとします。サブエージェントのセッション（agent-*）には、Explore、Plan、専門エージェントからの重要なコンテキストが含まれています。これらを省略すると、後任の保守担当者は来歴を調査し直さなければなりません。

フロー D：セッションコンテキスト配列のプレビュー

書き込む前に、session_contexts 配列全体をユーザーに表示してから、確認を取ります。

AskUserQuestion:
  question: "Review the session_contexts array that will be recorded:"
  header: "Review"
  multiSelect: false
  options:
    - label: "Looks correct - proceed"
      description: "Write this to the registry"
    - label: "Add descriptions"
      description: "Let me add descriptions to some sessions"
    - label: "Filter some sessions"
      description: "Remove sessions that aren't relevant"
    - label: "Cancel"
      description: "Don't write to registry yet"

フロー E：出力形式の選択

AskUserQuestion:
  question: "What outputs should be generated?"
  header: "Outputs"
  multiSelect: true
  options:
    - label: "registry.jsonl entry (Recommended)"
      description: "Master index entry with ALL session UUIDs and GitHub attribution"
    - label: "iterations.jsonl entries"
      description: "Detailed iteration records in sessions/<id>/"
    - label: "Full session chain archive (.jsonl.br)"
      description: "Compress sessions with Brotli for archival"
    - label: "Markdown finding document"
      description: "findings/<name>.md with embedded provenance table"
    - label: "Git commit with provenance"
      description: "Structured commit message with session references"
    - label: "Upload to S3 for team sharing"
      description: "Upload artifacts to S3 with retrieval command in commit"

フロー F：既存の ADR へのリンク

AskUserQuestion:
  question: "Link this to an existing ADR or design spec?"
  header: "ADR Link"
  multiSelect: false
  options:
    - label: "No ADR link"
      description: "This is standalone or ADR doesn't exist yet"
    - label: "Specify ADR slug"
      description: "Link to an existing ADR (e.g., 2025-12-15-feature-name)"
    - label: "Create new ADR"
      description: "This finding warrants a new ADR"

---

パート 2：セッションの調査プロセス

すべてのセッションファイルをスキャンして session_contexts 配列を作成し、必要に応じて UUID チェーンを追跡します。

スクリプト全文：調査スクリプト

手順の概要：

1. プロジェクト全体のスキャン - すべてのメインセッションとサブエージェントセッションを、行数とタイムスタンプとともに列挙します
2. session_contexts 配列の作成 - すべてのセッションを含む配列を作成します（session_uuid、type、entries、description）
3. UUID チェーンの追跡（任意） - セッション間の親 UUID 参照をたどり、来歴を詳しく調査します

---

パート 3：レジストリのスキーマ

来歴の追跡には、2 つの NDJSON ファイルを使用します。

• findings/registry.jsonl - マスターインデックス。1 行につき、自己完結した JSON オブジェクトを 1 つ記録します
• findings/sessions/<id>/iterations.jsonl - セッションごとのイテレーション単位の追跡情報

スキーマ全文、例、フィールドリファレンス：レジストリスキーマリファレンス

必須フィールド（registry.jsonl）

フィールド	形式
id	YYYY-MM-DD-slug
type	research_session / finding / decision
created_at	ISO8601 タイムスタンプ
created_by.github_username	必須 GitHub ユーザー名
session_contexts	必須 すべてのセッション UUID の配列

---

パート 4：出力の生成

セッションのアーカイブには Brotli 圧縮を使用し、来歴情報を含む構造化された git コミットメッセージを作成します。

完全なスクリプトとテンプレート：出力の生成

概要：

• 圧縮 - 各セッションを Brotli-9 で outputs/research_sessions/<id>/*.jsonl.br に圧縮します（gitignore 対象）
• マニフェスト - target_id、件数、タイムスタンプを含む manifest.json を自動生成します
• コミットメッセージ - テンプレートには registry_id、帰属情報、セッション数、S3 取得コマンドが含まれます

---

パート 5：確認ワークフロー

書き込み前の最終確認

追記する前に、必ず書き込む内容をユーザーに表示します。

AskUserQuestion:
  question: "Ready to write to registry. Confirm the entry:"
  header: "Confirm"
  multiSelect: false
  options:
    - label: "Write to registry"
      description: "Append this entry to findings/registry.jsonl"
    - label: "Edit first"
      description: "Let me modify some fields before writing"
    - label: "Cancel"
      description: "Don't write anything"

この質問の前に、以下を表示します。

1. 完全な JSON エントリ（整形済み）
2. session_contexts エントリの件数
3. GitHub ユーザー名の帰属情報
4. 対象ファイルのパス

書き込み後の検証

書き込み後、以下を検証します。

# Validate NDJSON format
tail -1 findings/registry.jsonl | jq . > /dev/null && echo "Valid JSON"

# Show what was written
echo "Entry added:"
tail -1 findings/registry.jsonl | jq '.id, .created_by.github_username, (.session_contexts | length)'

---

パート 6：ワークフローの概要

1. PREFLIGHT
   ├── Verify session storage location
   ├── Find ALL sessions (main + subagent)
   └── Check required tools (jq, brotli)

2. ASK: TARGET TYPE
   └── AskUserQuestion: What to trace?

3. ASK: GITHUB ATTRIBUTION
   └── AskUserQuestion: Who created this?

4. ASK: SESSION SCOPE
   └── AskUserQuestion: Which sessions? (Default: ALL)

5. BUILD session_contexts ARRAY
   ├── Enumerate ALL main sessions
   ├── Enumerate ALL subagent sessions
   └── Collect metadata (entries, timestamps)

6. ASK: PREVIEW session_contexts
   └── AskUserQuestion: Review before writing

7. ASK: OUTPUT FORMAT
   └── AskUserQuestion: What to generate?

8. ASK: ADR LINK
   └── AskUserQuestion: Link to ADR?

9. GENERATE OUTPUTS
   ├── Build registry.jsonl entry (with iterations_path, iterations_count)
   ├── Build iterations.jsonl entries (if applicable)
   └── Prepare commit message

10. ASK: FINAL CONFIRMATION
    └── AskUserQuestion: Ready to write?

11. WRITE & VERIFY
    ├── Append to registry.jsonl
    ├── Append to sessions/<id>/iterations.jsonl
    └── Validate NDJSON format

12. SANITIZE (MANDATORY before any S3 share)
    ├── Run scripts/sanitize_sessions.py on the staging directory
    ├── Review redaction_report.txt (verify no structural destruction)
    └── Produce sanitized/ directory for downstream packaging

13. (OPTIONAL) S3 UPLOAD
    ├── Package sanitized/ directory (zip or brotli per-file)
    └── Upload compressed archives, generate presigned URL if sharing externally

---

成功基準

1. セッションの完全な列挙 - すべてのメインセッションとサブエージェントのセッションが記録されている
2. GitHub への帰属 - created_by.github_username が常に存在する
3. 自己完結型のレジストリ - 将来のメンテナーが履歴の調査を必要としない
4. ユーザー確認 - すべてのステップで AskUserQuestion による確認がある
5. 有効な NDJSON - すべてのエントリが jq の検証に合格する
6. 再現可能 - セッション UUID によってコンテキスト全体を取得できる

---

参考資料

• S3 共有 ADR
• S3 取得ガイド
• レジストリスキーマのリファレンス
• プリフライトスクリプト
• 履歴調査スクリプト
• 出力の生成
• NDJSON 仕様
• jq マニュアル
• Brotli 圧縮

---

トラブルシューティング

問題	原因	解決策
セッションストレージが見つからない	Claude Code が初期化されていない	まず Claude Code のセッションを開始してください
プロジェクトにセッションがない	パスのエンコードが間違っている	エンコード済みパスが ~/.claude/projects/ と一致するか確認してください
jq の解析エラー	JSONL の形式が不正	各行を個別に jq -c . で検証してください
brotli が見つからない	依存関係が不足している	brew install brotli でインストールしてください
S3 へのアップロードに失敗する	AWS 認証情報が不足している	AWS CLI を設定するか、1Password インジェクションを使用してください
UUID チェーンが途切れている	セッションが圧縮されている	続きがないか、関連セッションを確認してください
GitHub ユーザー名がない	帰属情報が設定されていない	レジストリエントリでは必ず github_username を必須にしてください
レジストリエントリが無効	必須フィールドが不足している	id、type、created_at、session_contexts が存在するか確認してください

実行後の振り返り

このスキルの実行後、終了する前に次の点を確認してください。

1. コマンドは成功しましたか？ — 成功していない場合は、失敗の原因となった手順またはエラーテーブルを修正します。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーターテーブルを更新して一致させます。
3. 回避策が必要でしたか？ — 別のフラグや追加手順など、その場で工夫する必要があった場合は、次回の実行で同じ回避策が不要になるよう、この SKILL.md を更新します。

問題が実際に発生し、再現可能な場合にのみ更新してください。推測で更新しないでください。