GitHub・Linear・Claude 連携運用ルール¶

1. 概要¶

本ドキュメントは、GitHub・Linear・Claude の3サービスを連携させるための運用ルールを定める。

各サービスの役割¶

基本方針¶

• Linear主導: すべての作業はLinear Issueから始まる。GitHub Issueは実装フェーズでのPR紐付け用として補助的に使用する
• 一元管理: 事業計画プロジェクト（リポジトリなし）もLinearで統一管理する
• トレーサビリティ: アイデア → Issue → ブランチ → PR → マージまで一貫して追跡可能にする

2. 組織構造マッピング¶

対応関係¶

Linear Team 構成¶

技術領域ごとにTeamを分割する。

原則: 1つのLinear Projectが複数リポジトリにまたがる場合は、Initiativeでグルーピングする。

3. プロジェクト種別・Initiative の区別規則¶

種別一覧と視覚的区別¶

Initiative と Project を一目で区別するため、絵文字＋プレフィックスを併用する。

具体例¶

【Initiative】
  🎯[INIT] 認証基盤リニューアル
  🎯[INIT] 決済機能拡張

【コードProject】
  my-api          (icon: GitHub)
  my-web          (icon: GitHub)
  my-infra        (icon: GitHub)

【事業計画Project】
  事業戦略 2026    (icon: 🚀)
  セキュリティ監査  (icon: 🛡️)

Initiative の命名規則¶

• 必ず 🎯[INIT] を名前の先頭に付与する
• Initiative は複数の Project をまたぐ戦略テーマを表す
• descriptionに紐付くProjectの一覧と目的を記載する

コードProject のルール¶

• Linear ProjectアイコンはGitHubアイコンを使用する（必須）
• Project descriptionの冒頭に GitHub: https://github.com/<org>/<repo-name> を記載する
• Project名はリポジトリ名と一致させるか、人間可読な名称にしてdescriptionでリポジトリを明記する

事業計画Project のルール¶

• 内容に応じた絵文字をアイコンに使用する（GitHubアイコンは使用禁止）
• Project descriptionに「本プロジェクトはコードリポジトリを持たない事業計画プロジェクトです」と明記する

Project アイコン例¶

用途	アイコン例
コードProject	GitHubアイコン
セキュリティ関連
インフラ・構築関連
監視・分析関連
新規事業・戦略関連
ドキュメント関連

4. Issueライフサイクル¶

4.1 ステータス遷移¶

Backlog → Todo → In Progress → In Review → Done
                                             ├→ Canceled
                                             └→ Duplicate

4.2 カテゴリラベル（排他・必須）¶

すべてのIssueに以下のいずれか1つを必ず付与する。

カテゴリラベルの付与を強制する仕組み¶

Linear にはラベル付与を強制する組み込み機能がないため、以下の2つを併用して「ラベルなし」の発生を防ぐ。

1. Issue作成は原則Claude経由とする

Claudeは「7.1 Claudeの関与ルール」に従い、Issue作成時にカテゴリラベルを必ず付与する。人間が直接Issueを作成するケースを最小限にすることで、ラベル漏れを抑制する。

2. Linear Automationでデフォルトラベルを自動付与する

人間が直接Issueを作成した場合に備え、Linear Automationを設定する。

• 設定場所: Team Settings → Automations
• ルール: Issue作成時にカテゴリラベル（cat:*）が未付与の場合、自動で cat:idea を付与する
• 各Teamに同じAutomationを設定すること

これにより、カテゴリラベルが付いていないIssueは存在しない状態を維持できる。cat:idea はもっとも工数の少ない（＝安全な）デフォルトであるため、誤分類のリスクも低い。

4.3 カテゴリとステータスの関係¶

4.4 GitHub Issue連携タイミング¶

1. Linear Issueが cat:execution かつコードProjectに属する場合、ステータスがTodoに移行した時点でGitHub Issueを作成する
2. GitHub Issue作成後、Linear Issueのタイトルに [repo-name#番号] を追記する
3. GitHub Issue側のbodyにLinear IssueへのURLを記載する

5. ラベル体系¶

5.1 カテゴリラベル（排他・必須）¶

前述の cat:idea / cat:research / cat:execution。1つのIssueに1つだけ付与する。

5.2 タイプラベル（排他）¶

5.3 実行者ラベル（複数可）¶

5.4 優先度¶

Linearの組み込み優先度フィールドをそのまま使用する。ラベルでは管理しない。

6. 命名規則¶

6.1 Linear Issue タイトル¶

GitHub Issue紐付け前：

タイトル（内容を端的に表す）

GitHub Issue紐付け後：

[repo-name#123] タイトル

例：[my-app#45] ユーザー検索APIのページネーション対応

• リポジトリ名は短縮名を使用（Organization名は省略）
• cat:idea および cat:research はGitHub番号不要

6.2 GitHub Issue タイトル¶

[LINEAR-ID] タイトル

例：[BE-1234] ユーザー検索APIのページネーション対応

• Linear IDはチームキー + 番号（例：FE-123, BE-456, INF-789）
• bodyの冒頭にLinear IssueのURLを記載する

6.3 ブランチ命名規則¶

<type>/<LINEAR-ID>-<short-description>

例：feat/BE-1234-user-search-pagination

6.4 PR タイトル¶

<type>(<scope>): <description> [LINEAR-ID]

例：feat(api): add pagination to user search [BE-1234]

• Conventional Commits 準拠
• scopeは任意（モジュール名やディレクトリ名）
• 末尾にLinear IDを付与する

6.5 コミットメッセージ¶

<type>(<scope>): <description>

<optional body>

Ref: LINEAR-ID

例：

feat(api): add cursor-based pagination to /users endpoint

Replaces offset-based pagination with cursor-based approach.
Adds `after` and `before` query parameters.

Ref: BE-1234

7. Claudeの関与ルール¶

7.1 Linear Issue 作成¶

Claudeが作成するIssueの必須フィールド：

• タイトル（命名規則に従う）
• カテゴリラベル（cat:idea / cat:research / cat:execution）
• タイプラベル（Bug / Feature / Improvement）
• Team（適切な技術領域チーム）
• Project（該当するProject）
• 優先度（判断可能な場合）
• Description（背景、目的、完了条件を記載）

7.2 GitHub Issue 作成¶

Claudeが GitHub Issue を作成する条件：

1. Linear Issueが cat:execution である
2. 対象ProjectがコードProject（GitHub連携あり）である
3. Linear Issueのステータスが Todo 以上である

作成時のルール：

• タイトルは [LINEAR-ID] タイトル 形式
• bodyにLinear IssueへのURLを記載する
• 作成後、Linear Issueタイトルに [repo-name#番号] を追記する

7.3 PR 作成ルール¶

1. 必ず対応するGitHub Issueが存在すること（なければ先に作成する）
2. ブランチ命名規則に従うこと
3. PRタイトルは命名規則に従うこと
4. PR bodyに以下を含めること：
5. Closes #<GitHub-Issue番号>（自動クローズ用）
6. Linear: LINEAR-ID（Linear連携用）
7. 変更概要
8. テスト計画
9. Draft PRとして作成し、レビュー準備完了後にReady for Reviewに変更する

7.4 ステータス更新タイミング¶

8. 全体構成図¶

8.1 3サービスの関係¶

graph TB
    subgraph Linear["Linear（計画の中心）"]
        LW["Workspace"]
        LT_FE["Team: Frontend"]
        LT_BE["Team: Backend"]
        LT_INF["Team: Infra"]
        LP_CODE["Project（コード）\nicon: GitHub"]
        LP_BIZ["Project（事業計画）\nicon: 絵文字"]
        LI["Issue"]
        LC["Cycle"]
        LINIT["Initiative"]

        LW --- LT_FE & LT_BE & LT_INF
        LT_FE & LT_BE & LT_INF --- LP_CODE & LP_BIZ
        LP_CODE & LP_BIZ --- LI
        LC --- LI
        LINIT --- LP_CODE & LP_BIZ
    end

    subgraph GitHub["GitHub（コード管理）"]
        GO["Organization"]
        GR["Repository"]
        GI["Issue"]
        GP["Pull Request"]
        GB["Branch"]

        GO --- GR
        GR --- GI & GP
        GP --- GB
    end

    subgraph Claude["Claude（AIアシスタント）"]
        C_PLAN["企画・アイデア出し"]
        C_DESIGN["設計・調査"]
        C_IMPL["実装・PR作成"]
        C_REVIEW["レビュー支援"]
    end

    LW ===|"1:1"| GO
    LP_CODE ===|"1:1"| GR
    LI -->|"cat:execution のみ"| GI
    GI --- GP

    C_PLAN -->|"cat:idea 作成"| LI
    C_DESIGN -->|"cat:research 作成"| LI
    C_IMPL -->|"GitHub Issue 作成"| GI
    C_IMPL -->|"PR 作成"| GP
    C_REVIEW -->|"レビューコメント"| GP

    style Linear fill:#f0f4ff,stroke:#5E6AD2,stroke-width:2px
    style GitHub fill:#f0fff0,stroke:#238636,stroke-width:2px
    style Claude fill:#fff8f0,stroke:#D97706,stroke-width:2px

8.2 Issueライフサイクル¶

flowchart TD
    START(("アイデア発生")) --> CREATE_IDEA

    subgraph IDEA["フェーズ1: アイデア（工数なし）"]
        CREATE_IDEA["Linear Issue 作成\nlabel: cat:idea\nstatus: Backlog"]
        IDEA_EVAL{"評価"}
        CREATE_IDEA --> IDEA_EVAL
        IDEA_EVAL -->|"破棄"| CANCELED["Canceled"]
        IDEA_EVAL -->|"調査が必要"| PROMOTE_R
        IDEA_EVAL -->|"即実行可能"| PROMOTE_E
    end

    subgraph RESEARCH["フェーズ2: 調査（低工数）"]
        PROMOTE_R["ラベル変更: cat:research\nstatus: Todo"]
        R_WIP["status: In Progress\n調査実施"]
        R_DONE["status: Done\n調査完了"]
        R_NEXT{"実装に進む？"}
        PROMOTE_R --> R_WIP --> R_DONE --> R_NEXT
        R_NEXT -->|"No"| R_END["完了（調査のみ）"]
        R_NEXT -->|"Yes"| NEW_EXEC
    end

    subgraph EXEC["フェーズ3: 実行（工数あり）"]
        PROMOTE_E["ラベル: cat:execution\nstatus: Backlog"]
        NEW_EXEC["新Issue作成\nlabel: cat:execution"]
        E_TODO["status: Todo\n+ GitHub Issue 作成"]
        E_WIP["status: In Progress\nブランチ作成・実装"]
        E_REVIEW["status: In Review\nPR 作成"]
        E_DONE["status: Done\nPR マージ"]

        PROMOTE_E --> E_TODO
        NEW_EXEC --> E_TODO
        E_TODO --> E_WIP --> E_REVIEW --> E_DONE
    end

    style IDEA fill:#f3f4f6,stroke:#9CA3AF,stroke-width:2px
    style RESEARCH fill:#fef3c7,stroke:#F59E0B,stroke-width:2px
    style EXEC fill:#d1fae5,stroke:#10B981,stroke-width:2px

8.3 組織構造マッピング¶

graph LR
    subgraph LIN["Linear Workspace"]
        direction TB
        INIT1["🎯[INIT] 認証基盤リニューアル"]
        INIT2["🎯[INIT] 決済機能拡張"]

        T_FE["Team: Frontend"]
        T_BE["Team: Backend"]
        T_INF["Team: Infra"]

        P1["Project: my-web\nicon: GitHub"]
        P2["Project: my-api\nicon: GitHub"]
        P3["Project: my-infra\nicon: GitHub"]
        P4["Project: 事業戦略 2026\nicon: 🚀"]
        P5["Project: セキュリティ監査\nicon: 🛡️"]

        INIT1 -.-|"グループ化"| P1 & P2 & P3
        INIT2 -.-|"グループ化"| P2

        T_FE --- P1
        T_BE --- P2
        T_INF --- P3
        T_BE --- P4
        T_INF --- P5
    end

    subgraph GH["GitHub Organization"]
        direction TB
        R1["Repo: my-web"]
        R2["Repo: my-api"]
        R3["Repo: my-infra"]
        NONE1["（対応リポジトリなし）"]
        NONE2["（対応リポジトリなし）"]
    end

    P1 -->|"1:1"| R1
    P2 -->|"1:1"| R2
    P3 -->|"1:1"| R3
    P4 -.->|"連携なし"| NONE1
    P5 -.->|"連携なし"| NONE2

    style LIN fill:#f0f4ff,stroke:#5E6AD2,stroke-width:2px
    style GH fill:#f0fff0,stroke:#238636,stroke-width:2px

付録: 運用チェックリスト¶

新プロジェクト作成時¶

• Linear Projectを作成する
• コードProjectの場合：GitHubリポジトリを作成し、ProjectアイコンをGitHubアイコンに設定する
• コードProjectの場合：descriptionにリポジトリURLを記載する
• 事業計画Projectの場合：適切な絵文字アイコンを設定し、descriptionに「リポジトリなし」を明記する
• 担当Teamを設定する
• 該当するInitiativeに紐付ける（該当する場合）

Issue作成時¶

• カテゴリラベル（cat:idea / cat:research / cat:execution）を1つ付与する
• タイプラベル（Bug / Feature / Improvement / Design）を付与する
• 適切なProjectに割り当てる
• cat:execution かつコードProjectの場合、Todo移行時にGitHub Issueを作成する
• GitHub Issue作成後、Linearタイトルに [repo-name#番号] を追記する

PR作成時¶

• ブランチ名が <type>/<LINEAR-ID>-<description> 形式であること
• PRタイトルが <type>(<scope>): <description> [LINEAR-ID] 形式であること
• PR bodyに Closes #<番号> と Linear: LINEAR-ID を記載すること
• Linear Issueのステータスを In Review に更新すること