Agent-Skills.md

Agent Skills: Task Starter

|

UncategorizedID: goldeneggg/dotfiles/task-starter

Repository

goldeneggg/dotfiles
goldeneggg
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/goldeneggg/dotfiles/tree/HEAD/ai-linux/.claude/skills/task-starter

Skill Files

Browse the full folder contents for task-starter.

Download Skill

Loading file tree…

ai-linux/.claude/skills/task-starter/SKILL.md

Skill Metadata

Name
task-starter
Description
|

Task Starter

引数

[プロジェクト名]

ソフトウェア/Web開発の目的と進め方を人が理解できる計画を作る。ルートREADMEで全体を説明し、仕様・調査根拠・個別作業へ案内する。実行に必要な依存関係と並行実行計画も整理する。

スコープ

含むもの

  • プロジェクトフォルダ構造の新規生成
  • ドキュメント形式の選択（Markdown / 自己完結HTML）
  • 仕様書・TODOタスク・現状分析ドキュメントの作成
  • タスク分割（依存メタ情報付き）と計画策定
  • 作業の依存関係図・全体の所要時間を決める経路・並行できる作業の特定
  • 承認前成果物に対する別セッションでの独立反証レビュー
  • Claude Code 最新機能（Subagents並列・/goal・worktree・/batch等）を活用した作業の進め方の提示

含まないもの

  • 既存TODOタスクの実行・進捗管理（→ task-performer）
  • コードの実装作業
  • 計画作成完了後の既存ドキュメントの更新・メンテナンス

ドキュメント作成原則（全成果物に適用）

  • この計画や会話を知らない人が、必要な理由（Why）、変更内容と完成後の状態（What）、実現方法（How）を説明できる文書にする。AI向けの識別子や実行指示だけで説明を済ませない。
  • ルート README.* を全体説明の入口にする。specs/ は要件と設計、references/ は事実と根拠、todos/ は個別作業と実行順を扱い、共通の詳細は一か所に置く。
  • 必要な因果関係を残しつつ、結論を先に書き、重複を削る。入力資料・コード等に元からある識別子は保持し、本文では名称や意味を添える。説明を短縮するためだけに略号やID体系を作らず、条件やリスクは意味の分かる名前で記す。
  • テンプレートは記入欄を埋めるためのものではない。必須の情報と保存形式を保ち、対象に不要な任意節や例示は削除する。
  • 生成と校正の具体的な判断は ../_shared/references/document-writing-guide.md に従う。Phase 3 の生成前と Phase 5 のレビュー前に参照する。

追加作業の採否

「初回の成功条件」は、今回の開発・改修を初めて成功と判断するために、Phase 1 でユーザーと合意した動作・結果、確認方法、必須制約を指す。ユーザーが明示した要件を独断で改善候補へ移さず、初回の範囲が不明なら確認する。

  • ユーザーの依頼に加えて提案する作業ごとに、それを行わなければ満たせない初回の成功条件と、未達になる理由を確認する。実装だけでなく、達成を検証する作業や必須制約を守る作業も対象にする。
  • 必要性を説明できる作業を初回の必須作業へ含める。将来の利便性・保守性・拡張余地だけが目的の作業は、specs/ の「将来の改善候補（初回の対象外）」へ分け、TODO・依存関係・初回の見積もりには含めない。候補がなければこの節は作らない。
  • 追加作業を正当化するために成功条件を後付けしない。判定に必要な事実や条件が不足する場合は、必須扱いにする前にユーザーへ確認する。

開発原則（タスク設計の必須観点）

以下4原則を設計段階で点検し、仕様・受け入れ条件・分割粒度に関わる考慮漏れを防ぐ。対応は初回の成功条件・必須制約と対象のリスクに応じて判断する。

  1. セキュリティ — 認証・認可、入力検証、機密情報の扱い、依存ライブラリの脆弱性について、対象の脅威の影響・発生条件・既存対策を確認する。初回の成功条件と必須制約を満たすために必要な対策を選ぶ。既存対策で十分な場合は、追加不要と判断した理由を記す。
  2. 耐障害性 (Fault Tolerance) — 障害時の影響と復旧方法を検討する。リトライ・タイムアウト・graceful degradation・ロールバック手順は、初回の成功条件に必要なものを設計へ織り込む。単一障害点で全体が止まらないかを点検する。
  3. 高可用性 (High Availability) — 初回に求める稼働継続性を確認し、冗長化・ヘルスチェック・無停止デプロイの必要性を判断する。
  4. スケーラビリティ (Scalability) — 初回の想定負荷・対象規模に対して、状態の持ち方・ボトルネック・水平/垂直スケールの必要性を検討する。

柔軟適用: 全タスクで4原則を検討し、考慮漏れを防ぐ。共通方針は specs/ の非機能要件にまとめ、各TODOの「開発原則チェック」にはその作業固有の対応または既存対策で十分と判断した理由と、必要な参照先を書く。非該当の原則は名前と「N/A（理由）」を残し、同じ理由なら1行にまとめてよい。着手可否・安全性・合否を左右する制約は、該当する作業・受け入れ条件の近くにも記載する。

4原則の検討は、対策作業を一律に追加する指示ではない。作業の追加は「追加作業の採否」に従う。必要な対策は通常、該当する実装タスクの作業内容・受け入れ条件に含める。独立した成果があり、担当を切り分けられる場合に独立タスクへ分割する。

TODOタスク番号規約

todos/ 配下のタスク番号は用途で番号帯を分ける:

  • 新規作成タスク = 0xx 番台（001〜099） — task-starter がプロジェクト初期に分割するタスクはすべてこの帯で連番。3桁ゼロ埋め。
  • 1xx 番台（101〜199）は予約 — task-performer によるタスク実行中に発生した「追加タスク」「申し送りタスク」用。task-starter の新規作成では使わない。

番号帯を分けることで、当初計画したタスク（0xx）と、実装着手後に判明した派生タスク（1xx）が一目で区別でき、計画の妥当性レビューや進捗把握がしやすくなる。

成功基準

  • Phase 1 でユーザーが選択した形式（Markdown / HTML）で、正本ドキュメントが一貫して生成されている
  • 進捗正本と drafts/doubt/ のレビュー資料がMarkdownで生成されている
  • 指定ディレクトリに YYYYMMDD-{name}/ フォルダ構造が生成されている
  • specs/ に要件・技術仕様を含む仕様書が作成され、非機能要件にセキュリティ・耐障害性・高可用性・スケーラビリティの方針が記載されている
  • todos/ に利用できる成果と担当のまとまりで分割したタスクが**0xx 番台（001〜099）**で依存順に配置され、各TODOに依存メタ（depends_on / parallel_group）が明記されている（Markdownはフロントマター、HTMLは <script type="application/x-task-meta">。1xx 番台は予約のため未使用）
  • 各TODOの作業項目と受け入れ条件が、チェックボックスを使わず W-ID / AC-ID 付きの静的定義として記載されている
  • progresses/README.md に全TODOの状態一覧があり、各TODOに対応する progresses/{ID}/PROGRESS.md と logs/{ID}/ が生成され、進捗正本・集約ビュー・その他の作業成果物が分離されている
  • 各TODOと対応する PROGRESS.md の「タスクの目的」に、タスク固有の「必要な理由」「解決する課題」「ユーザーから見た変化」が記載され、両者の内容が一致している
  • 追加作業が初回の成功条件への必要性で判断され、将来の改善候補が初回のTODO・依存関係・見積もりから分離されている
  • ルート README.* だけで必要な理由・完成後の変化・進め方・範囲・完了の判断が分かり、詳細の仕様・TODOと一致している
  • 全ドキュメントが「ドキュメント作成原則」に従い、要約と詳細の役割が分かれ、未説明の用語・IDだけの指示・同じ説明の繰り返しがない
  • 各TODOに「開発原則チェック」があり、4原則すべての具体的な対応または非該当の理由が分かる（同じ非該当理由はまとめてよい）
  • ロードマップ（todos/README.*）に作業の依存関係図・タスク表・完了までの見通し・並行できる作業・作業の進め方が記載されている（HTML時は Mermaid が <pre class="mermaid"> で描画される）
  • drafts/doubt/ に独立反証レビューの状態とサイクル別資料が保存され、Phase 5 へ進む前にレビューが完了またはユーザー判断でスキップされている
  • 独立レビューで初見の読解確認を行い、目的・変更内容・進め方の誤解や不明点への対応を記録している。実施状況は STATUS.md の読解確認専用欄で保持し、省略した場合は理由を明記する。自己確認を独立した確認として扱わない
  • ユーザーが Phase 5 のレビューで承認している

ユーザー確認の提示形式

ユーザーへ回答・選択・承認を求める前に、確認の提示形式と全文テンプレートを全文読み、その提示方法に従う。

ワークフロー

Phase 1: 情報収集

質問・形式選択・生成開始の確認を行う前に、確認の提示形式を全文読む。

  1. 入力テンプレートを読み、既知情報を整理

    • Phase 1 の開始時に必ず references/prompt-template.md を読む
    • ../_shared/references/task-management-contract.md を読み、進捗正本とログの保存契約を以降の生成へ適用する
    • ユーザーの依頼と $ARGUMENTS をテンプレートの項目へ対応付ける。$ARGUMENTS が指定されている場合はプロジェクト名として扱う
    • テンプレートが未記入でも実行を止めず、「生成開始条件」と照合して不足項目を特定する
    • 回答済みの情報や、対象コードから確認できる情報を再質問しない
    • 現在の課題、タスクが必要な理由、影響を受ける利用者、変更前後の違いを整理する。内部作業では、直接の機能変更がないことと、品質・安全性・保守性など利用者に届く間接的な変化を整理する

  2. 既存コード改修の場合、現状を分析

    • 対象リポジトリ/ディレクトリが不明な場合は、最初に確認する
    • 対象範囲が広い（複数モジュール・多数ファイルにまたがる）場合は、この調査をサブエージェントに委譲し、アーキテクチャ・処理フロー・課題のサマリだけをメインに戻させる。対象が数ファイルに絞られている場合は、委譲せず関連ファイルをファイル名検索・内容検索・読み込みで直接調査してよい
    • アーキテクチャ、処理フロー、課題・改善点を把握する
    • 調査で判明した情報を入力項目へ反映し、技術的な質問は調査後に絞り込む

  3. 不足情報を段階的に収集

    • references/prompt-template.md の「不足情報の質問順」に従い、重要な項目から1回1〜3問ずつ質問する
    • 「ユーザー確認の提示形式」に従い、質問ごとに確認理由・回答の用途・判断材料を示す
    • 任意項目は合理的な案で補い、成果物が大きく変わる場合だけユーザーへ確認する

  4. ドキュメント形式を確定（必須） 未指定の場合は、生成ドキュメントを Markdown と HTML のどちらにするか、選択肢を提示してユーザーに確認する。すでに明示されている場合は再質問しない。

    • Markdown（既定）: .md で生成。task-performer での実行や git 差分レビューに向く
    • HTML: 自己完結HTML（.html）で生成。ブラウザで開くだけで体裁・Mermaid図が表示され、共有・閲覧に向く 選択結果（md / html）を以降の Phase 2〜4 で一貫して使う。HTML を選んだ場合は 必ず references/html-output-guide.md を読んでから ドキュメントを生成する。

  5. 収集結果を確認

    • 「生成開始条件」が揃ったことを確認する
    • 初回の成功条件と将来の希望を分け、「追加作業の採否」に従って必須作業と改善候補を整理する
    • 「ユーザー確認の提示形式」で収集結果と採用する前提を提示し、ユーザーの確認を得てから Phase 2 へ進む

Phase 2: 構造生成

  1. プロジェクトフォルダを作成 --format には Phase 1 で選んだ形式（md / html）を渡す。

    python3 scripts/init_project.py "{プロジェクト名}" --path "{出力先}" --description "{概要}" --format {md|html}

    保存先の分類、PROGRESS.md と progresses/README.md の必須形式は、Phase 1 で読んだ共有契約に従う。

  2. 参考ファイルを配置

    • Phase 1 で確認した参考データ・ファイルがあれば files/ にコピーまたはリンク

Phase 3: ドキュメント生成

生成前にドキュメント生成ガイドを全文読み、各文書の生成手順を適用する。

現状分析・仕様書・TODOと対応する進捗正本・ログを作成し、ルートREADMEを仕上げる。文書ごとの適用条件・テンプレート・保存規約・同期手順は同ガイドに従う。

Phase 4: 依存分析とロードマップ生成

「TODOタスク分割ガイドライン」で決めた成果と担当のまとまりを保ち、並行できる作業と先行作業を待つ作業を分け、作業順・待ち条件・完了までの見通しをロードマップにまとめる。

  1. 依存関係の整理 各 TODO の依存メタ（depends_on, parallel_group）を集約し、以下を算出する。メタの所在は形式で異なる:

    • Markdown時: todos/{ID}/README.md 冒頭の YAML フロントマター
    • HTML時: todos/{ID}/README.html の <script type="application/x-task-meta"> ブロック（内部はYAML）
    • 作業の依存関係図: 前提タスクから後続タスクへ矢印で結ぶ、循環のない有向グラフ（DAG）
    • 全体の所要時間を決める経路: 推定時間の合計が最大となる経路（クリティカルパス）
    • 並行グループ: 同じ前提を持ち、編集ファイルが独立しているタスク群

  2. 並行可能性の判定基準 2タスクA, Bが「並行実行可能」とみなせる条件:

    • AとBのどちらも、もう一方の完了を直接・間接に待つ必要がない
    • 編集対象ファイルが重複しない（重複する場合は worktree で作業場所を分け、統合手順を作業の進め方に明示）
    • 共通の状態（DB、外部リソース等）への破壊的変更がない

    判定が曖昧でユーザーへ確認する場合は、確認前に確認の提示形式を全文読む。

  3. todos/README.md を生成 references/templates/roadmap-template.md をベースに以下を埋める:

    • タスク一覧表: ID/概要/前提/並行グループ/推定時間/並行推奨フラグ
    • 作業の依存関係図: Mermaid の graph TD 記法で可視化し、作業名を表示する。並行グループは classDef で色分け
    • 完了までの見通し: 全体の所要時間を決める経路と合計時間、作業時間に含まない外部の待ち時間
    • 並行できる作業: 各グループに属するタスクと、同時に進めても衝突しない理由
    • 作業の進め方: まず人が追える作業順・前提・待ち条件を示す。AIへの具体的な実行指示は必要な場合に付録へ置く。「作業の進め方の書き方」に従う
    • ルートREADMEの段階・成果・TODOリンクを確定し、ロードマップの順序や仕様の範囲・完了条件と照合する

Phase 4.5: 別セッションによる独立反証レビュー

承認前成果物の独立反証レビューを行う。開始・再開前、またはPhase 3で早期レビューを検討するときに、独立反証レビューの詳細手順を全文読む。

同手順に従い、レビュー材料の準備、中断・再開、結果検証、停止判定を行う。

Phase 5: レビューと確定

  1. 生成結果を一覧表示 実際の生成ファイルを一覧表示する。

  2. ユーザーレビューを依頼

    • ユーザーへ提示する前に確認の提示形式を全文読む
    • ../_shared/references/document-writing-guide.md の「提示前の確認」で校正する。ルートREADMEだけを読む確認と、個別TODOだけを読む確認を行い、不明点は提示前に修正する
    • STATUS.md の reader_check と結果参照・理由を確認する。done は参照先の回答と対応結果、not_run は未実施の理由を確認して提示し、未解決事項も明示する。専用欄や根拠が不明な場合は確認済みとせず、記録を確かめる。note や自己校正から独立レビューを実施済みと判断しない
    • 各TODOと対応する PROGRESS.md だけを読んで、「なぜ必要か」「何を解決するか」「ユーザーに何が変わるか」を説明でき、両者の内容が一致することを確認する
    • 追加作業が「追加作業の採否」を満たし、将来の改善候補が初回計画へ混入していないか確認する
    • 「ユーザー確認の提示形式」で計画の目的・成果・進め方・範囲、レビュー結果と未解決事項を要約し、承認対象が生成した計画であることを明示する。ルートREADMEを全体説明の入口として案内し、仕様とロードマップは詳細の参照先とする
    • フィードバックに基づき修正

  3. 承認後、完了メッセージを表示

作業の進め方の書き方

ロードマップでは、各タスクの成果と担当を踏まえ、作業順・待ち条件と必要な統合・検証の進め方を説明する。タスクIDには作業名を添え、待つ理由と受け渡す成果を明示する。

AIへの具体的な実行指示が役立つ場合だけ、付録にまとめる。

  • 個別実行には task-performer、独立作業の並行実行には Subagents、編集場所の隔離には worktree など、対象と利用環境に合う手段を選ぶ。/batch、Agent View、/goal、Hooksも利用可能性と必要性に応じて検討し、機能一覧を生成文書へ貼り付けない。
  • 並行実行の指示には担当TODO、編集範囲、完了条件を含める。worktreeを使う場合は変更を統合する段階も示す。
  • /goal 等に渡す条件は仕様から作り、確認に使う結果や記録を明示する。仕様全体の完了条件のうち、自動確認できる範囲と人の判断・外部作業を待つ範囲を区別する。
  • コマンドやツール引数の具体例を載せる場合は利用環境での仕様を確認する。計画の生成は、記載したコマンドや外部操作の実行許可を意味しない。

TODOタスク分割ガイドライン

粒度の基準

  • 成果と担当: 完了時に利用者または後続作業が使える成果と、担当責任がまとまる範囲で分割する。受け入れ条件はその成果を確認できるものにする。
  • 作業のまとまり: 成果を成立させるために必要な設計・実装・接続・検証は、原則として同じタスクに含める。工程や編集ファイルが異なることだけを分割理由にしない。
  • 時間の目安: 1〜2時間は作業量を把握する目安とし、時間に収めるためだけに成果や担当範囲を細分化しない。
  • 並行性: 成果と担当のまとまりで分割した後に Phase 4 の基準で判定する。並行化のためだけの共通基盤・統合タスクは作らない。独立した成果と担当があり、初回の成功条件に必要な基盤・統合作業は分割できる。

ソフトウェア/Web開発での分割例

以下は、各成果が初回の成功条件に必要で、成果と担当を切り分けられる場合の例。必要な調査・設計に独立した成果と担当がある場合は、先行タスクとして分割できる。並行実行の可否は Phase 4 の判定基準で判断する。

フロントエンド機能追加:

  1. 検索機能を利用可能にする（001-add-search）。画面・状態管理・API接続と、検索結果が表示されることの検証を含める
  2. 詳細表示機能を利用可能にする（002-add-details）。画面・データ取得と、対象の詳細が表示されることの検証を含める

API開発:

  1. 一覧取得APIを利用可能にする（001-implement-list-endpoint）。必要な設計・入力検証・エラー処理・動作テストを含める
  2. 更新APIを利用可能にする（002-implement-update-endpoint）。必要な設計・入力検証・エラー処理・動作テストを含める

リファクタリング:

  1. 入力処理を分離し、既存の動作を保つ（001-extract-input）。必要な分析・設計、処理の分離、呼び出し元の更新と動作検証を含める
  2. 集計処理を分離し、既存の動作を保つ（002-extract-summary）。必要な分析・設計、処理の分離、呼び出し元の更新と動作検証を含める

実装スタイル

自由度: Medium

  • 必須のメタ情報と進捗の保存形式を保ち、本文の構成はプロジェクトに応じて調整する
  • フォルダ構造は標準化、ドキュメント内容は柔軟に対応
  • 図や表は、文章だけより構成・比較・作業順を理解しやすくなる場合に使う

ユーザーインタラクション

以下の確認はすべて「ユーザー確認の提示形式」に従う。

  • Phase 1: 必須（プロジェクト情報収集 + ドキュメント形式の確認）
  • Phase 4: 並行可能性の判定で曖昧な場合は選択肢を提示して確認
  • Phase 4.5: 必須（別セッションの反証レビュー結果またはユーザーによるSKIPを待って再開）
  • Phase 5: 必須（レビューと承認）
  • 途中キャンセル: 生成途中のファイルは削除またはユーザーに確認。Phase 4.5 の awaiting_review は意図的な中断なのでキャンセル扱いにしない

エラーハンドリング

| エラー | 対応 | | ---------------------------- | ---------------------------------------------- | | フォルダが既に存在 | エラーメッセージを表示し、別名を提案 | | 権限不足でファイル作成不可 | エラーを報告し、別の出力先を提案 | | 情報収集中にキャンセル | 確認後、生成済みファイルを削除するか選択させる | | Python 3が未インストール | 手動でフォルダ構造を作成する代替手順を案内 | | 循環依存を検出 | エラー報告し、依存定義の見直しを依頼 | | HTMLシェルが見つからない | init_project.py が明示エラーで停止。references/templates/html-shell.html の存在を確認 | | レビュー結果を特定できない | STATUS.md の active cycle と、結果本文または結果ファイルのパスをユーザーへ確認 | | 3サイクル後も重大指摘が残る | 4回目を開始せず、スコープ変更・設計見直し・リスク受容をユーザーへ確認 |

前提条件

  • Python 3.x（scripts/init_project.pyの実行に必要）
  • 出力先ディレクトリへの書き込み権限

リソース

scripts/

  • scripts/init_project.py - プロジェクトフォルダ構造を生成（Python 3必須）
    • 入力: プロジェクト名(必須), --path(出力先), --description(概要), --format(md / html、既定 md)
    • 出力: YYYYMMDD-{kebab-case-name}/ ディレクトリと標準サブフォルダ群
    • 雛形: README、todos/README、progresses/README.md、drafts/doubt/STATUS.md
    • 参照頻度: 毎回（Phase 2で必ず実行）

references/

  • references/user-confirmation-guide.md - ユーザー確認前に読む提示形式と全文テンプレート
  • references/independent-review-guide.md - Phase 4.5の開始・再開前に読む詳細手順。早期レビュー・状態欄・材料準備・結果検証・停止条件を定義
  • references/project-output-guide.md - Phase 3の生成前に全文読む文書別の生成手順。適用条件・テンプレート・保存規約・同期手順を定義
  • ../_shared/references/document-writing-guide.md - Phase 3・5で参照する共有の執筆・校正ガイド。文書の役割、ルートREADMEの内容、実行中の更新、書き換え例、提示前の確認を定義
  • references/prompt-template.md - Phase 1で毎回参照する入力テンプレート。生成開始条件、不足判定、段階的な質問順を定義
  • references/html-output-guide.md - HTML形式選択時の生成ルール（Phase 1でHTMLを選んだら必ず参照）。シェル使用法・Mermaid・依存メタ埋め込み・拡張子規約・task-performer互換注記
  • ../_shared/references/task-management-contract.md - Phase 1で毎回参照する共有保存契約。PROGRESS.md、progresses/README.md の固定スキーマと logs/ への振り分けを定義
  • ../_shared/scripts/sync_progress_index.py - Phase 3で全TODO生成後に実行する同期スクリプト。個別 PROGRESS.md から全体進捗一覧を生成

references/templates/

以下のテンプレートはPhase 3〜4で参照する。ドキュメント生成のベースとして使用。

  • references/templates/spec-template.md - 仕様書テンプレート（Phase 3で毎回参照）
  • references/templates/todo-template.md - TODOタスクテンプレート（Phase 3で毎回参照、依存メタ必須）
  • references/templates/reference-template.md - 現状分析テンプレート（既存コード改修時のみ）
  • references/templates/roadmap-template.md - タスクロードマップテンプレート（Phase 4で毎回参照）
  • references/templates/html-shell.html - 自己完結HTMLの共有シェル（HTML形式選択時にスクリプト/Claude双方が使用）