mcpField
W
writing-plans

writing-plans

github.com/lucianghindaその他43943 回インストール1 日前に更新
リポジトリ

writing-plans について

ファイルパス、コード、テスト、コマンドを含む、タスク単位の詳細な実装計画を作成するスキルです。小さな手順で実装と検証を進める開発者やエージェントを対象としています。

主な機能

  1. 01ファイルと役割の整理
  2. 02作業の小さな手順への分割
  3. 03コードとテスト手順の記載
  4. 04網羅性と整合性の確認

活用シーン

  1. 01仕様に基づく機能計画
  2. 02不慣れなコードベースでの作業準備
  3. 03テスト駆動の実装タスク作成

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/lucianghinda/rubypowers --skill writing-plans

インストール後、Claude Code で/writing-plansを入力して読み込まれたか確認します。

同梱ファイルplan-document-reviewer-prompt.md

詳細

計画の作成

概要

コードベースに関する知識がまったくなく、好みも疑わしいエンジニアを想定して、包括的な実装計画を作成してください。各タスクで変更するファイル、コード、テスト、確認が必要なドキュメント、テスト方法など、必要な情報をすべて記載します。計画全体を、取り組みやすい小さなタスクに分けてください。DRY。YAGNI。TDD。こまめにコミットします。

熟練した開発者ではあるものの、こちらのツールセットや問題領域についてはほとんど知らないものと想定してください。優れたテスト設計についても、あまり詳しくないものと想定してください。

最初に宣言します：「writing-plans スキルを使って、実装計画を作成します。」

コンテキスト： この作業は、brainstorming スキルで作成した専用のワークツリーで行ってください。

計画の保存先： 新規プロジェクトの場合は、docs/rubypowers/plans/YYYY-MM-DD-<feature-name>.md に保存します。docs/superpowers/plans/ がすでに存在する場合は、既存プロジェクトのドキュメントをまとめておけるよう、代わりにその従来のフォルダーを使用してください。このワークフローでのすべての下書きの保存、編集、正式な反映、完了メッセージ、レビュアーへの指示には、選択したフォルダーを使用してください。従来のフォルダーがあるプロジェクトには、新しいフォルダーを作成しないでください。

  • ユーザーが希望する計画の保存先がある場合は、既定の保存先よりも優先してください。

スコープの確認

仕様に複数の独立したサブシステムが含まれている場合は、ブレインストーミングの段階でサブプロジェクトの仕様に分割しておくべきです。分割されていない場合は、サブシステムごとに別の計画に分けることを提案してください。各計画は、それ単独で動作し、テストできるソフトウェアを生み出す必要があります。

ファイル構成

タスクを定義する前に、作成または変更するファイルと、それぞれの役割を洗い出してください。ここで分解の方針を決めます。

  • 境界が明確で、インターフェースが適切に定義された単位を設計してください。各ファイルの責務は一つにしてください。
  • 一度に把握できるコードの量には限りがあり、ファイルが目的ごとに整理されているほど、変更の信頼性が高まります。何でも詰め込んだ大きなファイルより、小さく、目的が明確なファイルを優先してください。
  • 一緒に変更するファイルは、同じ場所に配置してください。技術レイヤーではなく、責務ごとに分割してください。
  • 既存のコードベースでは、確立されたパターンに従ってください。大きなファイルを使っているコードベースを、一方的に再構成しないでください。ただし、変更対象のファイルが扱いにくいほど大きくなっている場合は、計画に分割を含めてもかまいません。

この構成をもとにタスクを分解します。各タスクは、単独で意味のある、一貫した変更を生み出す必要があります。

取り組みやすいタスクの粒度

各ステップは一つの作業（2～5分）にします：

  • 「失敗するテストを書く」— 1ステップ
  • 「失敗することを確認するために実行する」— 1ステップ
  • 「テストを通すために最小限のコードを実装する」— 1ステップ
  • 「テストを実行し、成功することを確認する」— 1ステップ
  • 「コミットする」— 1ステップ

計画ドキュメントのヘッダー

すべての計画は、必ず次のヘッダーから始めてください：

# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use rubypowers:subagent-driven-development (recommended) or rubypowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

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

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

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

---

タスクの構成

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

- [ ] **Step 1: Write the failing test**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL with "function not defined"

- [ ] **Step 3: Write minimal implementation**

```python
def function(input):
    return expected
```

- [ ] **Step 4: Run test to verify it passes**

Run: `pytest tests/path/test.py::test_name -v`
Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```

プレースホルダー禁止

すべてのステップには、エンジニアが必要とする具体的な内容を記載してください。次のような記述は計画の失敗とみなします。絶対に使わないでください：

  • 「未定」、「TODO」、「後で実装する」、「詳細を記入する」
  • 「適切なエラー処理を追加する」／「バリデーションを追加する」／「エッジケースに対処する」
  • 「上記のテストを書く」（具体的なテストコードがないもの）
  • 「タスク N と同様」（担当者がタスクを順不同で読む可能性があるため、コードを繰り返し記載してください）
  • 方法を示さず、作業内容だけを記述するステップ（コードを変更するステップにはコードブロックが必要です）
  • どのタスクでも定義されていない型、関数、メソッドへの参照

忘れずに

  • ファイルパスは必ず正確に記載します
  • 各ステップには完全なコードを記載します。ステップでコードを変更する場合は、そのコードを示してください
  • コマンドと期待される出力を正確に記載します
  • DRY、YAGNI、TDD、こまめなコミットを徹底します

セルフレビュー

計画全体を書き終えたら、視点を新たにして仕様を確認し、計画と照らし合わせます。これは自分で実施するチェックリストであり、サブエージェントへの割り当てではありません。

1. 仕様の網羅性： 仕様の各セクション／要件をざっと確認します。それぞれを実装するタスクを示せますか？不足しているものを列挙してください。

2. プレースホルダーの確認： 計画を検索し、危険な兆候がないか確認します。上記の「プレースホルダー禁止」セクションにあるパターンがあれば修正してください。

3. 型の一貫性： 後続のタスクで使用している型、メソッドシグネチャ、プロパティ名は、先行するタスクで定義したものと一致していますか？タスク 3 で clearLayers() と呼んでいる関数が、タスク 7 では clearFullLayers() になっている場合、これは不具合です。

問題が見つかった場合は、その場で修正します。再レビューは不要です。修正して先に進んでください。タスクに含まれていない仕様要件が見つかった場合は、そのタスクを追加してください。

実行の引き継ぎ

計画を保存した後、実行方法を選べるようにします。

「計画を <selected plans folder>/<filename>.md に保存しました。実行方法は 2 つあります。

1. サブエージェント主導（推奨） - タスクごとに新しいサブエージェントを割り当て、タスク間でレビューしながら、すばやく反復します。

2. インライン実行 - executing-plans を使用し、このセッション内でチェックポイントを設けてタスクをまとめて実行します。

どちらの方法にしますか？」

サブエージェント主導を選択した場合：

  • 必須のサブスキル： rubypowers:subagent-driven-development を使用します
  • タスクごとに新しいサブエージェントを割り当て、2 段階のレビューを行います

インライン実行を選択した場合：

  • 必須のサブスキル： rubypowers:executing-plans を使用します
  • レビュー用のチェックポイントを設けて、タスクをまとめて実行します

コメント

Markdown 対応