linear-implement

Linear 実装

ワークフローの情報源として、リポジトリのルートを使用してください。以下を読み、従ってください。

• agents/implementer.md
• docs/implementer.md
• docs/agent-required-passes.md
• docs/superpowers-linear-persistence.md
• templates/linear-status-comment.md
• templates/linear-dashboard-comment.md
• schemas/linear-ai.status.v1.schema.yaml
• schemas/linear-ai.dashboard.v1.schema.yaml

最新の有効なマーク付き計画コメントから開始してください。製品の動作について、記載のない内容を作り上げないでください。作業がブロックされた場合は、マーク付きステータスコメントにまとめて質問を投稿し、適切な Linear の変更を適用または出力してください。

Claim Lock

docs/workflow.md の Claim Lock ルールに従ってください。開始時に issue を読み直してください。すでに in-use が付いていて、この実行が自身の claim の再開ではない場合は、変更を加えず、issue が claim 済みであることを報告して停止してください。それ以外の場合は、issue を claim する際に llm-active の適用と併せて in-use ラベルを追加してください。この実行が issue の作業を停止する際は、in-use を削除してください。対象となるのは、レビュー可能状態への引き継ぎ、ブロック、中断、失敗です。in-use は llm-* 名前空間の対象外であるため、llm-* ラベルの一括削除では削除されません。明示的に解除してください。

claim 時には、claimed_by: linear-implement と ISO 8601 形式の claimed_at を設定し、templates/linear-claim-block.md の linear-ai:claim ブロックも issue の説明に書き込んでください。解除時には claim ブロックを削除し、説明とラベルが一致するようにしてください。

実装前ゲート

コードを変更する前に、issue を claim した時点で、このゲートを一度実行してください。

1. 未解決の質問がないことを再確認してください。最新の実装準備完了プラン、その open_questions、accepted_unknowns、do_not_assume、および関連コードを読み直してください。重要な質問が未回答で、明示的に受け入れられていない場合、またはコードを読んで新たな曖昧さが見つかった場合は、推測したり作業を開始したりせず、llm-blocked を付けて、質問をまとめてブロックしてください。重要な未解決の質問がある状態で実装を開始してはいけません。
2. 未解決の質問がない場合は、実装準備完了プランを、独立して並行実行できるレーンに分解してください。リポジトリ、モジュール、チェックリスト項目、テスト対象、または検証レーンごとに分割し、互いに独立したファイルに触れるレーンは同時に実行できるようにしてください。Parallel Execution ルールに従い、各レーンを専用のサブエージェントに分離された worktree で割り当ててください。変更可能なファイルを共有する必要があるレーンのみ、逐次作業として確保してください。

自動モード

有効な実装準備完了プランが存在する場合は、自動モードで実装を進めてください。安全で元に戻せるローカルの調査、編集、テスト、検証は、再度許可を求めずに続行してください。これには、リポジトリのコンテキストの確認、リポジトリ内の TDD プランの作成、実装準備完了プランで指定または示唆されたファイルの編集、テストの更新、対象を絞った検証の実行、Linear のダッシュボードとステータスの証跡の更新、失敗したチェックの修正が含まれます。

次の作業が破壊的、取り消し不能、認証情報を必要とする、本番環境に影響する、スコープを大きく変更する、必要な権限が不足している、または大幅な手戻りにつながるような実質的な曖昧さがある場合に限り、質問するかブロックしてください。通常の実装上の判断で作業を中断するのではなく、ブロッカーに関する質問をマーク付きステータスコメントにまとめてください。

必要な権限コンテキスト

直接実装を開始する前に、必要な実装者権限コンテキストが有効であることを確認してください。セッションには、対象リポジトリへのワークスペース書き込みアクセス、リポジトリのパッケージマネージャーおよび検証コマンドを実行する権限、ダッシュボード／ステータスを変更するための Linear MCP 読み書きツール、ブランチ作成や PR 作業が対象に含まれる場合は Git／GitHub ツール、そして準備済みプランで必要とされるプロジェクト MCP ツールが必要です。

プロンプトごとに権限を確認する形で、通常の実装を開始しないでください。必要な実装者権限コンテキストをまず確立するか、引き継いでください。そうすれば、承認済みの安全で取り消し可能な作業を、確認を繰り返さずに進められます。そのコンテキストを確立できない場合は、安全な読み取り専用の調査に作業を絞るか、不足している権限を示してブロック状態を投稿／出力してください。通常の作業中に繰り返し確認を求めてはいけません。

Superpowers のタスクリストを Linear の課題説明ダッシュボードに反映するか、REQUIRED_LINEAR_MUTATIONS を出力するまでは、実装やコード変更を行わないでください。

課題説明内に、スキーマ linear-ai.dashboard.v1 に準拠したダッシュボードブロックを1つ維持してください。CLI 形式の状態記号、安定した準備済みプランのタスク ID、最上位タスクの状態変更ごとの last_checked 修復証拠を含めて、Superpowers のタスクリストをそのダッシュボードに反映してください。タスクを完了とする前に、実際のコード／作業ツリーの状態を確認してください。説明への書き込みができない場合に限り、代替手段としてダッシュボードコメントを使用してください。

並列実行

独立した実装作業には、サブエージェントを積極的に活用してください。同じ変更可能なファイルを必要としないレーンは、リポジトリ、モジュール、チェックリスト項目、テスト対象、レビュー担当、検証担当などに分けて、準備済みプランを並列化してください。

実装は、正しい課題用ワークツリー内にすでにあると証明できる場合を除き、必ず <repo>/.worktrees/<issue-id>-<optional suffix> にある隔離された課題用ワークツリーで行ってください。ブランチ上の作業ツリーに直接実装してはいけません。また、main や master に直接実装してはいけません。準備済みプランまたは Linear の課題に記載されたブランチ名や Git の参照は、課題用ワークツリーに紐づく Git の内部要素として扱い、主たる作業場所として扱わないでください。

コードを変更するサブエージェントを並列で動かす場合は、git worktree による分離を優先してください。コード変更を行う各レーンには、専用の一時レーン用ワークツリーまたは Git 参照を割り当て、対象を絞った検証を実行させ、変更ファイル、実行したテスト、残存リスク、ダッシュボードのタスク ID を報告させてください。複数のコード変更サブエージェントを同じ作業ツリーに配置してはいけません。

サブエージェントを割り当てる前に、そのレーンに必要なツールと権限があることを確認してください。具体的には、リポジトリの読み書きアクセス、パッケージマネージャー、テストコマンド、必要に応じて Linear MCP 読み書きツール、PR 作業が対象に含まれる場合は Git／GitHub ツール、さらに必要なプロジェクト MCP ツールを確認します。これらのツールや権限がない場合は、レーンを読み取り専用作業に絞るか、メインセッションで実行してください。

サブエージェントの作業は、差分をレビューし、競合を解決し、ダッシュボードのタスクリストを更新し、課題用ワークツリーで関連する検証を再実行してからのみ取り込んでください。

マージ後の取り込みと検証が済んだら、一時レーン用ワークツリーをクリーンアップしてください。一時レーン用ワークツリーは、永続的な課題用ワークツリーと区別して管理してください。一時レーン用ワークツリーを残す場合は、そのパス、ブランチ、担当者、理由をステータスコメントに記載してください。

実装レビューのループ

実装が完了したように見え、ローカルでの検証に合格したら、移行先を確認する前、および llm-review を適用する前に、docs/agent-required-passes.md に記載された必須の実装レビューループを実行します。独立したレビュー用サブエージェントを並列で実行します。必ず一般レビュー、リファクタリング／コードの臭い、バグハンター、セキュリティ、仕様／スコープの検証担当を含め、ランタイムが提供する専門分野のレビュー担当も追加します。その後、すべての指摘を修正するか、正当化し、各正当化の内容を指定のステータスコメントに記録して、収束するまでラウンドを繰り返します。課題で別の上限が明示されていない限り、ループの上限は5ラウンドです。各レビューラウンドの後に、ラウンド番号、実施したレビュー担当／観点、重要度別の指摘、修正した指摘、正当化した指摘、保留またはブロックされた指摘、再実行した検証、およびループを継続するか、収束したか、上限に達してブロックされたかを含むラウンドの概要を投稿または出力します。収束しないまま上限に達した場合は、ブロック状態を投稿します。その後、信頼度とテスト不足に関するセルフゲートを通過します。ループが収束し、両方のセルフゲートに合格するまで、実装は完了ではありません。

コミットと移行先のポリシー

実装と検証が完了したら、課題に別の引き継ぎ方法を明示する要件またはルールがない限り、デフォルトの統合手順を使用します。課題の作業ツリーをローカルの main ブランチにリベースし、レビュー可能な動作とロールバックの境界を維持できる最小限の数にスカッシュしてから、ローカルの main ブランチに統合します。

チケットが完了となるのは、コードが main ブランチに入った場合のみです。オープン中の PR だけではチケット完了には不十分です。課題で終端の手順として明示されている場合を除き、機能ブランチと PR はレビュー引き継ぎの状態です。

プッシュ、マージ、PR の作成、PR のレビュー可能状態への変更、llm-review の適用、またはレビュー可能な状態での引き継ぎを投稿する前に、移行先を確認します。

• 完了の場合はデフォルトブランチ（main または master）に統合する
• 課題でその引き継ぎ方法が明示されている場合に限り、PR を作成せずに機能ブランチを作成または更新する
• 課題でその引き継ぎ方法、または main に統合する前の人間によるレビューが明示されている場合に限り、PR を伴う機能ブランチを作成または更新する

回答を final_destination に main、master、feature_branch、または feature_branch_pr として記録します。回答がない、曖昧である、または undecided のままである場合は、llm-blocked または REQUIRED_LINEAR_MUTATIONS を出力して停止します。計画、ブランチ名、既存の課題用作業ツリー、または既存のドラフト PR から推測してはいけません。

スカッシュするコミット数は最小限にします。細かな編集ごとに分割したり、無関係な変更をまとめて単一のコミットにしたりせず、レビュー可能な動作またはリスクの境界ごとに分割します。

Conventional Commit スタイルでセマンティックバージョニングの構文を使用し、すべてのコミットの件名に Linear の課題 ID を含めます。例：

feat(HCL-123): add dashboard persistence
fix(HCL-123): repair status extraction
test(HCL-123): cover dashboard validation

Linear のマジックワードによるリンク

末尾にマジックワードと課題 ID を付けて Linear の課題に関連付けると、Linear が自動でリンクし、ステータスを更新します（プッシュ／オープン時に「進行中」、変更がデフォルトブランチに到達すると「完了」）。

• PR を使うフィーチャーブランチの宛先：PR の説明に、末尾のマジックワードと課題 ID を記載します。例：Fixes HCL-123（複数の課題の場合：Fixes HCL-123, HCL-124）。マジックワードが機能するのは PR のタイトルまたは説明のみで、PR コメントでは機能しません。
• main／master へ直接反映する宛先：上記の Conventional Commit の件名に加えて、コミットメッセージ本文に Fixes HCL-123 の行を追加します。PR を使わないフィーチャーブランチは、課題で明示的に要求されている場合に限り、引き継ぎ時の例外として認められます。
• クローズ用マジックワード：close/closes/closed/closing、fix/fixes/fixed/fixing、resolve/resolves/resolved/resolving、complete/completes/completed/completing、implements/implemented/implementing。Fixes を推奨します。Conventional Commit の件名には、読みやすさとコミット証跡によるクローズ処理のために (HCL-123) のスコープを残します。Linear の自動処理をトリガーするのはマジックワードです。
• クローズ用マジックワードはマージ時に課題を「完了」にするため、linear-close は検証と最終処理を実行します。課題がすでに「完了」であっても許容し、証跡の検証、ダッシュボードの更新、クローズ処理コメントの投稿、llm-* と in-use の削除を行います。

ステータスコメントに最終コミット一覧と選択した宛先を記載してください。

レビュー準備完了として引き継ぐ前に、最終的な宛先が明示的に選択されていること、一時的なレーンのワークツリーがクリーンアップされていること、課題のワークツリーのクリーンアップ状態が「クリーンアップ済み」または「意図的に保持」と明記されていることを確認してください。

Linear MCP 契約

利用可能な場合は、次の Linear MCP ツールを使用してください。

• get_issue - 現在の課題、ラベル、ステータス、ブランチのメタデータを読み取ります。
• list_comments - 作業に着手する前に、最新のマーク付き計画コメントとステータスコメントを探します。
• save_comment - マーク付きの実装ステータス、質問、ブロッカー、レビュー準備完了の証跡を投稿します。
• save_issue - llm-active、llm-blocked、llm-review を適用し、他の llm-* ラベルを削除し、着手時に in-use の要求を追加して停止時に削除し、課題の説明のダッシュボードを更新し、書き込みが可能な場合はステータスを更新します。

課題がサブ課題の場合は、同じ最終処理で docs/workflow.md の親課題とサブ課題に関するルールを適用してください。llm-active の場合は親課題を llm-active にして「進行中」に移します。llm-blocked の場合は、そのルールに従って親課題の状態を反映させます。親課題の in-use は要求しないでください。

ステータスコメントと課題説明のダッシュボードは、次のコマンドで検証してください。

scripts/validate_marked_comments.ts --description <issue-description-file> <status-comment-file>

llm-review を適用する、またはレビュー準備完了とする前に、次のハード引き継ぎゲートを実行してください。

scripts/verify_handoff.ts --issue-id <ISSUE-ID> --status <status-comment-file> --description <issue-description-file>

Linear メタデータのスナップショットが利用可能な場合は、次のコマンドでラベルを検証してください。

scripts/validate_marked_comments.ts --metadata <metadata.json> <status-comment-file>

エージェントが利用できるローカルの JavaScript パッケージマネージャーまたはランタイムを使用してください。Bun は .ts スクリプトを直接実行できます。Node／npm／pnpm／yarn の環境では、tsx などの TypeScript ランナーを介して実行してください。

Linear MCP の書き込みツールが利用できない場合は、ラベル、ステータス、コメントが更新されたと主張しないでください。マーク付きのステータスコメントとラベル／ステータスの変更内容を正確に記載した REQUIRED_LINEAR_MUTATIONS を出力してください。

ステップ完了時の引き継ぎ

実装でタスクの完了、ブロッカーの更新、検証パス、またはレビュー準備完了の状態になったら、変更内容、検証の証拠、現在の Linear のラベル／ステータス、該当する場合は PR またはパッチへのリンク、および推奨する次のステップを報告してください。ブロッカー、放棄、レビュー準備完了の引き継ぎ時、または安全で明確なタスクが残っていない場合は、ほかに追加することがないか尋ねてください。通常のタスク完了後は、続行するかどうかを尋ねないでください。作業が残っており、次のステップが安全で明確な場合は、次の未チェックのタスク、検証、またはレビューへの引き継ぎへ進んでください。

ブロッカー、放棄、またはレビュー準備完了の引き継ぎ時に、追加することがないと回答された後は、推奨する次のスキルに進むかどうかをユーザーに尋ねてください。推奨する次のスキルを明示し、ユーザーの確認を待ってください。自動で実行してはいけません。

次の回答形式を使用してください。

• 現在のフェーズ
• 変更内容
• 証拠
• 不足している証拠
• 未解決のブロッカー
• 推奨する次のステップ
• 推奨する次のスキル
• 質問：次に進む前に、ほかに追加することはありますか？
• 質問：推奨する次のスキルに進みますか？

実装が検証済みで、該当する場合は PR へのリンクがあり、課題に implementation_status が review_ready、blocked、active、または abandoned に設定されたステータスコメントが付いている場合は、終了してください。