linear

Linear

概要

Linear CLI（linear）が利用可能な場合は使用してください。インストール済みだと決めつけないでください。CLI を利用できない場合や、必要な操作に対応していない場合は、環境からすでに提供されている API キーを使用して Linear の GraphQL API を利用してください。

アクセス方法の選択

1. 失敗させずに CLI の有無を確認します。

   command -v linear
   

2. CLI が存在する場合は、以下の CLI のガイダンスに従ってください。

3. それ以外の場合は、GraphQL の認証情報が利用可能かどうかを表示せずに確認します。

   test -n "${LINEAR_API_KEY:-}"
   

   direnv を使用するプロジェクトでは、無視対象の環境ファイルで LINEAR_API_KEY を宣言し、.envrc から読み込むことがよくあります。キーが見つからない場合は、シークレットを読み取ったり、ログに記録したり、コピーしたりせず、プロジェクトに入る／許可する、または direnv exec を使用するなどして、direnv にプロジェクト環境を読み込ませてください。

4. GraphQL の操作は、Authorization: $LINEAR_API_KEY と JSON の Content-Type を指定して https://api.linear.app/graphql に送信します。クエリに課題のテキストを直接埋め込むのではなく、GraphQL の変数を使用してください。

   query='query Viewer { viewer { id name email } }'
   payload=$(jq -cn --arg query "$query" '{query: $query, variables: {}}')
   response=$(curl -sS https://api.linear.app/graphql \
     -H "Authorization: $LINEAR_API_KEY" \
     -H 'Content-Type: application/json' \
     --data "$payload")
   jq -e '.errors == null' <<<"$response" >/dev/null || {
     jq '.errors' <<<"$response" >&2
     exit 1
   }
   jq '.data' <<<"$response"
   

ミューテーションを行う場合は、推測したり、古くなったハードコード済みの ID に依存したりせず、先に ID と現在の状態を照会してください。errors 配列を含む GraphQL の HTTP 200 レスポンスは失敗として扱ってください。API キーを表示したり、コマンド出力に含めたり、コミットしたり、クエリや変数オブジェクトに直接記述したりしないでください。

課題の作成

課題の作成、下書き、書き換え、または内容の拡充を依頼された場合に認められるのは、問題を忠実に記述することです。プロダクトの計画や解決策の設計は行わないでください。課題には解決すべき問題を記載し、実装方法の検討は、その作業を担当する人間またはエージェントに委ねてください。

デフォルトの形式

すべての課題本文は、平易な言葉による短い段落で始めます。

> **In plain terms:** Describe what is wrong or missing, who or what it affects, and why it matters. Do not prescribe the implementation.

このブロックは、専門知識のない読者にもそれだけで伝わる内容にしてください。依頼が一文のみの場合、課題はこの一文のブロックだけでも構いません。情報源となる資料に根拠がある場合に限り、追加のセクションを設けてください。

重要な指針

• 解決策より先に問題を記述します。 現在の動作、判明している場合はユーザーや運用にとって望ましい結果、影響を受ける人やシステム、影響、および有用な根拠を説明します。タイトルには実装作業ではなく、問題や望ましい結果を記載します。
• 出典のある事実のみを記載します。 人間が述べた内容、引用元に記載された内容、または直接確認した内容のみを含めます。もっともらしい要件で不足を補わず、不確実性はそのまま保ちます。
• チケットの定型文は追加しません。 Issue を完全なものに見せるためだけに見出しを追加しないでください。最小の長さはなく、冒頭の平易な言葉によるブロック以外に必須のテンプレートもありません。
• 要件を作り上げません。 受け入れ基準、ユーザーストーリー、ペルソナ、スコープ、対象外事項、エッジケース、テスト、ロールアウト、移行、テレメトリ、セキュリティ、運用要件を推測しないでください。
• 計画用メタデータを作り上げません。 優先度、見積もり、期限、ラベル、親 Issue、依存関係、担当者、サブタスク、チェックリストを推測しないでください。
• 解決策を確定しません。 アーキテクチャ、API、データモデル、UI、実装手順を作り上げないでください。人間が解決策を提案した場合は、確定した設計へと発展させず、出典を明示した背景情報または制約として残します。
• 必要な場合にのみ確認します。 確認せずに Issue を作成すると問題を大きく誤って記述してしまう場合に限り、簡潔な質問をします。それ以外の場合は、忠実性を保てる最小限の Issue を作成し、実際に不明な点は未確定のままにします。
• 既存の Issue を優先します。 実行可能な場合は重複の可能性がある Issue を確認し、並行するチケットを作成するのではなく、既存の Issue を再利用して必要最小限の修正を加えます。

受け入れ基準、計画用メタデータ、解決策の詳細を追加するのは、人間が明示的に提示または承認した場合、あるいは引用元の内容を忠実に転記する場合に限ります。出典または決定の主体を明示し、それ以上詳しく説明しないでください。

バグ報告に記載された期待される動作は問題の説明に含めます。生成した受け入れ基準として重複させないでください。また、Issue に着手したからといって、解決策の仕様書へ書き換えてよいわけではありません。実装案は、最終的な担当者の計画またはディスカッションに記載してください。

Issue を作成または更新する前に、依頼、引用された根拠、直接の観察、または人間による明示的な決定にたどれない文はすべて削除します。

プルリクエストへの引き継ぎ

実装の開始後も、Issue を問題の正式な記述として扱います。事後的な解決策の仕様書へ書き換えたり、その内容をプルリクエストの説明に繰り返し記載したりしないでください。

代わりに、実際の関係に合った表記を使い、プルリクエストの冒頭で Issue にリンクします。

- **Closes:** [PROJECT-123 Problem title](https://linear.app/example/issue/PROJECT-123/problem-title)

Closes はプルリクエストが Issue を完全に解決する場合のみ使用します。一部のみを実現する場合は Advances、背景情報として関連付ける場合は Related、中立的なリンクが適切な場合は Issue を使用します。続くプルリクエストの 平易な言葉での説明 の段落には、そのプルリクエストが人々にもたらす変更のみを記載し、重要なトレードオフがあればそれも含めます。問題の背景はリンク先の Issue に記載されています。

CLI 設定

CLI コマンドを実行するには、LINEAR_ISSUE_SORT を設定する必要があります。

export LINEAR_ISSUE_SORT=priority

これを設定しないと、ほとんどのコマンドが失敗します。

チーム

linear team list を使用して、利用可能なチームを確認します。

Issue のステータス

ステータス	説明
triage	トリアージが必要な新しい Issue
backlog	優先順位付け済みだが、未着手
unstarted	着手可能（Todo）
started	進行中
completed	完了
canceled	キャンセル済み／対応しない

よく使うコマンド

Issue の一覧表示

# Active issues (excludes completed/canceled)
LINEAR_ISSUE_SORT=priority linear issue list --team WDY --no-pager

# Filter by state
LINEAR_ISSUE_SORT=priority linear issue list --team WDY --no-pager -s started -s unstarted

# All issues including completed/canceled
LINEAR_ISSUE_SORT=priority linear issue list --team WDY --no-pager --all-states

Issue の表示

LINEAR_ISSUE_SORT=priority linear issue view WDY-123 --no-pager

Issue のステータスを更新

linear issue update WDY-123 --state "Done"
linear issue update WDY-123 --state "In Progress"

Issue にリンクした PR を作成

linear issue pr WDY-123

チームの一覧表示

linear team list

ワークフロー

クローズする Issue の確認

# List active issues
LINEAR_ISSUE_SORT=priority linear issue list --team WDY --no-pager -s started -s unstarted -s backlog

# Cross-reference with recent commits
git log --oneline -30 --all

新しい Issue のトリアージ

# View issues in triage
LINEAR_ISSUE_SORT=priority linear issue list --team WDY --no-pager -s triage