skill-writing-plans

ホスト：Codex CLI — このスキルは Claude Code 向けに設計され、Codex 用に調整されています。 相互参照コマンドでは、/octo:* スラッシュコマンドではなく、Codex にインストール済みのスキル名を使用します。 現在の Codex シェルとサブエージェントツールを使用してください。現在のセッションで利用可能であることが確認されるまでは、プロバイダー、モデル、ホストのサブエージェントが利用可能だと主張しないでください。 ホストツールに相当するものについては、skills/blocks/codex-host-adapter.md を参照してください。

計画の作成

インストール済みプラグインから skills/blocks/engineering-method-selection.md を読み込み、 このタスクに関連する手法のみを適用してください。このエントリーポイントの 実行契約と出力形式は維持してください。参照先のスキルは指示として読み、 現在のコマンドを再帰的に呼び出したり、シートからプロバイダーへの呼び出しを追加したりしないでください。

必須遵守事項 — 省略禁止

このスキルが呼び出された場合、以下の構成に従って完全な実装計画を必ず作成してください。次の行為は禁止されています。

• 計画を省略し、実装に直行する
• ゼロコンテキスト計画の形式ではなく、曖昧な概要を作成する
• タスクが「簡単すぎる」ため計画は不要だと判断する
• ファイルパス、完全なコード、テスト手順、検証手順を省略する

ユーザーが求めているのは計画であり、実装ではありません。まず計画を作成してください。

最初の出力行は必ず次のとおりにしてください： 🐙 **CLAUDE OCTOPUS ACTIVATED** - Implementation Planning

概要

コードベースに関する知識がまったくなく、センスにも疑問があるエンジニアを想定して、包括的な実装計画を作成してください。

すべてを記述してください。変更するファイル、完全なコード、テスト方法、検証方法を含めます。

原則： DRY。YAGNI。TDD。こまめなコミット。

タスクの前に決定事項を整理する

実装タスクを作成する前に、未解決の決定事項について依存関係グラフを作成してください。 決定記録には、質問、必要な根拠、依存関係、担当者、解決内容、および解決によって着手可能になる実装を記載します。リポジトリで設定されているトラッカーを使用してください。Beads はエンドユーザーの要件ではありません。

決定の状態は open、claimed、resolved、superseded、blocked とし、ネイティブのトラッカー状態またはラベルに対応付けます。根拠または記録された人間の判断がある場合に限り、決定を解決済みにしてください。新たな根拠によって決定が無効になった場合は、その理由を説明したうえで、依存する作業を再開してください。循環がある場合、その作業に着手する準備はできていません。タスクを着手可能としてマークするのではなく、決定事項を再構成してください。

トラッカーのアトミック操作を使って担当を取得し、作成前に所有者情報を読み返してください。アトミックな担当取得が利用できない場合は、統合担当者を1人任命してください。他の担当者の取得済み担当を上書きしないでください。トラッカーが機能しない場合は、既存の計画保存先に未登録の提案であることを明記して保存し、トラッカーへの書き込みを停止してください。IDを捏造したり、データベースを移行したりしないでください。

計画書の構成

ヘッダー（必須）

# [Feature Name] Implementation Plan

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Estimated Time:** [X tasks × 5 min = Y minutes]


## Prerequisites

- [ ] [Any setup needed before starting]
- [ ] [Dependencies to install]
- [ ] [Files that must exist]

タスクの粒度

各タスクは1つのアクション（2～5分）にしてください。

良い例（単一のアクション）	悪い例（複数のアクション）
「失敗するテストを書く」	「テストを書いて実装する」
「失敗することを確認するためにテストを実行する」	「動作するようにする」
「合格する最小限のコードを実装する」	「機能を追加する」
「メッセージを付けてコミットする」	「機能を完成させる」

タスクのテンプレート

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/new-file.ts`
- Modify: `exact/path/to/existing.ts` (lines 45-67)
- Test: `tests/exact/path/to/test.spec.ts`

**Step 1: Write failing test**

```typescript
// tests/exact/path/to/test.spec.ts
describe('ComponentName', () => {
  it('should do specific thing', () => {
    const result = functionName(input);
    expect(result).toBe(expected);
  });
});

ステップ 2：失敗することを確認するためにテストを実行する

npm test tests/exact/path/to/test.spec.ts

期待される出力：

FAIL: expected 'expected' but got undefined

ステップ 3：最小限のコードを実装する

// exact/path/to/new-file.ts
export function functionName(input: InputType): OutputType {
  // Minimal implementation
  return expected;
}

ステップ 4：合格することを確認するためにテストを実行する

npm test tests/exact/path/to/test.spec.ts

期待される出力：

PASS: 1/1 tests passed

ステップ 5：コミットする

git add tests/exact/path/to/test.spec.ts exact/path/to/new-file.ts
git commit -m "feat(component): add specific functionality"

## Example: Complete Task

```markdown
### Task 3: Add Email Validation

**Files:**
- Create: `src/validators/email.ts`
- Test: `tests/validators/email.spec.ts`

**Step 1: Write failing test**

```typescript
// tests/validators/email.spec.ts
import { validateEmail } from '../src/validators/email';

describe('validateEmail', () => {
  it('returns error for empty email', () => {
    const result = validateEmail('');
    expect(result).toEqual({ valid: false, error: 'Email required' });
  });

  it('returns error for invalid format', () => {
    const result = validateEmail('not-an-email');
    expect(result).toEqual({ valid: false, error: 'Invalid email format' });
  });

  it('returns valid for correct email', () => {
    const result = validateEmail('[email protected]');
    expect(result).toEqual({ valid: true });
  });
});

ステップ 2：失敗することを確認するためにテストを実行する

npm test tests/validators/email.spec.ts

期待値：Cannot find module '../src/validators/email'

ステップ 3：最小限のコードを実装する

// src/validators/email.ts
interface ValidationResult {
  valid: boolean;
  error?: string;
}

export function validateEmail(email: string): ValidationResult {
  if (!email || !email.trim()) {
    return { valid: false, error: 'Email required' };
  }

  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(email)) {
    return { valid: false, error: 'Invalid email format' };
  }

  return { valid: true };
}

ステップ 4：合格することを確認するためにテストを実行する

npm test tests/validators/email.spec.ts

期待値：PASS: 3/3 tests passed

ステップ 5：コミットする

git add src/validators/email.ts tests/validators/email.spec.ts
git commit -m "feat(validators): add email validation with tests"

## Integration with Claude Octopus

### Using Octopus for Plan Execution

After creating a plan, offer execution options:

```markdown
## Execution Options

**1. Sequential (this session)**
Execute tasks one by one with verification between each.

**2. Parallel (octopus tangle)**
Use Claude Octopus to parallelize independent tasks:
```bash
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh tangle "Execute implementation plan for [feature]"

3. 完全なワークフロー（octopus embrace） 調査 → 定義 → 実装 → 提供：

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh embrace "Implement [feature] per plan"

### Plan Storage (Claude Code v2.1.10)

Claude Octopus uses session-aware plan storage. Plans are automatically saved to:

~/.claude-octopus/plans/${CLAUDE_SESSION_ID}/YYYY-MM-DD-feature-name.md

This integrates with Claude Code's `plansDirectory` setting. To customize:

```json
// settings.json
{
  "plansDirectory": "~/.claude-octopus/plans"
}

プロジェクト内の計画書は docs/plans/ に保存してください：

mkdir -p docs/plans
# docs/plans/2026-01-17-user-authentication.md

優れた計画のチェックリスト

• 各タスクは2～5分で完了する（単一のアクション）
• 正確なファイルパスを指定する（「utils フォルダー内」ではなく）
• コードを完全に記載する（「検証ロジックを追加する」ではなく）
• 期待される出力を含む正確なコマンドを記載する
• TDD：実装の前にテストする
• 各タスクの完了後にコミットする

よくある間違い

間違い	修正方法
「検証を追加する」	正確なコードを示す
「テストを更新する」	正確なテストコードを示す
「設定ファイル内」	config/app.config.ts の23行目
「テストを実行する」	npm test path/to/specific.spec.ts
大きなタスク（30分以上）	2～5分の手順に分割する
検証がない	「Xを実行し、Yを期待する」を追加する

計画を作成するタイミング

シナリオ	計画を使用するか
複数ステップの機能（3タスク以上）	はい
簡単なバグ修正（1タスク）	いいえ、そのまま実行する
範囲が不明確	はい（考えを整理できる）
サブエージェントへの委任	はい（コンテキストなしで実行できる）
複雑なリファクタリング	はい
設定変更	いいえ

関連スキル

• test-driven-development - 各タスクでTDDサイクルに従う
• verification-before-completion - 各手順を検証する
• finishing-branch - すべてのタスク完了後に実行する

要点

Plan exists → Engineer with zero context can execute
Otherwise → Not a complete plan

正確なパス。完全なコード。検証手順。思い込みを排除する。