incu-way-development

開発プロセス

新機能を推測に頼らずリリースするための、ゲート駆動型の構造化されたワークフローです。まずディスカバリーとインテークを行い、その後、PRD、計画、実装、検証、PRへと進みます。重要な各ゲートでは、ユーザーの明示的な承認を得ます。

---

リポジトリの適格性チェック（何よりも先に）

Phase 0 の前に、現在のリポジトリが ~/.ways/config.yaml の blacklist（形式：常時インストールされている incu-base の global-config ルール）に該当するか確認します。該当する場合、このリポジトリは incu-way でブラックリストに登録されていることをユーザーに伝え、このまま進める（今回限りの例外）か、停止するかを確認します。回答があるまでは、どのフェーズも実行しないでください。ファイルがない場合、または該当しない場合は、通常どおり進めます。

---

Phase 0 — ディスカバリーとインテーク（何よりも先に）

コードやプロジェクトのドキュメントを1行でも書く前に、誤った PRD を作成しないよう、プロダクトとコードベースについて十分な情報を集めます。

ディスカバリーチェックリスト

1. PRD.md（プロジェクトルート）を読みます。
2. docs/ 内の既存ドキュメントすべてと、docs/prds/ 内の PRD すべてを読みます。 この依頼について、精緻化されたチケットが docs/requirements/{slug}/TICKET.md に存在する場合（incu-way-po によって作成）、まずそれを読みます。受け入れ基準は PRD の機能要件の出発点として扱い、実現可能性に関する注記と影響を受けるモジュールのマップは、再導出するのではなく検証してください。
3. 依頼内容をプロダクトの観点から明確にします。
   • どのような変更が求められているか
   • 誰のための変更か
   • クライアントまたはステークホルダーが何を期待しているか
   • 何をもって成功とするか
   • 既存の制約や対象外事項は何か
4. コードベースの状況を把握します。
   • 依頼に関連する現在の動作
   • 影響を受ける可能性のあるモジュール、エントリーポイント、連携機能、テスト
   • 維持すべき既存のパターン
   • 既存機能との競合、重複、依存関係
   • 同じプロダクト内にある、影響を受ける可能性のある他のリポジトリ。ハブリポジトリの CLAUDE.md に repos: セクションがあればそれを確認します（存在する場合はこちらが優先）。なければ ~/.ways/config.yaml の linkedRepos（形式：常時インストールされている incu-base の global-config ルール）を確認します。どちらのリストにもこのリポジトリしか記載されていない場合は、単一リポジトリのプロダクトです。
5. 依頼の内容に応じて、ディスカバリーの深さを調整します。
   • 小規模で要件が明確な変更では、調査を簡潔に保ちます。
   • 曖昧な依頼、広範囲に影響する依頼、またはクライアントへの影響が大きい依頼では、何かを作成する前に詳しく調査します。
6. 重要な不明点が残っている場合は、PRD に進む前に要点を絞った確認質問をします。

Phase 0 の完了条件

Phase 1 に進む前に、Claude は以下を説明できる必要があります。

• 解決する問題と求められている変更
• 変更の対象者と、クライアント／ステークホルダーの期待
• 現時点で把握している成功基準または完了の定義
• 影響を受ける可能性のあるドキュメント、モジュール、フロー、連携機能
• 前提としている事項
• ユーザーへの確認が必要な未解決の質問

これらの点に合理的な確信を持って答えられない場合は、まだ PRD を作成しないでください。まず確認質問をします。

---

分離環境の設定（Phase 0 の直後）

ファイルを1つでも作成する前に、作業をどのように分離するかユーザーに確認します。

現在のチェックアウトに新しいブランチを作成して作業しますか、それとも別の git worktree を作成しますか？

ユーザーの回答どおりに進めます。 質問したらそこで停止し、ユーザーが選択するまでブランチも worktree も作成しないでください。

現在のチェックアウトにコミットされていない変更がある場合は、ブランチの切り替えや worktree の作成を行う前に停止して確認します。

オプション A — 現在のチェックアウトにブランチを作成

# Run from the repo root
git switch develop
git pull --ff-only
git switch -c feat/{slug}

以降のすべての作業（PRD、計画、コード、ドキュメント、コミット）は、現在のチェックアウトに作成したこのブランチで行います。develop や main に直接ファイルを書き込んではいけません。

オプション B — 別の worktree

worktree は .worktrees/ の下にのみ作成します。パスをユーザーに尋ねないでください。

# Run from the repo root
git fetch origin develop
mkdir -p .worktrees
git worktree add .worktrees/{slug} -b feat/{slug} origin/develop

以降のすべての作業（PRD、計画、コード、ドキュメント、コミット）は、この worktree 内でのみ行います。develop や main に直接ファイルを書き込んではいけません。

---

状態の追跡 — .ways/state.json

ways/v1alpha1 state contract（正規の .ways/state.json 形式、schemaVersion は 2）に従ってください。これは ways add がプロジェクトに配置する常時有効な state-contract ルールとして提供されるため、すでにコンテキストに含まれています（たどるパスはありません）。メンテナー向けの、このリポジトリ内のソースは ways/rulepacks/state-contract/ です。このスキル内でスキーマをコピーしたり、独自に作成したりしないでください。

フロー固有の値：

• flow: feature
• way: incu/dev · discipline: development（任意で、way マニフェストから wayVersion を指定）
• ブランチパターン：feat/{slug}
• 初期 phase：discovery
• isolationType：Phase 0 の分離方式の選択に応じて branch または worktree
• ドキュメント：docs/prds/{slug}/PRD.md、docs/prds/{slug}/PLAN.md、docs/prds/{slug}/TESTING.md
• ゲート：prd、plan、testing、pr-develop、pr-main

セッション開始時に、.ways/state.json が存在する場合は読み込んでください。branch が現在の feat/{slug} ブランチと一致する場合は、現在のフェーズ／次のステップ／保留中のゲートを報告し、その状態から再開してください。ファイルが存在しない場合、または存在するものの branch が一致しない場合（マージ済みの機能から引き継がれた古いファイル）は、Phase 0 から開始し、選択した分離方式のセットアップ直後に .ways/state.json を作成または上書きしてください。フェーズが切り替わるたびに、退出するフェーズを lastPhase にも更新してください。

更新ポイント（フェーズ → 書き込む内容）：

タイミング	phase	ドキュメント／ゲート／ステップ
PRD のドラフト作成	prd	PRD.md → in-review
Gate 1 通過	plan	PRD.md → approved；ゲート prd → passed
Plan のドラフト作成	plan	PLAN.md → in-review
Gate 2 通過	implementation	PLAN.md → approved；ゲート plan → passed；PLAN.md のタスクから steps を生成する — 実行可能なタスクごとに 1 エントリーを作成し、すべて todo にする
実装中	implementation	各ステップを in-progress → done（または blocked）に更新する — フェーズの最後にまとめてではなく、ステップごとに直ちに状態ファイルを書き込む
検証	validation	TESTING.md → 作成後に approved
Gate 3 通過	review	ゲート testing → passed
feat→develop の PR を作成	pr-develop	ゲート pr-develop → 引き続き pending；その url に PR のリンクを設定
PR を develop にマージ	pr-develop	ゲート pr-develop → passed
develop→main の PR を作成	pr-main	ゲート pr-main → 引き続き pending；その url に PR のリンクを設定
PR を main にマージ	done	ゲート pr-main → passed

Gate 2 で生成する steps 配列が、ボード上で進捗（例：3/7）として表示される内容です。ステップ ID はプランのフェーズラベル（A1、A2、B1、…）に合わせてもかまいません。

.ways/state.json は自分でコミットせず、書き込むだけにしてください。ユーザーがチェックポイントを永続化したい場合は、incu-way-prepare-pr を呼び出すよう提案してください。これにより、そのチェックポイントと、該当する遷移のドキュメント／コードが一緒にコミットされます。

---

Phase 1 — PRD のドラフト作成

目標： Phase 0 の調査結果に基づいて、新機能に焦点を絞った PRD を作成します。

保存先

docs/prds/{prd-slug}/PRD.md

スラッグ形式： {zero-padded-id}-{kebab-feature-name} 例：003-contact-export、007-auto-tagging-rules

次の ID の確認 — このチェックアウトだけでなく、すでに使われている可能性のある場所をすべて確認してください。 現在のブランチだけを確認するカウンターでは、2 つの機能を並行して作業した瞬間に ID が衝突します。同じベースから分岐した 2 つの worktree／ブランチが、それぞれ独立して同じ「次の」番号を算出することになり、実際にこの問題は発生しています。スキャンするだけでは解決しません。2 つのエージェントが同時にスキャンし、両方が同じ番号を算出してから、それぞれのディレクトリを作成する可能性があります。1 台のマシン上でこれを防ぐには、スキャンから予約までの処理中にロックを保持してください。

0. スキャンを始める前に、同じマシン上でロックを取得します。

   LOCK="$(git rev-parse --git-common-dir)/incu-way-prd-slug.lock"
   until mkdir "$LOCK" 2>/dev/null; do sleep 0.2; done
   trap 'rmdir "$LOCK"' EXIT
   

   mkdir が成功するプロセスは常に 1 つだけです。また、--git-common-dir はこのリポジトリのすべての worktree から同じ共有パスを解決するため、このチェックアウトだけでなく worktree 間でもロックが見えます。実際にこの競合が起きるのはまさに worktree 間です。このロックは incu-way-po と共有します（incu-way-prd-slug.lock、同じ ID 空間：docs/prds/ と docs/requirements/）。incu-way-bugs とは共有しません（別の ID 空間です）。
1. このチェックアウトの docs/prds/ と docs/requirements/ ですでに使われている ID を一覧表示します。
2. このリポジトリのほかのすべての worktree を一覧表示し（git worktree list）、それらの docs/prds/ と docs/requirements/ も確認します。兄弟 worktree の PRD はここでの git status には表示されませんが、ディスク上には存在しています。
3. デフォルトブランチをフェッチし（git fetch origin {default}）、そこですでにマージされている内容を一覧表示します（git ls-tree --name-only origin/{default} -- docs/prds/ docs/requirements/）。このブランチの作成後に誰かがマージした ID は、まだローカルのツリーには含まれていません。

3 か所すべてで見つかった ID のうち、最も大きい値の次の ID を使用し、ロックを解除する前に、ただちに docs/prds/{id}-{slug}/ を作成してください（空のプレースホルダーファイルだけでも予約できます）。ロックを解除するのはその後です（上記の trap が、上の手順のいずれかが失敗した場合も含めて自動的に処理します）。ロックを保持したまま予約することが、同じマシン上での競合を実際に防ぐ方法です。スキャンだけでは防げません。2 つ目のエージェントは、ロックが解除されるまで手順 1 を開始できず、その時点ではこの ID はすでにディスク上に存在します。ただし、フェッチが行われていない異なる 2 台のマシン間で発生する本当の競合は防げません。これは、中央レジストリのないクライアント側カウンターに固有の限界です。

この機能が incu-way-po のチケットに由来する場合は、チケットのスラッグを再利用して、docs/requirements/{slug}/ と docs/prds/{slug}/ が対応するようにします。

PRD の構成

# PRD — {Feature Name}

## Status
Draft | In Review | Approved | In Progress | Done

## Problem
One paragraph. What pain does this solve? Who feels it?

## Goals
Bulleted list. Measurable outcomes where possible.

## Non-goals
What is explicitly out of scope.

## User stories
- As a [role], I want [action] so that [benefit].

## Functional requirements
Numbered list. Concrete, testable.

## Non-functional requirements
Performance, security, accessibility constraints.

## Data model changes
Tables, columns, or relations added/modified. Reference `docs/database-schema.md`.

## UI/UX notes
Key screens or flows. Link wireframes if any.

## Open questions
Unresolved decisions that need user input before implementation.

## Conflicts / dependencies
List any conflicts with existing PRDs or features found in Phase 0.

ゲート 1 — PRD レビュー

PRD を作成した後：

• 未解決の前提や未回答の質問を推測で補わず、明示してください。
• 未回答の質問があれば、明示してください。
• 次のように伝えます：「PRD のドラフトを docs/prds/{slug}/PRD.md に用意しました。続行する前にレビューしてください。」
• 停止してください。ユーザーが OK と言うまで先に進まないでください。

---

フェーズ 2 — 実装計画

目標： PRD の要件をコード変更に対応付けた、段階的な計画を作成します。

保存先

docs/prds/{prd-slug}/PLAN.md

計画の構成

# Implementation Plan — {Feature Name}

## Branch / worktree
Branch name: `feat/{slug}`
Isolation mode: current checkout branch | separate worktree

## Phases

### Phase A — {name}
- [ ] Task 1 (file/module affected)
- [ ] Task 2

### Phase B — {name}
...

## Test plan
- Unit tests: what to cover
- E2E tests: critical paths
- Manual validation checklist

## Rollback notes
How to revert if something goes wrong.

ゲート 2 — 計画レビュー

計画を作成した後：

• 明示されていない前提を、承認済みの要件として扱わないでください。重要な受け入れ基準がまだ曖昧な場合は、まず PRD を修正してください。
• 次のように伝えます：「実装計画を docs/prds/{slug}/PLAN.md に用意しました。コーディングを始める前にレビューしてください。」
• 停止してください。ユーザーが OK と言うまで先に進まないでください。

---

フェーズ 3 — 実装

目標： ユーザーが選択した分離ブランチまたは worktree で機能を実装します。

セットアップ

フェーズ 1 の前に選択した分離モードで続行してください。ユーザーからモードの変更を求められない限り、2 つ目のブランチや worktree を作成しないでください。

実装中のルール

• CLAUDE.md の規約（命名規則、サーバー優先、any の禁止など）を厳守してください。
• 論理的なチェックポイント（スキーマ、API、UI、テスト）に分けて作業してください。各チェックポイントで pnpm typecheck && pnpm lint && pnpm test を実行し、チェックポイントの準備ができたことをユーザーに伝え、incu-way-prepare-pr を呼び出してコミットするよう提案してください。git add／git commit は自分で実行しないでください。
• PRD のすべての機能要件を、少なくとも 1 つのテストに対応付けてください。

（incu-way-prepare-pr で使用する）推奨コミットメッセージ形式

feat({slug}): {short description}

- Requirement FR-N implemented
- Tests added: {what}

---

フェーズ 4 — 検証

目標： ユーザーに引き渡す前に、PRD に照らして実装を検証します。

チェックリスト（ユーザーにテストを依頼する前に実行）

• PRD のすべての機能要件が実装されています。
• テスト計画のすべての項目が成功しています（pnpm test、pnpm test:e2e）。
• pnpm typecheck が終了コード 0 で完了します。
• pnpm lint が終了コード 0 で完了します。
• pnpm build が成功します。
• 既存テストにリグレッションがありません。
• PRD の未解決の質問が解決済みです（または保留として記録されています）。
• PRD のステータスが In Progress → Done（または Ready for Review）に更新されています。
• Snyk のコードスキャンで問題がありません（新たな問題なし）。
• Snyk の依存関係スキャンで問題がありません（新たな問題なし）。
• SonarQube のスキャンで問題がありません（新たな問題なし）。

セキュリティスキャン（Gate 3 の前に必須）

選択した作業場所を対象に、3 つのスキャンをすべて実行してください。この機能のコミットによって新たに発生したすべての問題を修正してください。main／develop に既存の問題は、修正が容易な場合を除き対象外です。各修正サイクルの後に再スキャンし、問題がなくなるまで続けてください。

Snyk — ソースコード（SAST）： snyk_code_scan MCP ツールを使用します。

path: <absolute path to the selected working location>
severity_threshold: low

Snyk — 依存関係（SCA）： snyk_sca_scan MCP ツールを使用します。

path: <absolute path to the selected working location>
severity_threshold: low
all_projects: true

フォルダーがまだ信頼済みでない場合は、同じパスを指定して先に snyk_trust を呼び出してください。

SonarQube：

bash run-sonar.sh

出力を確認し、この機能ブランチで変更されたファイルに付与された問題を調べてください。新しいコードによって発生した BLOCKER または CRITICAL の重大度の問題を修正してください。

snyk_trust、snyk_code_scan、snyk_sca_scan、または run-sonar.sh を利用できない場合は、不足しているツールと、失敗した正確なコマンドまたはツール名を docs/prds/{slug}/TESTING.md に記録し、そのツールをインストール／設定するか、利用可能な検証のみで続行するかをユーザーに確認してください。実行されていないスキャンを問題なしと報告してはいけません。

修正ループ：

1. 新たに指摘されたすべての問題に対処します（脆弱な依存関係のアップグレード、入力のサニタイズなど）。
2. pnpm typecheck && pnpm lint && pnpm test を実行し、問題が発生していないことを確認します。
3. 修正をコミットするために incu-way-prepare-pr を呼び出すよう提案します（fix({slug}): address snyk/sonar findings）。自分ではコミットしないでください。
4. 3 つのスキャンをすべて再実行します。
5. 3 つのスキャンすべてで新たな問題がゼロと報告されるまで繰り返します。

Gate 3 — ユーザーテスト

検証に合格した後：

• docs/prds/{slug}/TESTING.md に簡潔なテストガイドを作成します。
  • 機能の開始方法（URL、CLI コマンドなど）
  • 実行するシナリオの手順（正常系＋エッジケース）
  • 既知の制限事項または保留項目
• 「実装が完了し、検証されました。テストガイドは docs/prds/{slug}/TESTING.md にあります。テストして、結果をお知らせください。」と伝えます。
• ここで停止し、ユーザーからのフィードバックを待ちます。

---

フェーズ 5 — プルリクエストによるマージ

目標： レビュー済みの PR を通じて、機能を develop、続いて main に統合します。ブランチを直接マージしてはいけません。必ず PR を使用してください。

ブランチの流れ

feat/{slug}  →  develop  →  main
               (PR 1)      (PR 2)

PR 1 — feat/{slug} → develop

ユーザーによる検証が完了したら（Gate 3 通過後）、ブランチの準備ができたことを伝え、incu-way-prepare-pr を呼び出して feat/{slug} をプッシュし、develop への PR を作成するよう提案してください。自分でプッシュしたり、gh pr create を実行したりしないでください。これを行うスキルは incu-way-prepare-pr のみであり、ユーザーが依頼した場合に限り実行します。

incu-way-prepare-pr で使用する PR のタイトルと本文の推奨案：

Title: feat({slug}): {short feature name}

PR の本文には次の内容を含めてください：

• 概要： 実装した内容とその理由を説明する箇条書き 2～4 項目。
• PRD： docs/prds/{slug}/PRD.md へのリンク。
• テスト： docs/prds/{slug}/TESTING.md へのリンク。
• チェックリスト： typecheck ✅、lint ✅、tests ✅、build ✅、snyk-code ✅、snyk-deps ✅、sonarqube ✅、ユーザーによる検証 ✅。

PR を作成したら、ユーザーに PR の URL を共有してください。ここで停止してください。ユーザーが PR を承認するまで、マージしないでください。

PR 2 — develop → main

PR 1 が develop にマージされたら、再度 incu-way-prepare-pr を呼び出して、develop → main の PR を作成するよう提案してください。

incu-way-prepare-pr で使用する PR のタイトルと本文の推奨案：

Title: release: {slug} — {short feature name}

PR の本文には次の内容を含めてください：

• このリリースに含まれる機能や修正。
• 差分全体を確認できるよう、develop → feat の PR へのリンク。

PR を作成したら、ユーザーに PR の URL を共有してください。ここで停止してください。ユーザーが承認するまで、マージしないでください。

---

クイックリファレンス — ゲート

ゲート	トリガー	伝える内容	次に進む条件
1	PRD 作成済み	「PRD のドラフトを docs/prds/{slug}/PRD.md に作成しました。レビューしてください。」	ユーザーが OK と返答
2	計画作成済み	「実装計画を docs/prds/{slug}/PLAN.md に作成しました。レビューしてください。」	ユーザーが OK と返答
3	セキュリティスキャンに問題がなく、検証に合格	「実装が完了しました。テストガイドは docs/prds/{slug}/TESTING.md にあります。テストしてください。」	ユーザーからのフィードバック
4	ユーザーによる検証完了	PR feat→develop 用に incu-way-prepare-pr の実行を提案し、ユーザーが実行したら URL を共有	ユーザーによる PR の承認
5	PR 1 のマージ完了	PR develop→main 用に incu-way-prepare-pr の実行を提案し、ユーザーが実行したら URL を共有	ユーザーによる PR の承認

---

機能ごとのファイル構成

docs/prds/{prd-slug}/
  PRD.md        # Feature spec (Phase 1)
  PLAN.md       # Implementation plan (Phase 2)
  TESTING.md    # Testing guide (Phase 4)

---

やってはいけないこと

• Gate 1 を通過する前にコードを書かないでください。
• Gate 2 を通過する前に実装を開始しないでください。
• Gate 3 の後、ユーザーの承認なしに main へマージしないでください。
• ブランチを直接マージしないでください。変更がどれほど小さくても、必ず PR を経由してください。
• 要件の確認、PRD の作成、計画の策定の際に、クライアントの要件、暗黙のスコープ、または受け入れ基準を作り出さないでください。
• クライアントの期待、制約、または影響を受ける可能性のある領域が不明確になるほど依頼内容が曖昧な場合は、PRD を作成しないでください。
• PRD に記載されていない要件を作り出さないでください。不明な点があれば、Open Questions に追加し、Gate 1 で提示してください。
• 実装完了を宣言する前に pnpm typecheck && pnpm lint && pnpm test を実行する手順を省略しないでください。