base

Base Skill - 汎用パターン

基本原則

複雑さは敵です。コードの各行はすべて負担になります。目標は、どのエンジニア（または AI）でも 1 回のセッションでシステム全体を理解できるほどシンプルなソフトウェアです。

---

シンプルさのルール

これらの制限は、作成または変更するすべてのファイルに適用されます。

関数レベル

• 関数あたり最大 20 行 — 長くなる場合は、直ちに分割してください
• 関数あたり最大 3 個のパラメーター — それ以上の場合は、オプションオブジェクトを使用するか、分割してください
• ネストは最大 2 階層 — 早期リターンを使ってフラット化するか、関数を抽出してください
• 単一責任 — 各関数は、厳密に 1 つの処理だけを行います
• コメントより説明的な名前 — 内容を説明するコメントが必要なら、名前を変更してください

ファイルレベル

• ファイルあたり最大 200 行 — 長くなる場合は、続ける前に責任ごとに分割してください
• ファイルあたり最大 10 個の関数 — 認知負荷を管理しやすく保ちます
• ファイルごとに 1 つのエクスポート対象 — ファイルには、主要な目的を 1 つだけ持たせてください

モジュールレベル

• ディレクトリのネストは最大 3 階層 — ネストよりフラットな構成が優れています
• 明確な境界 — 各モジュールには、単一の公開インターフェースがあります
• 循環依存は禁止 — 例外はありません

適用プロトコル

ファイルを完成させる前に必ず行うこと：

1. 総行数を数える — 200 行を超える場合は、作業を止めて分割する
2. 関数の数を数える — 10 個を超える場合は、作業を止めて分割する
3. 各関数の長さを確認する — 20 行を超える関数があれば、作業を止めて分割する
4. パラメーターの数を確認する — 3 個を超えるものがあれば、作業を止めてリファクタリングする

開発中に制限を超えた場合：

⚠️ FILE SIZE VIOLATION DETECTED

[filename] has [X] lines (limit: 200)

Splitting into:
- [filename-a].ts - [responsibility A]
- [filename-b].ts - [responsibility B]

リファクタリングを先延ばしにしないでください。 違反は「後で」ではなく、直ちに修正してください。

---

アーキテクチャパターン

関数型コア、命令型シェル

• ビジネスロジックには純粋関数を使います — 副作用がなく、決定的です
• 副作用は境界でのみ発生させます — API 呼び出し、データベース、ファイルシステムなどはエッジで扱います
• データを受け取り、データを返します — 関数はデータを変換し、状態を変更しません

継承よりコンポジション

• 継承は 1 階層を超えないようにします — インターフェースやコンポジションを優先します
• 小さく、組み合わせ可能なユーティリティを使います — シンプルな要素から複雑なものを構築します
• 依存性注入を使います — 依存関係は渡し、直接インポートしません

エラー処理

• 迅速かつ明確に失敗させます — エラーは直ちに表面化させます
• 暗黙の失敗は禁止です — すべてのエラーをログに記録するか、スローします
• 誤用できない API を設計します

---

テスト方針

• ビジネスロジックを 100% カバーする — 関数型コアを対象にします
• 境界には統合テストを用意する — API エンドポイント、データベース操作などを対象にします
• テストされていないコードはマージしない — テストに合格しない場合、CI がブロックします
• 実装ではなく振る舞いをテストする — リファクタリング後もテストが機能します
• 各テストを独立して実行する — 相互依存させません

---

アンチパターン（絶対に避けること）

• ❌ グローバル状態
• ❌ マジックナンバー／マジック文字列 — 名前付き定数を使用する
• ❌ 深いネスト — フラット化するか、抽出する
• ❌ 長いパラメーターリスト — オブジェクトを使用する
• ❌ 「何をしているか」を説明するコメント — コード自体で内容が分かるようにする
• ❌ デッドコード — 削除する。変更履歴は git に残る
• ❌ コピー＆ペーストによる重複 — 共通関数に抽出する
• ❌ 巨大なオブジェクト／ファイル — 責任ごとに分割する
• ❌ 循環依存
• ❌ 時期尚早な最適化
• ❌ 大規模な PR — 小さく、対象を絞った変更のみ
• ❌ リファクタリングと機能追加の混在 — コミットを分ける

---

ドキュメントの構成

すべてのプロジェクトで、コードのドキュメントとプロジェクト仕様を明確に分ける必要があります。

project/
├── docs/                      # Code documentation
│   ├── architecture.md        # System design decisions
│   ├── api.md                 # API reference (if applicable)
│   └── setup.md               # Development setup guide
├── _project_specs/            # Project specifications
│   ├── overview.md            # Project vision and goals
│   ├── features/              # Feature specifications
│   │   ├── feature-a.md
│   │   └── feature-b.md
│   ├── todos/                 # Atomic todos tracking
│   │   ├── active.md          # Current sprint/focus
│   │   ├── backlog.md         # Future work
│   │   └── completed.md       # Done items (for reference)
│   ├── session/               # Session state (see session-management.md)
│   │   ├── current-state.md   # Live session state
│   │   ├── decisions.md       # Key decisions log
│   │   ├── code-landmarks.md  # Important code locations
│   │   └── archive/           # Past session summaries
│   └── prompts/               # LLM prompt specifications (if AI-first)
└── CLAUDE.md                  # Claude instructions (references skills)

配置場所と内容

配置場所	内容
docs/	技術ドキュメント、API リファレンス、セットアップガイド
_project_specs/	ビジネスロジック、機能、要件、TODO
_project_specs/session/	セッション状態、決定事項、再開に必要なコンテキスト
CLAUDE.md	Claude 固有の指示とスキルの参照

---

アトミックな TODO

すべての作業を、検証基準とテスト基準を含むアトミックな TODO として追跡します。

TODO の形式（必須）

## [TODO-001] Short descriptive title

**Status:** pending | in-progress | blocked | done
**Priority:** high | medium | low
**Estimate:** XS | S | M | L | XL

### Description
One paragraph describing what needs to be done.

### Acceptance Criteria
- [ ] Criterion 1 - specific, measurable
- [ ] Criterion 2 - specific, measurable

### Validation
How to verify this is complete:
- Manual: [steps to manually test]
- Automated: [test file/command that validates this]

### Test Cases
| Input | Expected Output | Notes |
|-------|-----------------|-------|
| ... | ... | ... |

### Dependencies
- Depends on: [TODO-xxx] (if any)
- Blocks: [TODO-yyy] (if any)

### TDD Execution Log
| Phase | Command | Result | Timestamp |
|-------|---------|--------|-----------|
| RED | `[test command]` | - | - |
| GREEN | `[test command]` | - | - |
| VALIDATE | `[lint && typecheck && test --coverage]` | - | - |
| COMPLETE | Moved to completed.md | - | - |

Todo のルール

1. アトミック - 各 todo は、完了可能な単一の作業単位にします
2. テスト可能 - すべての todo に検証基準とテストケースを設定します
3. 適切な規模 - 「M」より大きい場合は、さらに細分化します
4. 独立性 - todo 間の依存関係を最小限にします
5. 追跡可能 - 完了したら active.md → completed.md に移動します

Todo の実行ワークフロー（TDD - 必須）

すべての todo は、必ず以下のワークフローに従う必要があります。例外はありません。

┌─────────────────────────────────────────────────────────────┐
│  1. RED: Write Tests First                                  │
│     └─ Create test file(s) based on Test Cases table        │
│     └─ Tests should cover all acceptance criteria           │
│     └─ Run tests → ALL MUST FAIL (proves tests are valid)   │
├─────────────────────────────────────────────────────────────┤
│  2. GREEN: Implement the Feature                            │
│     └─ Write minimum code to make tests pass                │
│     └─ Follow simplicity rules (20 lines/function, etc.)    │
│     └─ Run tests → ALL MUST PASS                            │
├─────────────────────────────────────────────────────────────┤
│  3. VALIDATE: Quality Gates                                 │
│     └─ Run linter (auto-fix if possible)                    │
│     └─ Run type checker (tsc/mypy/pyright)                  │
│     └─ Run full test suite with coverage                    │
│     └─ Verify coverage threshold (≥80%)                     │
├─────────────────────────────────────────────────────────────┤
│  4. PROVE + COMPLETE: Show evidence, then mark done         │
│     └─ Only after ALL validations pass                      │
│     └─ SHOW PROOF — paste the real test/lint/type output    │
│        (pass/fail counts), never just "tests pass"          │
│     └─ UI change? attach a screenshot / visual-diff         │
│     └─ Web user-facing flow? record a demo-video walkthrough │
│     └─ Security-critical change? run a security-audit pass   │
│     └─ Generated content? show the actual artifact          │
│     └─ Move todo to completed.md + checkpoint session state │
└─────────────────────────────────────────────────────────────┘

完了とは、主張ではなく証明です。 todo は、証拠があなたの応答に含まれている場合にのみ完了です。実際のコマンド出力、UI 変更がある場合はスクリーンショット、ユーザー向けの Web フローがある場合は demo-video のウォークスルー、生成コンテンツがある場合は実際の成果物を提示してください。証拠がなければ、完了ではありません。（CLAUDE.md の「完了の定義 — 絶対遵守」セクションを参照してください。）

スタック別の実行コマンド

Node.js/TypeScript:

# 1. RED - Run tests (expect failures)
npm test -- --grep "todo-description"

# 2. GREEN - Run tests (expect pass)
npm test -- --grep "todo-description"

# 3. VALIDATE - Full quality check
npm run lint && npm run typecheck && npm test -- --coverage

Python:

# 1. RED - Run tests (expect failures)
pytest -k "todo_description" -v

# 2. GREEN - Run tests (expect pass)
pytest -k "todo_description" -v

# 3. VALIDATE - Full quality check
ruff check . && mypy . && pytest --cov --cov-fail-under=80

React/Next.js:

# 1. RED - Run tests (expect failures)
npm test -- --testPathPattern="ComponentName"

# 2. GREEN - Run tests (expect pass)
npm test -- --testPathPattern="ComponentName"

# 3. VALIDATE - Full quality check
npm run lint && npm run typecheck && npm test -- --coverage --watchAll=false

ブロック条件

次の場合、todo を完了としてマークしてはいけません。

• ❌ 先にテストを作成していない（RED フェーズをスキップした）
• ❌ テストが最初に失敗しなかった（無効なテストである）
• ❌ 失敗しているテストがある
• ❌ リンターにエラーがある（警告は許容される場合があります）
• ❌ 型チェッカーにエラーがある
• ❌ カバレッジがしきい値を下回った

失敗によってブロックされた場合：

## [TODO-042] - BLOCKED

**Blocking Reason:** [Lint error in X / Test failure in Y / Coverage at 75%]
**Action Required:** [Specific fix needed]

バグ修正ワークフロー（TDD - 必須）

ユーザーからバグが報告された場合、決して直接修正に取りかかってはいけません。

┌─────────────────────────────────────────────────────────────┐
│  1. DIAGNOSE: Identify the Test Gap                         │
│     └─ Run existing tests - do any fail?                    │
│     └─ If tests pass but bug exists → tests are incomplete  │
│     └─ Document: "Test gap: [what was missed]"              │
├─────────────────────────────────────────────────────────────┤
│  2. RED: Write a Failing Test for the Bug                   │
│     └─ Create test that reproduces the exact bug            │
│     └─ Test should FAIL with current code                   │
│     └─ This proves the test catches the bug                 │
├─────────────────────────────────────────────────────────────┤
│  3. GREEN: Fix the Bug                                      │
│     └─ Write minimum code to make the test pass             │
│     └─ Run test → must PASS now                             │
├─────────────────────────────────────────────────────────────┤
│  4. VALIDATE: Full Quality Check                            │
│     └─ Run ALL tests (not just the new one)                 │
│     └─ Run linter and type checker                          │
│     └─ Verify no regression in coverage                     │
└─────────────────────────────────────────────────────────────┘

バグ報告の Todo 形式

## [BUG-001] Short description of the bug

**Status:** pending
**Priority:** high
**Reported:** [how user reported it / reproduction steps]

### Bug Description
What is happening vs. what should happen.

### Reproduction Steps
1. Step one
2. Step two
3. Observe: [incorrect behavior]
4. Expected: [correct behavior]

### Test Gap Analysis
- Existing test coverage: [list relevant test files]
- Gap identified: [what the tests missed]
- New test needed: [describe the test to add]

### Test Cases for Bug
| Input | Current (Bug) | Expected (Fixed) |
|-------|---------------|------------------|
| ... | ... | ... |

### TDD Execution Log
| Phase | Command | Result | Timestamp |
|-------|---------|--------|-----------|
| DIAGNOSE | `npm test` | All pass (gap!) | - |
| RED | `npm test -- --grep "bug description"` | 1 test failed ✓ | - |
| GREEN | `npm test -- --grep "bug description"` | 1 test passed ✓ | - |
| VALIDATE | `npm run lint && npm run typecheck && npm test -- --coverage` | Pass ✓ | - |

バグ修正のアンチパターン

• ❌ テストなしで修正する - バグが再発する可能性が高くなります
• ❌ 修正後にテストを書く - テストでバグを検出できることを証明できません
• ❌ テストの不足点分析をスキップする - テストで検出できなかった理由を見落とします
• ❌ 修正箇所だけをテストする - リグレッションを確認するため、テストスイート全体を実行する必要があります

アトミックな Todo の例

## [TODO-042] Add email validation to signup form

**Status:** pending
**Priority:** high
**Estimate:** S

### Description
Validate email format on the signup form before submission. Show inline error if invalid.

### Acceptance Criteria
- [ ] Email field shows error for invalid format
- [ ] Error clears when user fixes the email
- [ ] Form cannot submit with invalid email
- [ ] Valid emails pass through without error

### Validation
- Manual: Enter "notanemail" in signup form, verify error appears
- Automated: `npm test -- --grep "email validation"`

### Test Cases
| Input | Expected Output | Notes |
|-------|-----------------|-------|
| [email protected] | Valid, no error | Standard email |
| [email protected] | Valid, no error | Subdomain |
| notanemail | Invalid, show error | No @ symbol |
| user@ | Invalid, show error | No domain |
| @example.com | Invalid, show error | No local part |

### Dependencies
- Depends on: [TODO-041] Signup form component
- Blocks: [TODO-045] Signup flow integration test

### TDD Execution Log
| Phase | Command | Result | Timestamp |
|-------|---------|--------|-----------|
| RED | `npm test -- --grep "email validation"` | 5 tests failed ✓ | - |
| GREEN | `npm test -- --grep "email validation"` | 5 tests passed ✓ | - |
| VALIDATE | `npm run lint && npm run typecheck && npm test -- --coverage` | Pass, 84% coverage ✓ | - |
| COMPLETE | Moved to completed.md | ✓ | - |

---

認証情報の管理

プロジェクトで API キーが必要な場合は、必ず最初にユーザーに一元管理されたアクセスファイルを確認してください。

ワークフロー

1. Ask: "Do you have an access keys file? (e.g., ~/Documents/Access.txt)"
2. Read and parse the file for known key patterns
3. Validate keys are working
4. Create project .env with found keys
5. Report missing keys and where to get them

検出するキーのパターン

サービス	パターン	環境変数
OpenAI	sk-proj-*	OPENAI_API_KEY
Claude	sk-ant-*	ANTHROPIC_API_KEY
Render	rnd_*	RENDER_API_KEY
Replicate	r8_*	REPLICATE_API_TOKEN
Reddit	client_id + secret	REDDIT_CLIENT_ID、REDDIT_CLIENT_SECRET

解析ロジックと検証コマンドの詳細については、credentials.md を参照してください。

---

セキュリティ

すべてのプロジェクトは、これらのセキュリティ要件を満たす必要があります。詳しいパターンについては、security.md のスキルを参照してください。

必須のセキュリティチェック

1. コードにシークレットを含めない - 環境変数を使用し、シークレットは決してコミットしないでください
2. .env を .gitignore に含める - 必ず設定し、例外はありません
3. クライアントに公開される環境変数にシークレットを含めない - シークレットに VITE_*、NEXT_PUBLIC_* を決して使用しないでください
4. すべての入力を検証する - API の境界で Zod/Pydantic を使用してください
5. パラメーター化クエリのみを使用する - SQL に文字列連結を使用しないでください
6. パスワードを適切にハッシュ化する - 12 回以上のラウンド数で bcrypt を使用してください
7. 依存関係をスキャンする - npm audit / safety check を通過する必要があります

必須ファイル

• シークレットのパターンを含む .gitignore
• 必要な変数をすべて含む .env.example（値は記載しない）
• コミット前の検証を行う scripts/security-check.sh

CI でのセキュリティ

すべての PR で、以下に合格する必要があります。

• シークレットスキャン（detect-secrets / trufflehog）
• 依存関係の監査（npm audit / safety）
• 静的解析（CodeQL）

---

品質ゲート

カバレッジのしきい値

• コードカバレッジは最低 80% - これを下回る場合、CI は失敗する必要があります
• ビジネスロジック（core/）は 100% を目指します
• 統合テストで境界をカバーします

コミット前フック

すべてのプロジェクトに、以下を実行するコミット前フックを設定する必要があります。

1. リント（可能な場合は自動修正）
2. 型チェック
3. テスト（最低限、影響を受けるテスト）

これにより、問題が CI に持ち込まれる前に検出でき、時間を節約し、メインブランチをクリーンに保てます。

---

セッション管理

再開できるようにコンテキストを維持します。詳しくは session-management.md を参照してください。

コアルール：自然な区切りでチェックポイントを作成する

タスクを完了したら、次の項目を確認します。

1. 決定事項があるか？ → _project_specs/session/decisions.md に記録します
2. ツール呼び出しが10回を超えたか？ → current-state.md に完全なチェックポイントを作成します
3. 主要な機能が完了したか？ → session/archive/ にアーカイブします
4. それ以外の場合 → current-state.md を簡単に更新します

セッション開始時

1. _project_specs/session/current-state.md を読みます
2. _project_specs/todos/active.md を確認します
3. 記録されている「次のステップ」から続けます

セッション終了時

1. 現在のセッションをアーカイブします
2. 引き継ぎメモを記載して current-state.md を更新します
3. 次のステップが具体的で実行可能な内容になっていることを確認します

---

回答形式

機能を実装する場合（TDD に従います）：

1. 要件が曖昧な場合は 要件を明確にします
2. 構成を提案します — コードを書く前に概要を示します
3. 最初にテストを書きます — テストケース表に基づきます（RED フェーズ）
4. テストを実行して失敗することを確認します — テストが有効であることを証明します
5. テストに合格するために必要最小限のコードを 実装します（GREEN フェーズ）
6. 完全な検証を実行します — lint、型チェック、カバレッジ（VALIDATE フェーズ）
7. 複雑さに注意を促します — 制限に近づいている場合は警告します
8. 完了後にチェックポイントを作成します — セッションの状態を更新し、TDD の実施内容を記録します

TDD は必須です。 実装を始める前に、テストを作成し、失敗することを確認する必要があります。

これらのルールに違反するコードに気付いた場合は、作業を止めてリファクタリングしてから続けます。

---

自動 TDD ループ（Stop Hook 経由）

.claude/settings.json の Stop hook は、応答のたびにテストを実行します。テストが失敗すると、失敗の出力が自動的に Claude に返されます。手動での対応は不要です。

設定の詳細については、iterative-development スキルを参照してください。

動作の仕組み

1. Claude に何かの実装を依頼します
2. Claude がテストと実装を書きます
3. Stop hook がテストを自動的に実行します
4. テストが失敗した場合：出力が Claude に返され、Claude が修正して再試行します
5. すべて合格した場合：Claude が停止し、作業は完了です

作動する条件

タスクの種類	TDD ループ？
新機能	はい — 応答ごとにテストが実行されます
バグ修正	はい — まず失敗するテストを書きます
リファクタリング	はい — 既存のテストでデグレードを検出します
簡単な質問・説明	いいえ — コードを変更しません
1 行の修正	いいえ — 些細な変更です