はじめに

こんにちは。プロダクト開発基盤チームのYoshioka（@tsuyogoro）です。

LLMによるコーディングが当たり前になり、チームでも人力でコードを書く場面は減ってきました。一方で、手戻りが起きやすいのは実装そのものより「実装の前」だという感覚は残っています。

何をどう分解するか
どの順序で進めるか
依存関係や完了条件をどう定義するか

ここが曖昧なままだと、あとから設計や優先順位が崩れ、「進んでいるのに進んでいない」状態になりがちです。こうした経験に心当たりのある方も多いのではないでしょうか。さらに計画フェーズは認知負荷が高く、人間がボトルネックになりやすい傾向があります。

そこで、実装の前段を支援するエージェント用Skillとしてlinear-project-builderを作りました。

このSkillは「コードを書く」ためではなく、LLMに実装を任せるための入力（タスク設計）を組み立てるところまでを担当します。これにより、これまでチームで行っていたタスクのリファインメント（洗い出し・具体化）を、開発者がLLM相手に1人で進めやすくなります。本記事では、LLMに実装を任せる前の設計プロセスに課題を感じている方に向けて、linear-project-builderの設計と運用の工夫をご紹介します。

linear-project-builderとは

Linearはソフトウェア開発向けのタスク管理ツールです。Jiraに近いイメージで、Project（Epic相当）とIssue（作業チケット）で管理します。

AIエージェントと相性がよく、「このチケットの内容でPRを作って」と渡すと、文脈付きで実行してもらいやすいのが特徴です。

linear-project-builderは、要件やアイデアを「LLMがそのまま実装できる粒度」のLinear Project / Issueに落とし込む一連の作業をAgent Skillの形に仕組み化したものです。実装そのものは行わず、入力となるProject / Issueを設計・作成するところまでに役割を絞っています（実装は別のエージェントや人が担当）。

出力先をLinearにしているのは、Projectに順序や依存関係を持たせ、Issueに実装粒度を持たせることで、LLMが作業単位を解釈しやすくなるためです。結果として、Issue 1本につきPR 1本、といった運用にもつなげやすくなります。

Skill動作の3つのPhase

ここで言うSkillは、AIエージェントに「役割」「手順」「参照ドキュメント」をまとめて渡すための定義です。

linear-project-builderは3つのPhaseで動き、Phaseごとに参照するreferences/（Markdown）を切り替えます。これにより、情報が足りないうちに先に進まないようにしています。

Phase 1: ヒアリング — 解像度が足りるまで対話する
Phase 2: 構造化と品質検証 — フォーマットに沿ってProject / Issueを組み立て、品質ゲートを通す
Phase 3: Linear登録 — チーム選択とAPI制約を踏まえ、Linearに登録する（MCPはLinearのAPIをエージェントから呼び出す仕組み）

全体のファイル構成は以下の通りです。

skills/pdf/linear-project-builder
├── README.md                    # 概要・セットアップ・使い方
├── SKILL.md                     # スキル定義・3 Phase ワークフロー・MCP ツール一覧
└── references
    ├── codebase-access.md       # コード参照方法（ローカル/gh CLI）と参照元の記録
    ├── integrity-rules.md       # Issue 先行・Project と 1 対 1 対応の整合性ルール
    ├── interview-guide.md       # ヒアリングの質問項目・心得・入力形式の判定
    ├── mcp-constraints.md       # Linear API の制約（文字数・格納ルール）
    ├── project-format.md        # Project Description のフォーマット定義
    ├── quality-check.md         # 「AI に渡してよいか」の出口チェック
    ├── task-format.md           # Issue（Task）Description のフォーマット定義
    ├── team-selection.md        # チーム一覧の取得・選択とパラメータマッピング
    └── troubleshooting.md       # MCP 衝突・API エラー時の対処

Phase 1: ヒアリング（情報を埋める）

「必要な情報が揃うまで、プロジェクトを作らない」のがPhase 1の鉄則です。

短文のアイデアだけでは、LLMに渡せる粒度まで分解できません。そこでinterview-guide.mdに沿って、何を・どの順で・どの完了条件でやるかを埋めていきます。

質問は一度に大量に出さず、基本は1つずつ。反対に、Notionなどに要件が整理されている場合、AIにとって解像度が十分なら対話を省略してPhase 2に進めます。

コード参照が必要な場合は、codebase-access.mdに従って参照方法（ローカルclone, gh CLI, MCP経由…etc）と、対象リポジトリ・パスを明文化します。

Phase 2: 構造化と品質検証（実装可能な仕様に変換）

Phase 2では、迷いなく実装・検証できるレベルのProject / Issue案を作ります。

integrity-rules.mdに従い、適切なIssueの粒度に分けます。粒度の目安は「1チケット ≦ 1日（人間がやる場合）」。見積もりが2日以上になる場合は、「なぜ分割できないか」をIssueに明記します。

フォーマットはproject-format.mdとtask-format.mdで固定し、Issueには次を含めます。

触るファイル
実装ステップ
テストと完了条件

最後にquality-check.mdで「このままAIに渡してよいか」を確認し、通過したものだけをPhase 3へ。

Phase 3: Linear登録（MCP実行）

Phase 3では、Phase 2を通過したProject / IssueをMCP経由でLinearへ登録します。

team-selection.mdに従って対象チームを選び、担当者・見積もり・優先度などをマッピング。続けてmcp-constraints.mdのAPI制約（文字数・格納ルール）を守りつつ、MCP経由で作成・更新します。

トラブルに備えて、troubleshooting.mdに「よくあるトラブルと対処」をまとめています（ツールとしての使いやすさ向上のための施策です）。

壁打ち相手としての質を上げるTips

運用で効いているポイントをまとめます。

Skill定義に「厳しさ」を書いておく

ゴールは「実行可能なタスクに落とす」ことです。どんな基準で厳しくするかをSkill定義に明示しておくと、エージェントの振る舞いがぶれにくくなります。

### 1. タスク粒度の鉄の掟： "1 Ticket <= 1 Day"
タスクは必ず**「最大でも1日（数時間〜8時間程度）で完了できる粒度」**まで物理的に分割してください。
...
### 3. 曖昧さは罪
ユーザーが必要な情報を出すまで、絶対にプロジェクトを作成しないでください。

人間側が「質問をスキップしない」ように設計する

質問が多いと、人間側が飛ばしたり薄く答えたりしがちです。そこで「質問は1回に1つまで」とSkill側で決め、1つの問いに集中して答えられるようにしています。

### 4. 入力形式の柔軟性
- **対話形式**: 質問は1つずつリズムよく。複数の質問を一気に投げかけない
- **ドキュメント形式**: ユーザーがある程度まとまった文章を提供した場合、それを活用する
...

解像度が足りるまで先に進まない

Phase 1は面倒に感じやすいのですが、ここで必要なだけ答えるとPhase 2・3が楽になります。要件が固まっている場合は、NotionのURLや要件ドキュメントを渡すと短縮できます。

品質ゲートを通過したものだけLinearに登録する

quality-check.mdを通過したものだけをLinearに登録します。「とりあえず登録して、あとで直す」をやめると、LLMに実装を任せた後の手戻りが減ります。

なお、quality-check.mdのほとんどはAIに書かせました。「どういう状態になれば実行可能なのか」を繰り返し問いかけ、内容をブラッシュアップしていきました。実行するのはAI自身なので、AIに基準を決めてもらうのは合理的です。

「速さ」だけを求めない

このSkillは出力の質を最優先しています。現状、対話からチケット作成まで15分前後かかることが多いです。

ただ本来、チームでのリファインメント作業や、要件を壁打ちしながら明確にする作業には時間がかかります。20分足らずで形になり、Issueが「そのままLLMに渡せる単位」になる点は非常に価値があります。「AIによって何が置き換えられるのか」を考えることが大事とよく言われますが、開発の現場にもそうした事例があるということですね。

実際に生成されたLinear ticketの例

繰り返しになりますが、このSkillの価値は実装（実行）の前段を支援してくれる点にあります。実際の業務プロジェクトではなく、汎用的な課題でLinearチケットを作成した例をご紹介します。

その後「今の時点で興味がある趣味候補を、最大3つまで挙げてください」「ランニングを月2回継続するうえで、今いちばんの障害になりそうなものは何ですか？」など、細かいヒアリングが続きました（これを人にされると「詰められてる!?」となりますが、AI相手だと不思議とそのような感情は湧きませんね）。そして、以下のようなProjectとIssuesが生成されました。

この例では人間（私）が実行する必要がありますが、通常の開発プロジェクトでは、ここから先の作業の多くをLLMが実行してくれます。ProjectのチケットをCodex・Claude Codeなどに渡せば、Projectに記載されたプラン通りにコードが作成され、人間による動作確認・コードレビュー（これらも可能な限りLLMに任せるのが今の働き方ですが）へと進めます。

（おまけ）Skillの配置の仕方

複数のコーディングエージェントでSkillを共有するため、以下の構成で定義しています。

<repository_root>/
├── skills/                    ← スキル定義の実体（ここが正）
│   ├── code-review/
│   └── identity-f-local-dev/
│
├── .cursor/
│   └── skills → ../skills     ← シンボリックリンク
├── .claude/
│   └── skills → ../skills     ← シンボリックリンク
└── .codex/
    └── skills → ../skills     ← シンボリックリンク