linear-implement

Linear Issue の実装

概要

このスキルは、プロフェッショナルなソフトウェアエンジニアリングの手法に基づき、Linear の issue を実装するための包括的なワークフローを提供します。issue の分析から PR の作成まで、開発ライフサイクル全体を自動化し、テスト駆動開発、並行コードレビュー、体系的な検証によって品質を確保します。

このスキルを使用するタイミング

次の場合にこのスキルを使用します：

• ユーザーが Linear の issue ID（形式：TRA-9、DEV-123 など）を提示する
• ユーザーが Linear の issue の実装を依頼する
• ユーザーがコードレビューを含む、体系的な TDD アプローチを希望する
• ユーザーが issue から PR までのワークフローの自動化を必要としている

例：

• 「TRA-142 を実装して」
• 「DEV-89 の機能の実装を手伝って」
• 「Linear の issue ABC-456 に取り組んで」

基本ワークフロー

このスキルは、次の 14 ステップのプロセスに従います：

1. Linear の issue を取得 - Linear MCP 経由で issue の詳細をすべて取得
2. 追加のコンテキストを収集 - Obsidian、Sentry、GitHub を検索し、関連情報を確認
3. 進行中に変更 - 作業中であることを示すため、issue のステータスを更新
4. フィーチャーブランチを作成 - Linear が提案する git ブランチ名を使用
5. 分析と計画 - 要件を分解し、実装計画を作成
6. メモリに保存 - 追跡用に、計画をメモリーグラフに保存
7. 計画をレビュー - ユーザーの確認用に計画を提示
8. TDD による実装 - tdd-workflow スキルを呼び出し、テスト駆動開発を実施
9. 並行コードレビュー - parallel-code-review スキルを呼び出し、包括的に分析
10. フィードバックに対応 - code-review-implementer スキルを呼び出し、問題を体系的に修正
11. 検証 - すべてのテストとリンターがパスすることを確認
12. 意味のあるコミット - 意味のあるコミット履歴を作成
13. PR を作成 - Linear との連携を含む、包括的なプルリクエストを作成
14. 最終検証 - CI/CD パイプラインと Linear との連携を確認

ワークフローの実装詳細

ステップ 1：Linear の issue の詳細を取得する

Linear MCP ツールを使って issue の詳細をすべて取得します：

mcp__linear__get_issue(id: <issue-id>)

主な情報を抽出します：

• タイトルと説明
• 現在のステータスと優先度
• 提案された git ブランチ名（branchName フィールド）
• チームとプロジェクトのコンテキスト
• 添付ファイルまたは関連する作業
• ラベルと割り当てられたチームメンバー

ステップ 2：追加のコンテキストを収集する

計画を立てる前に、実装方針を決めるため、複数の情報源から関連するコンテキストを収集します。

Obsidian Vault を検索する

この issue に関連する既存のメモがないか検索します：

# Search by issue ID
Search Obsidian vault for: "TRA-142"

# Search by issue summary/keywords
Search Obsidian vault for: "<keywords from issue title/description>"

次の内容を探します：

• この機能について話し合った過去のミーティングメモ
• アーキテクチャ上の決定事項や技術メモ
• 類似の作業に関する関連実装メモ
• ユーザーリサーチや要件ドキュメント

Sentry のコンテキストを取得する（参照されている場合）

Linear の issue で Sentry の issue やエラートラッキングが参照されている場合：

mcp__sentry__get_issue(issue_id: <sentry-issue-id>)

Sentry から次の情報を抽出します：

• エラーのスタックトレースと発生頻度
• 影響を受けるユーザーと環境
• 関連するイベントとブレッドクラム
• 既存のコメントや担当者

このコンテキストは、次の理解に役立ちます：

• バグの根本原因
• 影響を受けるコードパス
• issue の発生頻度
• 考慮すべき環境要因

GitHub のコンテキストを取得する（参照されている場合）

Linear の issue で GitHub のプルリクエスト、issue、ディスカッションが参照されている場合：

# View PR details and discussion
gh pr view <pr-number>

# View PR comments and review threads
gh pr view <pr-number> --comments

# View issue details
gh issue view <issue-number>

# View issue comments
gh issue view <issue-number> --comments

GitHub から次の情報を抽出します：

• 過去の実装の試み
• レビューでのフィードバックや指摘された懸念
• 設計に関する議論や決定事項
• 関連するコード変更やコンテキスト

コンテキストの要約：

コンテキストを収集した後、次の内容を要約します：

• Obsidian で見つかった関連情報
• Sentry のエラー詳細（該当する場合）
• GitHub のディスカッションから得られた知見（該当する場合）
• このコンテキストが実装方針に与える影響

ステップ 3：課題を「進行中」にする

開発に着手したことがわかるように、課題のステータスを更新します。

1. 課題からチーム ID を特定します
2. mcp__linear__list_issue_statuses(team: <team-id>) を使用して「進行中」のステータスを取得します
3. mcp__linear__update_issue(id: <issue-id>, state: <in-progress-state-id>) を使用して課題を更新します

これにより、作業が始まったことをチームメンバーに知らせることができます。

ステップ 4：機能ブランチを作成する

一貫性を保つため、Linear が提案するブランチ名を使用します。

# Ensure on main and up-to-date
git checkout main
git pull origin main

# Get branch name from Linear's branchName field
BRANCH_NAME="<from Linear branchName field>"

# Create branch if new, or checkout if exists (idempotent)
git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"

# Verify correct branch
git branch --show-current

このパターンにより、次のことが実現します。

• 既存ブランチの再利用
• Linear が提案する命名規則の一貫性
• 冪等な操作（安全に再実行可能）
• 常に最新の main から作業

ステップ 5：ソリューションを分析し、計画する

課題を、実行可能な実装計画に分解します。

分析プロセス：

1. 課題の説明から具体的な要件を抽出します
2. 影響を受けるコンポーネントとシステムを特定します
3. テスト戦略を決定します（ユニット → 結合 → システム）
4. プロジェクトのパターンに沿った実装方針を計画します
5. 潜在的なリスクと依存関係を特定します

計画の内容：

• 目標：実装の目的を明確に記述します
• 要件：具体的な機能要件と技術要件を記載します
• アーキテクチャ：既存のコードベース（モデル、サービス、コントローラー）にソリューションをどう適合させるかを説明します
• テスト戦略：システムスペックを含む包括的なテストを計画します
• 実装手順：開発タスクを順序立てて列挙します
• 受け入れ基準：完了の定義を記載します

ステップ 6：計画をメモリに保存する

メモリ MCP ツールを使用して、実装計画を保存します。

mcp__memory__create_entities(entities: [
  {
    name: "Linear Issue <issue-id>",
    entityType: "implementation-plan",
    observations: [
      "Requirements: <requirements>",
      "Architecture: <architecture-decisions>",
      "Test Strategy: <test-approach>",
      "Status: planning-complete"
    ]
  }
])

これにより、次の内容を永続的に記録できます。

• 課題の背景と要件
• 実装方針とその理由
• 開発中の進捗
• 今後の作業に活かすための学び

ステップ 7：ユーザーと計画を確認する

確認を依頼するため、計画全体を提示します。

計画の提示内容：

• 実装する内容の概要
• 重要な技術的判断とその理由
• テスト戦略と想定されるカバレッジ
• 推定される複雑さと特定したリスク
• 明示的な確認依頼

ユーザーが選択できること：

• 承認して実装に進む
• 方針の変更を依頼する
• 要件や制約を追加する
• 確認事項について質問する

ステップ 8：テスト駆動開発で実装する

承認後、TDD ワークフロースキルを実行します。

Invoke the Skill tool with: tdd-workflow

TDD ワークフロースキルでは、次のことを徹底します。

• Red-Green-Refactor サイクル
• テストピラミッド戦略（ユニット → 結合 → システム）
• 実装より先にテストを作成すること
• システムスペックを含む包括的なテストカバレッジ

期待される成果：

• 新機能に対する完全なテストカバレッジ
• プロジェクトの POODR 原則に沿った実装
• 失敗する可能性のある操作に対する Result パターン
• クリーンで保守しやすいコード構造

ステップ 9：サブエージェントによる並列コードレビュー

実装後、並列コードレビュースキルを実行します。

Invoke the Skill tool with: parallel-code-review

これにより、専門のレビュサブエージェントが並列で起動します。

セキュリティレビュー：

• OWASP Top 10 の脆弱性
• マルチテナントのセキュリティ（ActsAsTenant の検証）
• XSS、CSRF、SQL インジェクションの防止
• 認証および認可の確認
• 機密データの取り扱い

Rails のベストプラクティスレビュー：

• POODR の原則（SRP、依存関係の管理、Tell Don't Ask）
• Rails 7 以降の規約
• N+1 クエリの防止
• ActiveRecord の最適化
• サービスオブジェクトのパターン
• Result パターンの使用

フロントエンドレビュー（該当する場合）：

• ViewComponent のベストプラクティス
• Tailwind CSS の規約
• StimulusJS のパターン
• アクセシビリティ（ARIA 属性）

出力：

• レビュー結果の統合レポート
• 重複を防ぐための判断記録
• 重大度と影響度に基づいて優先順位付けされたフィードバック

ステップ 10：レビューのフィードバックに対応する

コードレビュー実装スキルを呼び出します。

Invoke the Skill tool with: code-review-implementer

このスキルでは、フィードバックに体系的に対応します。

プロセス：

1. フィードバックを影響度と作業量に基づいて解析し、優先順位を付けます
2. よくあるリファクタリングパターンを特定します
3. テストで検証しながら、段階的に修正を実装します
4. 後方互換性を確保します
5. 必要に応じてドキュメントを更新します

アーキテクチャに関するフィードバックは必須です：

• コントローラーやモデルが多くの責務を担っている場合は、サービスオブジェクトを抽出します
• 失敗する可能性のある操作には Result パターンを適用します
• テスト容易性と保守性が向上するようにリファクタリングします
• 新しいサービスオブジェクトに対する包括的なスペックを追加します

注： アーキテクチャに関するフィードバックをすべて実装するまで、PR を作成しないでください。

ステップ 11：検証と品質保証

コミットを作成する前に、すべてのチェックが通ることを確認します。

検証手順：

# Run full test suite
bundle exec rspec

# Run linting (Standard, ERB, Brakeman)
bin/lint

# Fix any failures or warnings
# Verify system specs pass in clean environment

品質チェック：

• コードがプロジェクトの POODR 原則に従っている
• Result パターンが適切に使用されている
• セキュリティ上の脆弱性がない
• パフォーマンスへの影響が考慮されている（N+1 クエリがない）
• すべてのサブエージェントからのフィードバックに対応している
• テストカバレッジが十分である

リンティングに関する注意：

• Rails コードのみを扱っている場合は、Yarn の失敗を無視できます
• MigratedSchemaVersion と ContextCreatingMethods に関する警告は無害です
• 実際の違反には対応する必要があります（ファイルパスと行番号を確認してください）

ステップ 12：論理的なコミットを作成する

実装の経緯が伝わる、意味のあるコミットを作成します。

コミット戦略：

1. テストのコミット：新機能の失敗するテストを追加します
2. 実装のコミット：テストを通すためのコードを追加します
3. リファクタリングのコミット：コードの構造を改善します
4. セキュリティ修正のコミット：セキュリティレビューのフィードバックに対応します
5. パターン改善のコミット：OOP/Rails パターンに関する提案を実装します
6. ドキュメントのコミット：必要に応じてドキュメントを更新します

コミットメッセージの形式：

Present-tense summary under 50 characters

- Detailed explanation if needed (under 72 chars per line)
- Reference which review feedback was addressed
- Note any breaking changes or migration requirements

Linear issue: <Linear issue URL>
Implemented with Claude Code

適切な書式設定のために heredoc を使用します：

git commit -m "$(cat <<'EOF'
Add user notification service

- Extract notification logic from controller
- Apply Result pattern for error handling
- Add comprehensive RSpec tests with edge cases

Linear issue: https://linear.app/company/issue/TRA-142
Implemented with Claude Code
EOF
)"

ステップ 13：プルリクエストを作成する

Linear 連携を含む、包括的な PR を作成します。

PR 作成コマンド：

gh pr create --title "<concise-title>" --body "$(cat <<'EOF'
## Summary
- Concise bullet points of what was implemented
- Key technical decisions made

## Implementation Details
- Architecture approach and patterns used
- Services/models/controllers added or modified
- Database changes (if applicable)

## Testing Strategy
- Test coverage added (unit, integration, system)
- Edge cases covered
- Manual testing performed

## Code Review Process
- Security review findings and resolutions
- Rails best practices review findings and resolutions
- Performance considerations addressed

## Breaking Changes
[None or list any breaking changes]

## Linear Issue
Closes <Linear issue URL>

---
Implemented with Claude Code following TDD methodology with parallel code reviews.
EOF
)"

PR の説明に含める内容：

• 実装の概要
• 技術的なアプローチと主要な判断
• テスト戦略とカバレッジ
• コードレビューの指摘事項と対応内容
• 対応したセキュリティ上の考慮事項
• 破壊的変更や移行に関する注意事項
• 該当する場合は、スクリーンショットやデモ

Linear 連携：

• PR の本文に Closes <Linear-issue-URL> を含めます
• PR がマージされると、Linear が自動的に課題をリンクし、ステータスを更新します

ステップ 14：最終確認

PR の設定と完了状況を確認します。

最終チェック：

• ✅ CI/CD パイプラインが正常に起動した
• ✅ Linear の課題がリンクされ、更新されている
• ✅ CI 環境ですべてのテストが通っている
• ✅ コードレビュー担当者に通知されている
• ✅ ブランチ保護ルールを満たしている
• ✅ セキュリティレビューとパターンレビューが記録されている

完了サマリー： ユーザーにチェックリストを提示します。

• ✅ Linear の課題を分析し、計画を立てた
• ✅ TDD でソリューションを実装した
• ✅ 包括的なシステムスペックを追加した
• ✅ セキュリティレビューを完了した
• ✅ Rails/OOP パターンのレビューを完了した
• ✅ すべてのレビューのフィードバックに対応した
• ✅ すべてのテストとリンティングに合格した
• ✅ 論理的なコミット履歴を作成した
• ✅ Linear 連携を含む PR を作成した

他のスキルとの連携

このスキルは、複数の専門スキルを統括します。

tdd-workflow：

• Red-Green-Refactor サイクルを徹底します
• テストファースト開発を確実に実施します
• テストピラミッド戦略を案内します

parallel-code-review：

• セキュリティレビューと Rails レビューを並行して実行します
• 重複を避けるため、指摘事項を集約します
• 優先順位を付けたフィードバックを提示します

code-review-implementer：

• すべてのフィードバックに体系的に対応します
• よくあるリファクタリングパターンを適用します
• テストで修正を検証します

プロジェクト固有の規約

このスキルは、CLAUDE.md に記載されたプロジェクトのガイドラインに従います。

Rails のパターン：

• ビジネスロジックにはサービスオブジェクトを使用します
• 失敗する可能性のある処理には Result パターンを使用します
• POODR の原則（SRP、Tell Don't Ask、デメテルの法則）

マルチテナントのセキュリティ：

• ActsAsTenant による自動スコープ設定
• テナント分離の検証
• クエリで明示的にテナントのスコープを設定する必要はありません

テスト：

• shoulda-matchers を使用した RSpec
• ユーザーワークフローにはシステムスペックを使用します
• テスト対象のシステムをスタブ化しないでください
• リクエストスペックでの認証にはバックドアミドルウェアを使用します

コードスタイル：

• ユーザーに表示するすべてのテキストに i18n を使用します
• ブール値の代わりにタイムスタンプ列を使用します
• 静的な値には Postgres の enum を使用します
• 必須の環境変数には ENV.fetch を使用します

要件

Linear MCP 統合：

• Linear MCP サーバーを設定し、利用可能な状態にする必要があります
• 必須のツール：mcp__linear__get_issue、mcp__linear__update_issue など

Git リポジトリ：

• 現在のディレクトリが Git リポジトリである必要があります
• main ブランチが存在し、最新の状態である必要があります
• Git にユーザーの認証情報が設定されている必要があります

テストとリンティング：

• テストに bundle exec rspec を利用できる必要があります
• リンティングに bin/lint スクリプトを利用できる必要があります
• Ruby/Rails の開発環境が設定されている必要があります

GitHub CLI：

• gh CLI ツールがインストールされ、認証済みである必要があります
• PR 作成用にリポジトリが設定されている必要があります

スキル：

• tdd-workflow スキルが利用可能である必要があります
• parallel-code-review スキルが利用可能である必要があります
• code-review-implementer スキルが利用可能である必要があります

エラー処理

よくある問題と解決策：

Linear の課題が見つからない場合：

• 課題 ID の形式を確認します（例：tra-9 ではなく TRA-9）
• Linear MCP 統合が動作していることを確認します
• ユーザーがチーム／課題にアクセスできることを確認します

ブランチがすでに存在する場合：

• 想定どおりの動作です。ワークフローは既存のブランチをチェックアウトします
• 安全に作業を再開できるようにします
• ブランチがリモートと同期していることを確認します

テストまたはリンティングが失敗する場合：

• 失敗内容を確認し、PR を作成する前に修正します
• よくあるリンティングの問題：StandardRB、ERB Lint、Brakeman
• standardrb --fix をむやみに実行しないでください。変更内容を確認します

コードレビューで問題が指摘された場合：

• PR を作成する前に、アーキテクチャに関するフィードバックに必ず対応します
• 推奨されたとおりにサービスオブジェクトを抽出します
• 提案された箇所に Result パターンを適用します
• すべてのフィードバックに対応してから PR を作成します

ワークフローの例

ユーザーからのリクエスト：

Implement TRA-142

スキルの応答：

1. Linear から TRA-142 を取得します
2. 追加のコンテキストを収集します：
   • Obsidian の保管庫で「TRA-142」と関連キーワードを検索します
   • Sentry の課題詳細を取得します（Linear の課題で参照されている場合）
   • GitHub の PR ディスカッションを取得します（Linear の課題で参照されている場合）
3. 課題を「進行中」に更新します
4. ブランチ dg/tra-142-user-notification-service を作成します
5. 要件を分析し、収集したコンテキストを踏まえて計画を作成します
6. 計画をメモリーグラフに保存します
7. 計画を提示します：「Result パターンを使用して、ユーザー通知用の新しいサービスオブジェクトを作成します……」
8. ユーザーの承認を待ちます
9. 承認後、tdd-workflow スキルを呼び出します
10. 実装後、parallel-code-review スキルを呼び出します
11. レビューで次の点が指摘されます：「通知ロジックをサービスオブジェクトに抽出し、Result パターンを適用する」
12. フィードバックに対応するため、code-review-implementer スキルを呼び出します
13. 検証を実行します：bundle exec rspec ✅、bin/lint ✅
14. 適切なメッセージを付けて、論理的な単位でコミットを作成します
15. 詳細な説明と Linear へのリンクを含む PR を作成します
16. 完了チェックリストを提示します

最終出力：

• 実装が完了した機能ブランチ
• すべてのテストが成功
• すべてのリンティングが成功
• Linear と統合された詳細な PR
• PR のマージ時に課題が自動的に更新されます

ベストプラクティス

計画フェーズ：

• 要件を十分に理解するため、時間をかけます
• エッジケースとエラー条件を特定します
• マルチテナントへの影響を検討します
• 包括的なシステム仕様を計画します

実装フェーズ：

• TDD を厳守します。コードを書く前にテストを作成します
• コミットは小さく、論理的にまとめます
• 自己文書化されたコードを書きます
• ユーザーに表示するすべてのテキストに i18n を使用します

レビュー フェーズ：

• アーキテクチャに関するフィードバックにはすべて対応します
• 推奨されたリファクタリングを省略しません
• テストで修正を検証します
• パフォーマンスへの影響を検討します

PR の作成：

• 包括的な説明を記載します
• レビューでの指摘事項とその解決内容を文書化します
• 手動テストの内容を記載します
• Linear とのリンクが正しいことを確認します

品質ゲート：

• テストが失敗する状態で PR を作成しません
• リンティングエラーがある状態で PR を作成しません
• アーキテクチャに関するフィードバックに対応せずに PR を作成しません
• 検証手順を省略しません