session-management

セッション管理スキル

長時間にわたる開発セッションでコンテキストを維持し、休憩後もスムーズに再開できるようにします。

---

基本原則

自然な区切りでチェックポイントを作成し、すぐに再開できるようにします。

長時間の開発セッションでは、コンテキストが失われるおそれがあります。状態、決定事項、進捗をあらかじめ記録しておけば、休憩から戻った場合でも、コンテキストの上限に達した場合でも、どのセッションからでも中断した地点から正確に再開できます。

---

段階的な要約ルール

Tier 1：簡易更新（current-state.md のみ）

発動条件：小さなタスクや ToDo 項目を完了した後 対応：「Active Task」、「Progress」、「Next Steps」の各セクションを更新します 所要時間：約30秒

Tier 2：完全なチェックポイント（current-state.md + decisions.md）

発動条件：

• 機能や重要な変更を完了した後
• アーキテクチャやライブラリに関する決定を行った後
• 作業中にツールを約20回呼び出した後
• コードベースの別の領域に移るとき

対応：

1. current-state.md 全体を更新します
2. 決定事項があれば decisions.md に記録します
3. 変更中のファイルの表を更新します

Tier 3：セッションアーカイブ（archive/ + 完全なチェックポイント）

発動条件：

• 作業セッションの終了時
• 大きな機能やマイルストーンの完了時
• コンテキストが大きく切り替わる前
• コンテキストが重くなってきたとき（ツール呼び出しが約50回以上）

対応：

1. アーカイブ項目を作成します：archive/YYYY-MM-DD[-topic].md
2. 完全なチェックポイントを作成します
3. current-state.md から詳細なメモを削除します
4. 新しいパターンを導入した場合は code-landmarks.md を更新します

判断の目安

┌─────────────────────────────────────────────────────┐
│ After completing work, ask:                         │
├─────────────────────────────────────────────────────┤
│ Was a decision made?        → Log to decisions.md   │
│ Task took >10 tool calls?   → Full Checkpoint       │
│ Major feature complete?     → Archive               │
│ Ending session?             → Archive + Handoff     │
│ Otherwise                   → Quick Update          │
└─────────────────────────────────────────────────────┘

---

セッション状態の構成

_project_specs/session/ ディレクトリを作成します：

_project_specs/
└── session/
    ├── current-state.md      # Live session state (update frequently)
    ├── decisions.md          # Key decisions log (append-only)
    ├── code-landmarks.md     # Important code locations
    └── archive/              # Past session summaries
        └── 2025-01-15.md

---

現在の状態ファイル

_project_specs/session/current-state.md - 15〜20分ごと、または大きな進捗があった後に更新します。

# Current Session State

*Last updated: 2025-01-15 14:32*

## Active Task
[One sentence: what are we working on right now]

Example: Implementing user authentication flow with JWT tokens

## Current Status
- **Phase**: [exploring | planning | implementing | testing | debugging | refactoring]
- **Progress**: [X of Y steps complete, or percentage]
- **Blocking Issues**: [None, or describe blockers]

## Context Summary
[2-3 sentences summarizing the current state of work]

Example: Created auth middleware and login endpoint. JWT signing works.
Currently implementing token refresh logic. Need to add refresh token
rotation for security.

## Files Being Modified
| File | Status | Notes |
|------|--------|-------|
| src/auth/middleware.ts | Done | JWT verification |
| src/auth/refresh.ts | In Progress | Token rotation |
| src/auth/types.ts | Done | Token interfaces |

## Next Steps
1. [ ] Complete refresh token rotation in refresh.ts
2. [ ] Add token blacklist for logout
3. [ ] Write integration tests for auth flow

## Key Context to Preserve
- Using RS256 algorithm (not HS256) per security requirements
- Refresh tokens stored in HttpOnly cookies
- Access tokens: 15 min, Refresh tokens: 7 days

## Resume Instructions
To continue this work:
1. Read src/auth/refresh.ts - currently at line 45
2. The rotateRefreshToken() function needs error handling
3. Check decisions.md for why we chose RS256 over HS256

---

決定ログ

_project_specs/session/decisions.md - アーキテクチャと実装に関する決定を追記していくログです。

# Decision Log

Track key decisions for future reference. Never delete entries.

---

## [2025-01-15] JWT Algorithm Choice

**Decision**: Use RS256 instead of HS256 for JWT signing

**Context**: Implementing authentication system

**Options Considered**:
1. HS256 (symmetric) - Simpler, single secret
2. RS256 (asymmetric) - Public/private key pair

**Choice**: RS256

**Reasoning**:
- Allows token verification without exposing signing key
- Better for microservices (services only need public key)
- Industry standard for production systems

**Trade-offs**:
- Slightly more complex key management
- Larger token size

**References**:
- src/auth/keys/ - Key storage
- docs/security.md - Security architecture

---

## [2025-01-14] Database Schema Approach

**Decision**: Use Drizzle ORM with PostgreSQL

**Context**: Setting up data layer

**Options Considered**:
1. Prisma - Popular, good DX
2. Drizzle - Type-safe, SQL-like
3. Raw SQL - Maximum control

**Choice**: Drizzle

**Reasoning**:
- Better TypeScript inference than Prisma
- More transparent SQL generation
- Lighter weight, faster cold starts

**References**:
- src/db/schema.ts - Schema definitions
- src/db/migrations/ - Migration files

---

コードの目印

_project_specs/session/code-landmarks.md - すぐに参照できるよう、重要なコードの場所を記録します。

# Code Landmarks

Quick reference to important parts of the codebase.

## Entry Points
| Location | Purpose |
|----------|---------|
| src/index.ts | Main application entry |
| src/api/routes.ts | API route definitions |
| src/workers/index.ts | Background job entry |

## Core Business Logic
| Location | Purpose |
|----------|---------|
| src/core/auth/ | Authentication system |
| src/core/billing/ | Payment processing |
| src/core/workflows/ | Main workflow engine |

## Configuration
| Location | Purpose |
|----------|---------|
| src/config/index.ts | Environment config |
| src/config/features.ts | Feature flags |
| drizzle.config.ts | Database config |

## Key Patterns
| Pattern | Example Location | Notes |
|---------|------------------|-------|
| Service Layer | src/services/user.ts | Business logic encapsulation |
| Repository | src/repos/user.ts | Data access abstraction |
| Middleware | src/middleware/auth.ts | Request processing |

## Testing
| Location | Purpose |
|----------|---------|
| tests/unit/ | Unit tests |
| tests/integration/ | API tests |
| tests/e2e/ | End-to-end tests |
| tests/fixtures/ | Test data |

## Gotchas & Non-Obvious Behavior
| Location | Issue | Notes |
|----------|-------|-------|
| src/utils/date.ts | Timezone handling | Always use UTC internally |
| src/api/middleware.ts:45 | Auth bypass | Skip auth for health checks |
| src/db/pool.ts | Connection limit | Max 10 connections in dev |

---

CLAUDE.md のセッションルール

次のセクションを CLAUDE.md に追加します：

## Session Management

**IMPORTANT**: Follow session-management.md skill. Update session state at natural breakpoints.

### After Every Task Completion
Ask yourself:
1. Was a decision made? → Log to `decisions.md`
2. Did this take >10 tool calls? → Full checkpoint to `current-state.md`
3. Is a major feature complete? → Create archive entry
4. Otherwise → Quick update to `current-state.md`

### Checkpoint Triggers
**Quick Update** (current-state.md):
- After any todo completion
- After small changes

**Full Checkpoint** (current-state.md + decisions.md):
- After significant changes
- After ~20 tool calls
- After any decision
- When switching focus areas

**Archive** (archive/ + full checkpoint):
- End of session
- Major feature complete
- Context feels heavy

### Session Start Protocol
When beginning work:
1. Read `_project_specs/session/current-state.md`
2. Check `_project_specs/todos/active.md`
3. Review recent `decisions.md` entries if needed
4. Continue from "Next Steps"

### Session End Protocol
Before ending or when context limit approaches:
1. Create archive: `_project_specs/session/archive/YYYY-MM-DD.md`
2. Update current-state.md with handoff format
3. Ensure next steps are specific and actionable

---

圧縮の戦略

圧縮するタイミング（Tier 3 アーカイブ）

発動条件	対応
ツール呼び出しが約50回以上	進捗を要約し、詳細なメモをアーカイブします
大きな機能の完了	機能の詳細をアーカイブし、ランドマークを更新します
コンテキストの切り替え	これまでのコンテキストを要約してアーカイブし、新たに開始します
セッションの終了	アーカイブを含む完全なセッション引き継ぎを行います

残す情報とアーカイブする情報

アクティブなコンテキストに残す情報：

• 現在のタスクと直近の次のステップ
• 状態を含む作業中のファイル一覧
• 作業を妨げている問題
• 現在の作業に影響する重要な決定事項

アーカイブ／要約する情報：

• うまくいかなかった調査経路
• 詳細なデバッグ記録（結論のみを残す）
• 詳細なエラーメッセージ（根本原因のみを残す）
• 調査メモ（推奨事項のみを残す）

圧縮テンプレート

圧縮時は、次の形式を使用します：

## Compressed Context - [Topic]

**Summary**: [1-2 sentences]

**Key Findings**:
- [Bullet points of important discoveries]

**Decisions Made**:
- [Reference to decisions.md entries]

**Relevant Code**:
- [File:line references]

**Archived Details**: [Link to archive file if created]

---

セッションアーカイブ

重要な作業の後、またはセッション終了時にアーカイブを作成します：

_project_specs/session/archive/YYYY-MM-DD[-topic].md

# Session Archive: [Date] - [Topic]

## Summary
[Paragraph summarizing what was accomplished]

## Tasks Completed
- [TODO-XXX] Description - Done
- [TODO-YYY] Description - Done

## Key Decisions
- [Reference decisions.md entries made this session]

## Code Changes
| File | Change Type | Description |
|------|-------------|-------------|
| src/auth/login.ts | Created | Login endpoint |
| src/auth/types.ts | Modified | Added RefreshToken type |

## Tests Added
- tests/auth/login.test.ts - Login flow tests
- tests/auth/refresh.test.ts - Token refresh tests

## Open Items Carried Forward
- [Anything not finished, now in active.md]

## Session Stats
- Duration: ~3 hours
- Tool calls: ~120
- Files modified: 8
- Tests added: 12

---

ToDo システムとの連携

ToDo をセッションにリンクする

進行中の ToDo でセッションのコンテキストを参照します：

## [TODO-042] Implement token refresh

**Status:** in-progress
**Session Context:** See current-state.md

### Progress Notes
- 2025-01-15: Started implementation, base structure done
- 2025-01-15: Added rotation logic, need error handling

ToDo の完了時に自動更新する

ToDo を完了したとき：

1. active.md で ToDo を完了済みにします
2. current-state.md の進捗を更新します
3. 行った決定事項を記録します
4. 新しいパターンを導入した場合は code-landmarks.md を更新します

---

クイックコマンド

プロジェクトのスクリプトまたはエイリアスに追加します：

# Show current session state
alias session-status="cat _project_specs/session/current-state.md"

# Quick edit session state
alias session-edit="$EDITOR _project_specs/session/current-state.md"

# View recent decisions
alias decisions="tail -100 _project_specs/session/decisions.md"

# Create session archive
session-archive() {
  cp _project_specs/session/current-state.md \
     "_project_specs/session/archive/$(date +%Y-%m-%d).md"
  echo "Archived to _project_specs/session/archive/$(date +%Y-%m-%d).md"
}

---

適用の仕組み

1. 入口としての CLAUDE.md

CLAUDE.md の Skills セクションで session-management.md を参照する必要があります。Claude は最初に CLAUDE.md を読み、そこからセッションルールに従います。

2. リマインダー付きのセッションファイルヘッダー

セッションファイルのヘッダーに、適用を促すリマインダーを含めます：

current-state.md のヘッダー：

3. セルフチェックの質問

タスクを完了した後、Claude は次の点を確認します：

□ Did I make a decision? → Log it
□ Did this take >10 tool calls? → Full checkpoint
□ Is a feature complete? → Archive
□ Am I ending/switching context? → Archive + handoff

4. セッション開始時の確認

セッションを開始するとき、Claude は次のことを行う必要があります。

1. current-state.md が存在するか確認し、存在する場合は読み込みます
2. 見つかった内容を「再開します：［前回の状態］」と報告します
3. 続行する前に、次のステップを確認します

5. 定期的なセルフ監査

およそ 20 回のツール呼び出しごとに、Claude は次の点を確認します。

• current-state.md は最新の状態ですか？
• 記録されていない決定事項はありますか？
• コンテキストが重くなっていませんか？

6. ユーザーのプロンプト

ユーザーは、次のように依頼してこれを徹底できます。

• 「セッションの状態を更新」→ チェックポイントを実行します
• 「現在の状態は？」→ Claude が読み込んで報告します
• 「セッションを終了」→ アーカイブと引き継ぎを実行します
• 「前回のセッションから再開」→ Claude が最初に状態ファイルを読み込みます

---

アンチパターン

• 状態を追跡しない - 何も把握できず、再開もできません
• 状態の記述が冗長すぎる - 小説ではなく、ざっと確認できる内容にします
• 古い状態ファイル - 定期的に更新しないと役に立たなくなります
• 決定事項の記録漏れ - 後の自分は、その理由を思い出せません
• コードの目印がない - コードベースを再発見するのに時間がかかります
• アーカイブしない - セッションファイルが散らかります
• 圧縮の兆候を無視する - コンテキストの過負荷によってパフォーマンスが低下します
• 決定後のチェックポイントを省略する - 重要なコンテキストが失われます
• セッション終了時に引き継ぎをしない - 次のセッションが何も把握できない状態で始まります

---

クイックリファレンス

チェックポイントの判断フロー

Task completed?
    │
    ├── Decision made? ──────────────────→ Log to decisions.md
    │
    ├── >10 tool calls OR significant? ──→ Full Checkpoint
    │
    ├── Major feature done? ─────────────→ Archive
    │
    └── Otherwise ───────────────────────→ Quick Update

ファイル一覧

ファイル	更新頻度	目的
current-state.md	タスクごと	現在の状態、次のステップ
decisions.md	決定時	アーキテクチャ上の選択
code-landmarks.md	パターン変更時	コードのナビゲーション
archive/*.md	セッション／機能の終了時	履歴記録