leanspec

LeanSpec — 仕様駆動コーディングスキル

エージェントに仕様駆動コーディングを教えます。これは、仕様を一時的な計画メモではなく、開発を推進する永続的な成果物として扱う手法です。LeanSpec は方法論と leanspec CLI を提供します。各アダプター（markdown、GitHub Issues、ADO、Jira、…）は、それぞれのバックエンド固有の言語を使います。このスキルは意図的にアダプターに依存しない設計です。ここにステータス値、優先度名、フィールドキーをハードコードしないでください。

すべてのセッションを機能の確認から始める

仕様の読み取り、書き込み、リンクを行う前に、次を実行します。

leanspec capabilities -o json

出力が信頼できる情報源です。次の内容が示されます。

• アクティブなアダプターの名前（markdown、github、ado、…）。
• 存在するメタデータフィールドと、その型や列挙値。
• このアダプターで各意味的役割（status、priority、tags、 assignee、due_date）を担うフィールド。
• バックエンドが理解するリンクタイプ（parent、depends_on、…）。

返された列挙値だけを有効な語彙として使用します。仕様を「作業中」の状態に移したい場合は、意味的役割が status のフィールドを調べ、アダプターが「作業が進行中」と呼ぶ値を選んで送信します。in-progress という名前だと決めつけないでください。

基本原則

1. 仕様は永続的な成果物です。 セッション終了後も残り、レビュー可能で、コードと関連付けられます。計画モードの一時的なメモではありません。
2. 方法論であり、仕組みではありません。 以下の5つのフェーズは、バックエンドが markdown フォルダーでも、GitHub リポジトリでも、Jira プロジェクトでも適用されます。
3. まず確認します。 新しいものを書く前に、既存のものを必ず読みます。
4. 実装より意図を先にします。 まずなぜを、次にどのようにを記録します。
5. 現実と照らして検証します。 ステータスフィールドだけを信用せず、コード、コミット、テスト、CI を確認します。
6. アダプターの語彙を使います。 フィールド名や値をハードコードしないでください。

5つのフェーズ

1. 確認する

何かに手を加える前に、プロジェクトの現状を把握します。

1. leanspec capabilities -o json を実行します（セッション開始時）。
2. leanspec board を実行して、プロジェクトの現在の構成を確認します。
3. leanspec search "<keywords>" を実行して、関連する項目を探します。
4. よく似た項目が見つかった場合は、新しい項目を作成するのではなく、既存の項目を拡張したり、リンクしたりすることを検討します。

2. 作成する

意図を新しい永続的な成果物として記録します。

1. 既知のフィールド（タイトル、本文、ステータスや優先度などの意味的フィールド、タグ、親項目、依存関係）をすべて1回の呼び出しで指定して、leanspec create <short-name> を実行します。空の項目を作成してから更新してはいけません。
2. 本文には次の内容を記述します。
   • 概要 — 解決する問題と、それが重要な理由。
   • 要件 — 個別に検証できる項目のチェックリスト。
   • 対象外 — 明示的にスコープ外とする内容。
   • 受け入れ条件 — 完了の定量的な定義。
3. 関連性が明らかになったら、関係をリンクします。アダプターが宣言するリンクタイプ（通常、階層には parent、ブロッカーには depends_on を使用します。capabilities で確認してください）を使います。

3. 詳細化する

コーディングを始める前に、仕様を実装できる状態にします。

1. 仕様で参照されているファイル、モジュール、API を見つけ、実在することを確認します。
2. 再利用できる既存のパターンを探し、具体的なパスと関数シグネチャを仕様に記録します。
3. 依存関係が利用可能であることを検証します。
4. ゲート条件：作業を妨げる不明点がなく、チェックリストの各項目が具体的で実行可能であること。

4. 実装する

詳細化された仕様に沿って作業します。

1. 仕様（leanspec view <id>）を読み、親項目、子項目、依存関係も確認します。
2. leanspec update <id> を使い、アダプターが宣言するステータス値で仕様を「作業中」の状態に移します。
3. チェックリストを順に進め、スコープの境界内で作業します。判断や発見があれば、その都度仕様内に記録します。
4. スコープ外の作業が必要だとわかった場合は、現在の仕様を拡張するのではなく、新しい仕様を作成してリンクします。

5. 検証

ステータスではなく、実際の状態と照らし合わせて完了を確認します。

1. プロジェクトの品質ゲート（テスト、型チェック、Lint、ビルド）を実行します。
2. 仕様の受け入れ基準を読み直し、それを証明するコミット、テスト、またはファイルを示せる場合にのみ、各項目にチェックを付けます。
3. 仕様をアダプターが宣言する「完了」状態に移行し、短い実装メモを追記します。
4. 失敗があった場合は、進行中のまま原因を修正し、再実行します。

関係の種類

関係の種類はアダプターによって宣言されます。capabilities.link_types を確認してください。よく使われる形は次の2つです。

• 親／子 — 大きな項目を子項目に分解します。子項目は親項目がなければ意味を成さず、すべての子項目が完了すると親項目も完了します。
• 依存関係 — ブロッカーを表します。2つの項目はそれぞれ独立した作業ですが、一方を先にリリースする必要があります。

判断フローチャート：

1. 項目 B は項目 A のスコープに含まれますか？ → 親／子。
2. 項目 B は項目 A の完了を待つだけですか？ → 依存関係。
3. 同じ項目の組み合わせに両方を使うことは避けてください。

判断基準：「項目 A が存在しなかったとしても、項目 B は意味を成しますか？」 いいえ → B は A の子項目です。はい → B は A に依存します。

変化する作業の管理

• コンテンツの変更 — leanspec update --content を使うか、項目の本文を編集します。
• メタデータの変更 — アダプターが宣言するフィールドには、サポートされている leanspec update フラグ（--status、--priority、--assignee、--add-tags、--remove-tags など）を使います。各フラグで指定できる値は、アダプターの機能に従います。このスキルは、フロントマターや YAML を直接編集しません。
• スコープの拡大 — 分割します。兄弟仕様を作成して関連付け、元の仕様の対象外事項に、分割した項目への参照を追加します。
• 不要になった作業 — 削除せず、アダプターの「クローズ／アーカイブ」状態に移行します。履歴は重要です。

コンテキストの節約

• 各項目は約 2000 トークン未満に保ちます。それを超える場合は分割します。
• 散文より箇条書きを優先します。
• 外部ドキュメントを複製するのではなく、参照を記載します。
• チェックリストは実行可能な項目にのみ使い、それ以外は通常のリストにします。

ベストプラクティス — 要点

• 項目を手動で作成しないでください。 必ず leanspec create を使います。
• メタデータを直接編集しないでください。 leanspec update を使います。
• 必ず最初に状況を確認してください。 create の前に board ／ search を実行します。
• 把握しているすべてのフィールドを、必ず create に渡してください。 空の状態で作成してから更新することは避けます。
• クローズする前に必ず検証してください。 テスト、型チェック、Lint、ビルドを実行します。
• アダプターの語彙に従ってください。 あいまいな点があれば、capabilities を再実行します。

参考資料

• references/adapters.md — アダプターの仕組みと、その上に独自の SOP を構築する方法。
• references/workflow.md — 例を交えた5段階のワークフロー。
• references/commands.md — CLI リファレンス。
• references/best-practices.md — パターンとアンチパターンの詳細。
• references/examples.md — Markdown、GitHub Issues、Azure DevOps のバックエンドを使った一連のシナリオ。