Linear

Linear

Linear で課題、プロジェクト、チームを管理するためのツールとワークフローです。

---

⚠️ ツールの利用可否（最初にお読みください）

このスキルは複数のツールバックエンドに対応しています。利用可能なものを使用してください。

1. MCP ツール（mcp__linear） - ツールセットで利用可能な場合に使用します
2. Linear CLI（linear コマンド） - Bash 経由で常に利用できます
3. ヘルパースクリプト - 複雑な操作に使用します

MCP ツールが利用できない場合は、Bash 経由で Linear CLI を使用してください。

# View an issue
linear issues view ENG-123

# Create an issue
linear issues create --title "Issue title" --description "Description"

# Update issue status (get state IDs first)
linear issues update ENG-123 -s "STATE_ID"

# Add a comment
linear issues comment add ENG-123 -m "Comment text"

# List issues
linear issues list

「MCP ツールが利用できない」ことを障害として報告しないでください。代わりに CLI を使用してください。

---

🔐 セキュリティ：Varlock との連携

重要：API キーをターミナルの出力や Claude のコンテキストに絶対に表示しないでください。

安全なコマンド（常に使用）

# Validate LINEAR_API_KEY is set (masked output)
varlock load 2>&1 | grep LINEAR

# Run commands with secrets injected
varlock run -- npm run query -- "query { viewer { name } }"

# Check schema (safe - no values)
cat .env.schema | grep LINEAR

安全でないコマンド（絶対に使用しない）

# ❌ NEVER - exposes key to Claude's context
linear config show
echo $LINEAR_API_KEY
printenv | grep LINEAR
cat .env

新しいプロジェクトのセットアップ

1. @sensitive アノテーションを付けて .env.schema を作成します。

   # @type=string(startsWith=lin_api_) @required @sensitive
   LINEAR_API_KEY=
   

2. LINEAR_API_KEY を .env に追加します（このファイルは絶対にコミットしないでください）。

3. 環境変数を使用するように MCP を設定します。

   {
     "mcpServers": {
       "linear": {
         "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" }
       }
     }
   }
   

4. 操作の前に varlock load を使用して検証します。

---

クイックスタート（初めて利用する方へ）

1. セットアップを確認する

セットアップチェックを実行して、設定を確認します。

npm run setup

次の項目を確認します。

• LINEAR_API_KEY が設定され、有効であること
• @linear/sdk がインストールされていること
• Linear CLI が利用可能であること（任意）
• MCP が設定されていること（任意）

2. API キーを取得する（必要な場合）

セットアップで API キーが見つからないと報告された場合：

1. ブラウザーで Linear を開きます。
2. Settings（歯車アイコン）-> Security & access -> Personal API keys に移動します。
3. Create key をクリックし、キー（lin_api_ で始まります）をコピーします。
4. 環境に追加します。

# Option A: Add to shell profile (~/.zshrc or ~/.bashrc)
export LINEAR_API_KEY="lin_api_your_key_here"

# Option B: Add to Claude Code environment
echo 'LINEAR_API_KEY=lin_api_your_key_here' >> ~/.claude/.env

# Then reload your shell or restart Claude Code

3. 接続をテストする

すべてが正常に動作することを確認します。

npm run query -- "query { viewer { name } }"

Linear に登録されている自分の名前が表示されます。

4. よく使う操作

# Create issue in a project
npm run ops -- create-issue "Project" "Add rate limiting to auth endpoints" "Auth endpoints have no rate limiting, allowing brute-force attacks. Add configurable limits per endpoint with 429 responses when exceeded."

# Update issue status
npm run ops -- status Done ENG-123 ENG-124

# Edit issue title or description (fix typos, expand bodies)
npm run ops -- update-issue ENG-123 description --file /tmp/description.md --force
npm run ops -- update-issue ENG-123 title "Corrected title" --force
echo "New body from pipeline" | npm run ops -- update-issue ENG-123 description --stdin --force
npm run ops -- update-issue ENG-123 description "Short inline update" --strict=false

# Create sub-issue
npm run ops -- create-sub-issue ENG-100 "Sub-task" "Details"

# Update project status
npm run ops -- project-status "Phase 1" completed

# Show all commands
npm run ops -- help

詳細については、プロジェクト管理コマンドを参照してください。

---

Issue Creation Checklist (Required)

Linear のイシューを作成するときは、ユーザーから指定がなくても、必ず以下の 3 つの手順を完了してください。

1. 受け入れ条件を含む詳細な説明。 すべてのイシューの説明には、具体的でテスト可能なチェック項目を 2 つ以上含む ## Acceptance Criteria セクションが必須です。標準テンプレートと記入済みの完全な例については、docs/issue-template.md を参照してください。CLI の create-issue / create-sub-issue は、この構成を満たさない説明を拒否します。MCP の save_issue を呼び出す場合は、先に npm run ops -- validate-description --stdin で下書きを検証してください（以下を参照）。ユーザーがタイトルしか提示していない場合は、以下のテンプレートを使って説明を作成してください。

   詳細度 — デフォルトでは 6 セクションの完全なテンプレートを使用します。 ユーザーの表現から簡潔さが明らかに求められている場合（「quick issue」、「one-liner」、「just the AC」、「brief」、「terse」、「minimum」、「short」）を除き、本文は Context → Problem → Proposal → Acceptance Criteria → Verification → Out of scope の構成にしてください。120 文字／2 項目という基準は、バリデーターが拒否する最低条件であり、レビュー担当者が求める水準ではありません。ユーザーがタイトルしか提示していない場合は、完全なテンプレートに沿って詳細な本文を作成し、最低条件だけの内容で提出するのではなく、追加質問をしてください。些細な変更（誤字修正、1 行の設定変更など）では、受け入れ条件からテスト方法が明白な場合に限り、Problem を Context にまとめ、Verification を省略して構いません。デフォルトではなく、意図的に構成を簡略化してください。

   ## Context
   **Title:** <title>
   
   <What is changing and why. 2-4 sentences. Link prior issues, docs, or incidents that motivate this.>
   
   ## Problem
   <What specifically is broken, missing, or insufficient today. Name the file, flow, or behavior.>
   
   ## Proposal
   <What you intend to do about it. High-level approach, not implementation line-by-line.>
   
   ## Acceptance Criteria
   - [ ] <Concrete, testable outcome>
   - [ ] <Concrete, testable outcome>
   
   ## Verification
   <How the AC will actually be checked. Manual steps, test command, or review instruction.>
   
   ## Out of Scope
   - <What this issue does NOT cover — redirect to the follow-up or explain why it's deferred>
   

   npm run ops -- create-issue --template を使うと、必要に応じてテンプレートを表示できます。記入済みの完全な例については、docs/issue-template.md を参照してください。

2. ラベル。 ラベル分類に従って適用してください。

   • 種類ラベルは必ず 1 つ（feature、bug、refactor、chore、spike）
   • ドメインラベルは 1～2 個（backend、frontend、security、infrastructure など）
   • 該当する場合はスコープラベル（blocked、breaking-change、tech-debt）

3. プロジェクトの割り当て。 コンテキスト（進行中のスプリント、機能領域、またはユーザーの指示）に基づき、適切なプロジェクトに割り当ててください。該当するプロジェクトが明らかでない場合は、ユーザーに確認してください。バッチ／サブエージェントのコンテキストでは、親イシューに関連付けられたプロジェクト、またはデフォルトのイニシアチブプロジェクトを使用してください。

既存のイシューを更新する場合は、既存のラベルとプロジェクトを維持し、不足しているラベルの追加または誤った割り当ての修正のみを行ってください。

MCP ツール。 mcp__linear__save_issue（または MCP のイシュー作成ツール）を呼び出す前に、下書きの説明を validate-description --stdin に渡し、終了コードが 0 の場合に限り save_issue を呼び出してください。

echo "$DRAFT_BODY" | npm run ops -- validate-description --stdin
# exit 0 → save_issue を呼び出しても安全です
# exit 5 → 説明を修正し、再度パイプに渡して確認してください

CLI の create-issue / create-sub-issue では、すでにこの検証が必須になっています。MCP にはサーバー側のゲートがないため、この事前チェックと事後の npm run lint-issues 監査だけが、MCP 経由の操作に対する強制手段です。ファイルに保存した長い下書きには、--stdin の代わりに --file <path> を使用してください。

詳細度と検証は別物です。 検証の合格（終了コード 0）は、120 文字／2 つの受け入れ条件という最低基準を満たしたことを示すだけです。ユーザーが明示的に簡潔さを求めていない限り、本文は 6 セクションの完全なテンプレート（Context → Problem → Proposal → AC → Verification → Out of Scope）に沿って構成してください。上記の箇条書き #1 を参照してください。

強制の仕組み。 CLI と SDK の経路には強制ゲートがあります。MCP の経路は指示と監査によって運用されます。save_issue をインターセプトする PreToolUse フックは検討されましたが、Claude Code がランタイムの場合にしか動作せず、ユーザーごとのインストールが必要で、ペイロードの形式もハーネスのバージョンに依存するため、採用されませんでした。指示レイヤーの逸脱を事後に検出するには、ローカルまたは CI で npm run lint-issues -- --since 24h を実行してください。

---

Project Planning Workflow

Issue Creation Checklist を参照してください。すべてのイシューで、説明、ラベル、プロジェクトの割り当てが必須です。

最初から正しいプロジェクトに課題を作成する

ベストプラクティス：新しいフェーズや取り組みを計画する際は、1 回の計画セッションでプロジェクトとその課題をまとめて作成します。課題を何でも入れるプロジェクトに作成し、後から移動するのは避けてください。

推奨ワークフロー

1. まずプロジェクトを作成します：

   npm run ops -- create-project "Phase X: Feature Name" "My Initiative"
   

2. プロジェクトの状態を Planned に設定します：

   npm run ops -- project-status "Phase X: Feature Name" planned
   

3. プロジェクトに直接課題を作成します（--template を使って正規のテンプレートを先に表示するか、ヒアドキュメントで複数行の説明を渡します）：

   # Print the template to seed your description
   npm run ops -- create-issue --template
   
   # Create the issue with a template-shaped description
   npm run ops -- create-issue "Phase X: Feature Name" "Parent task" "$(cat <<'EOF'
   ## Context
   Implement the core feature with integration tests and documentation.
   
   ## Acceptance Criteria
   - [ ] All API endpoints return correct responses
   - [ ] Test coverage >80% on new modules
   EOF
   )" --labels feature,backend
   
   npm run ops -- create-sub-issue ENG-XXX "Sub-task 1" "$(cat <<'EOF'
   ## Context
   Set up database schema and migrations for the new feature tables.
   
   ## Acceptance Criteria
   - [ ] Migration runs cleanly on a fresh database
   - [ ] Rollback migration restores prior schema
   EOF
   )"
   

4. 作業を開始する際にプロジェクトの状態を更新します：

   npm run ops -- project-status "Phase X: Feature Name" in-progress
   

これが重要な理由

• 追跡可能性：課題は作成時からプロジェクトに紐付いています
• 指標：プロジェクトの進捗を初日から正確に追跡できます
• ワークフロー：課題をプロジェクト間で移動する手間がありません
• 整理：Linear のビューとフィルターが正しく機能します

避けるべきアンチパターン

❌ 「一時保管用」プロジェクトに課題を作成し、後から移動する：

# Don't do this
create-issue "Phase 6A" "New feature"  # Wrong project
# Later: manually move to Phase X      # Extra work

---

プロジェクト管理コマンド

project-status

Linear のプロジェクトの状態を更新します。Linear の API に対応する、ユーザーフレンドリーな用語を受け付けます。

npm run ops -- project-status <project-name> <state>

有効な状態：

入力	説明	API 値
backlog	まだ開始していません	backlog
planned	今後の予定として設定されています	planned
in-progress	現在進行中です	started
paused	一時的に保留中です	paused
completed	正常に完了しました	completed
canceled	実施しません	canceled

使用例：

# Start working on a project
npm run ops -- project-status "Phase 8: MCP Decision Engine" in-progress

# Mark project complete
npm run ops -- project-status "Phase 8" completed

# Partial name matching works
npm run ops -- project-status "Phase 8" paused

link-initiative

既存のプロジェクトをイニシアチブに紐付けます。

npm run ops -- link-initiative <project-name> <initiative-name>

使用例：

# Link a project to an initiative
npm run ops -- link-initiative "Phase 8: MCP Decision Engine" "Q1 Goals"

# Partial matching works
npm run ops -- link-initiative "Phase 8" "Q1 Goals"

unlink-initiative

プロジェクトとイニシアチブの紐付けを解除します。

npm run ops -- unlink-initiative <project-name> <initiative-name>

使用例：

# Remove incorrect link
npm run ops -- unlink-initiative "Phase 8" "Linear Skill"

# Clean up test links
npm run ops -- unlink-initiative "Test Project" "Q1 Goals"

エラー処理：

• プロジェクトが指定されたイニシアチブに紐付いていない場合はエラーを返します
• プロジェクトまたはイニシアチブが見つからない場合はエラーを返します

プロジェクトのライフサイクル全体の例

# 1. Create project linked to initiative
npm run ops -- create-project "Phase 11: New Feature" "Q1 Goals"

# 2. Set state to planned
npm run ops -- project-status "Phase 11" planned

# 3. Create issues in the project
npm run ops -- create-issue "Phase 11" "Parent task" "Description"
npm run ops -- create-sub-issue ENG-XXX "Sub-task 1" "Details"

# 4. Start work - update to in-progress
npm run ops -- project-status "Phase 11" in-progress

# 5. Mark issues done
npm run ops -- status Done ENG-XXX ENG-YYY

# 6. Complete project
npm run ops -- project-status "Phase 11" completed

# 7. (Optional) Link to additional initiative
npm run ops -- link-initiative "Phase 11" "Q2 Goals"

---

ツールの選択

タスクに適したツールを選択してください：

優先度	ツール	使用する場面
1	MCP（公式サーバー）	ほとんどの操作 — 推奨
2	lin CLI	インストールされている場合の読み取り／状態更新の高速処理（任意）
3	ヘルパースクリプト	一括操作、ラベル分類、プロジェクトのワークフロー
4	SDK スクリプト	複雑な操作（ループ、条件分岐）
5	GraphQL API	上記でサポートされていない操作

lin CLI（任意の高速処理）

lin Rust バイナリがインストールされている場合、スキルは次の操作に自動的に使用します：

• 課題の状態更新（status、done、wip）
• イニシアチブの一覧表示
• 課題の検索（search <query>）
• 課題の一覧表示（list-issues [--team X] [--state Y]）
• ユーザー情報（whoami）

lin が利用できない場合、すべての操作は通知なしで SDK にフォールバックします。

インストール（任意）：

brew install aaronkwhite/tap/lin    # macOS (Homebrew)
cargo install lincli                # Any platform with Rust

無効化：LINEAR_USE_LIN=0 を設定すると、インストール済みでも lin を使用しません。

MCP サーバーの設定

mcp.linear.app の公式 Linear MCP サーバーを使用してください：

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.linear.app/sse"],
      "env": { "LINEAR_API_KEY": "your_api_key" }
    }
  }
}

WARNING：非推奨のコミュニティサーバーは使用しないでください。詳細については、troubleshooting.md を参照してください。

MCP の信頼性（公式サーバー）

操作	信頼性	備考
課題の作成	✅ 高	完全にサポートされています
状態の更新	✅ 高	state: "Done" を直接使用します
課題の一覧表示／検索	✅ 高	フィルターとクエリをサポートしています
コメントの追加	✅ 高	課題 ID で動作します

状態をすばやく更新する

# Via MCP - use human-readable state names
update_issue with id="issue-uuid", state="Done"

# Via helper script (bulk operations)
node scripts/linear-helpers.mjs update-status Done 123 124 125

ヘルパースクリプトのリファレンス

ヘルパースクリプトの詳しい使い方については、troubleshooting.md を参照してください。

エージェントの並列実行

一括操作やバックグラウンド実行には、Linear-specialist サブエージェントを使用します。

Task({
  description: "Update Linear issues",
  prompt: "Mark ENG-101, ENG-102, ENG-103 as Done",
  subagent_type: "Linear-specialist"
})

Linear-specialist を並列で使用する場合：

• ステータスの一括更新（3 件以上の課題）
• プロジェクトのステータス変更
• 複数の課題の作成
• コード変更後の同期操作

直接実行する場合：

• 単一の課題のクエリ
• 課題の詳細表示
• 簡単なステータス確認
• すぐに結果が必要な操作

並列実行のパターンについては、sync.md を参照してください。

画像のアップロード

ステップ 1：会話のコンテキストから画像を抽出する

Claude Code でインライン共有された画像は、自動的にディスクへ保存されません。画像はセッション JSONL 内に base64 として保存されています。抽出スクリプトを使用します。

# Find the current session JSONL
ls -t ~/.claude/projects/<project-path>/*.jsonl | head -1

# Extract all inline images (saves to /tmp by default)
npm run extract-image -- <path-to-session.jsonl>

# Or specify a custom output directory
npm run extract-image -- <path-to-session.jsonl> ~/Desktop

画像は /tmp/shared-image-0.png、/tmp/shared-image-1.png などとして保存されます。

アップロードする前に、必ず Read ツールで抽出した画像を確認してください。

ステップ 2：課題を作成する

# Standard approach
npm run ops -- create-issue "Project Name" "Issue title" "Description"

注：特定のチームを対象にする必要があり、create-issue が誤ったチームを選択する場合は、明示的な teamId を指定して GraphQL を使用してください。

# プロジェクトのチームを取得
npm run query -- 'query { projects(filter: { name: { containsIgnoreCase: "PROJECT NAME" } }) { nodes { id name teams { nodes { id name key } } } } }'

# 明示的な teamId を指定して作成
npm run query -- 'mutation { issueCreate(input: { teamId: "TEAM_UUID", projectId: "PROJECT_UUID", title: "Issue title", description: "Description" }) { success issue { id identifier url } } }'

ステップ 3：画像をアップロードして課題に添付する

npm run upload-image -- /tmp/shared-image-0.png ENG-123 "Optional comment text"

スクリプトは次の処理を行います。

1. ファイルを Linear の S3 ストレージにアップロードする
2. 画像を埋め込んだ Markdown を含むコメントを課題に投稿する

対応形式：PNG、JPG/JPEG、GIF、WebP、SVG、PDF

既知の問題

問題	原因	対処方法
create-issue が誤ったチームを選択する	ワークスペースに複数のチームがある	明示的な teamId を指定して GraphQL を使用する（ステップ 2 を参照）
upload-image.ts で「Issue not found」と表示される	添付する前に課題が削除された	先に課題が存在することを確認する
ディスク上に画像が見つからない	ファイルではなくインラインで共有された	セッション JSONL から抽出する（ステップ 1）

---

重要な要件

課題 → プロジェクト → イニシアチブ

すべての課題は、必ずプロジェクトに関連付ける必要があります。すべてのプロジェクトは、必ずイニシアチブにリンクする必要があります。

エンティティ	リンク必須先	未設定の場合
課題	プロジェクト	プロジェクトボードに表示されない
プロジェクト	イニシアチブ	ロードマップに表示されない

プロジェクト作成の完全なチェックリストについては、projects.md を参照してください。

---

規約

課題のステータス

• 自分に割り当て済み：state: "Todo" を設定
• 未割り当て：state: "Backlog" を設定

ラベル

ドメインベースのラベル分類を使用します。必須ルールについては課題作成チェックリストを、分類全体についてはdocs/labels.mdを参照してください。

# Validate labels
npm run ops -- labels validate "feature,security"

# Suggest labels for issue
npm run ops -- labels suggest "Fix XSS vulnerability"

SDK 自動化スクリプト

MCP ツールでは不十分な場合にのみ使用してください。 ループ、マッピング、一括更新を含む複雑な操作では、@linear/sdk を使用する TypeScript スクリプトを作成します。次の内容については sdk.md を参照してください。

• スクリプトの完全なパターンとテンプレート
• 一般的な自動化の例（一括更新、フィルタリング、レポート作成）
• ツールの選択基準

スクリプトは型ヒントを完全に利用でき、複数ステップの操作では生の GraphQL よりもデバッグが容易です。

GraphQL API

フォールバックとしてのみ使用してください。 MCP または SDK でサポートされていない操作に使用します。

次の内容を含む完全なドキュメントについては、api.md を参照してください。

• 認証とセットアップ
• クエリとミューテーションの例
• タイムアウト処理のパターン
• MCP のタイムアウトへの対処方法
• シェルスクリプトとの互換性

簡単なアドホッククエリ：

npm run query -- "query { viewer { name } }"

プロジェクトとイニシアチブ

高度なプロジェクトおよびイニシアチブ管理パターンについては、projects.md を参照してください。

クイックリファレンス - よく使うプロジェクトコマンド：

# Create project linked to initiative
npm run ops -- create-project "Phase X: Name" "My Initiative"

# Update project status
npm run ops -- project-status "Phase X" in-progress
npm run ops -- project-status "Phase X" completed

# Link/unlink projects to initiatives
npm run ops -- link-initiative "Phase X" "My Initiative"
npm run ops -- unlink-initiative "Phase X" "Old Initiative"

projects.md の主なトピック：

• プロジェクト作成チェックリスト（必須手順）
• コンテンツフィールドと説明フィールド
• 作成前の確認
• 作業前のコードベース検証
• サブ課題の管理
• プロジェクトのステータス更新
• プロジェクトの更新（ステータスレポート）

---

同期パターン（一括操作）

コード変更を Linear に一括同期する方法については、sync.md を参照してください。

クイック同期コマンド：

# Bulk update issues to Done
npm run ops -- status Done ENG-101 ENG-102 ENG-103

# Update project status
npm run ops -- project-status "My Project" completed

課題の一括インポート（bulk-create.ts）

マニフェストディレクトリから、1 つのチームに複数の課題を作成します。各課題には個別の Markdown 説明と、任意のメディアファイルを設定できます。メディアは Linear の fileUpload API でアップロードされ、説明に埋め込まれます（画像はインライン表示、その他のファイルはリンクとして表示）。

ユースケース：各課題にスクリーンショットや録画を添付する必要がある、顧客フィードバック、振り返りのアクションアイテム、またはカスタマー開発のチケットのインポート。

LINEAR_API_KEY=xxx npx tsx scripts/bulk-create.ts \
  --manifest ./feedback-2026-04 \
  --config ./feedback-2026-04/config.json

課題を作成したりファイルをアップロードしたりせずに、まずマニフェストをプレビューします。

npx tsx scripts/bulk-create.ts \
  --manifest ./feedback-2026-04 \
  --config ./feedback-2026-04/config.json \
  --dry-run

マニフェストディレクトリ：

feedback-2026-04/
  tickets.json        # [{ key, title, priority?, labels?, files? }, ...]
  config.json         # { team_key, state_name?, default_priority? }
  desc-<key>.md       # description markdown per ticket (optional)
  <media files>       # referenced by each ticket's files[]

設定は UUID ではなく名前で解決されます：

• team_key → findTeamByKey で検索されます（例："ENG"）
• state_name → 任意のワークフローステータスです（例："Triage"）
• チケットの labels → チームごとにラベル名を大文字・小文字を区別せずに解決します。不明な名前は既定で警告されますが、--strict を指定するとエラーになります

---

リファレンス

ドキュメント	目的
api.md	GraphQL API リファレンス、タイムアウト処理
sdk.md	SDK 自動化パターン
sync.md	一括同期パターン
projects.md	プロジェクトとイニシアチブの管理
troubleshooting.md	よくある問題、MCP のデバッグ
docs/labels.md	ラベル分類体系

外部： Linear MCP Documentation