planner

Planner Skill

複雑なプロジェクトを、管理しやすく再開可能なステップに分割した段階的なプロジェクト計画を生成します。初期設計からコーディング、テスト、クラウドへのデプロイまで対応します。

Tip：利用可能なすべてのスキルの概要については、root SKILL.md を参照してください。

---

Greenfield と Brownfield の検出

シナリオ	検出条件	動作
Greenfield	Dockerfile がなく、.do/app.yaml もない	アーティファクトをゼロから作成する
Brownfield	Dockerfile または .do/app.yaml が存在する	既存のものを確認、検証、強化する

AI アシスタントがプロジェクトの状態を自動的に検出します。有効なアーティファクトを作り直さないでください。重要な検証ゲートは doctl app dev build です。これが成功すれば、アーティファクトは正しい状態です。

---

段階的なデプロイが必要な理由

複雑な App Platform のデプロイを一度に実行すると、失敗する可能性があります。

1. 準備なしのデプロイは失敗します - インフラストラクチャを準備せずにデプロイすると、分かりにくいエラーが発生します
2. コンテキストが失われます - 認証情報、クラスター ID、進捗状況がセッション間で忘れられます
3. デバッグが難しくなります - すべてを一度にデプロイすると、どのコンポーネントが失敗したのか分かりません
4. 再開が困難です - 最初からやり直すと時間が無駄になり、途中までの進捗も記録されません

---

まずローカルでビルドする

重要：クラウドにデプロイする前に、必ずローカルでビルドを検証してください。

doctl app dev build                    # Build using local app spec
doctl app dev build --app <APP_ID>     # Build using existing deployed app
doctl app dev build --env-file .env    # Build with environment overrides

ビルド場所	フィードバック時間	失敗時のコスト
クラウド	5-10 分	サイクルが無駄になり、ログも分かりにくい
ローカル	30-60 秒	すぐに修正でき、エラーも明確

詳細：build-local-first.md を参照してください。

---

Tier の分類

ユーザーの説明からの検出

ユーザーが言及した内容	Tier
"static", "frontend only", "no database", "SPA"	Tier 1
"PostgreSQL", "MySQL", "database", "API + frontend"	Tier 2
"Kafka", "OpenSearch", "workers", "event-driven", "microservices"	Tier 3

判定ツリー

Does user mention Kafka, OpenSearch, workers, or "event-driven"?
  YES → Tier 3 (Complex)
  NO → Does user mention database (PostgreSQL, MySQL, MongoDB)?
         YES → Tier 2 (Database-backed)
         NO → Tier 1 (Simple)

app.yaml からの検出（フォールバック）

.do/app.yaml が存在する場合：

• workers が存在する → Tier 3
• databases に KAFKA または OPENSEARCH がある → Tier 3
• databases が存在する → Tier 2
• いずれも存在しない → Tier 1

---

Tier の構成

Tier 1：シンプル（5 ステージ）

基準：静的サイト、単一サービス、データベースなし

Plan/
├── 01-local-design.md
├── 02-local-coding.md
├── 03-local-testing.md
├── 04-cloud-deploy.md
└── 05-cloud-validate.md

例：Next.js の静的エクスポート、React SPA、Hugo サイト、Astro

Tier 2：データベースを使用（7 ステージ）

基準：1～2 個のサービス、単一データベース（PostgreSQL/MySQL）

Plan/
├── 01-local-design.md
├── 02-local-coding.md
├── 03-local-testing.md
├── 04-cloud-database.md
├── 05-cloud-config.md
├── 06-cloud-deploy.md
└── 07-cloud-validate.md

例：Rails + PostgreSQL、Django + MySQL、Node.js API + Postgres

Tier 3：複雑（9 ステージ）

基準：複数のサービス、ワーカー、Kafka/OpenSearch、VPC ネットワーキング

Plan/
├── 01-local-design.md
├── 02-local-coding.md
├── 03-local-testing.md
├── 04-cloud-database-clusters.md
├── 05-cloud-config-users-topics.md
├── 06-cloud-debug-validation.md
├── 07-cloud-secrets-cicd.md
├── 08-cloud-deploy-production.md
└── 09-cloud-end-to-end.md

例：イベント駆動型マイクロサービス、ML パイプライン、リアルタイム分析

重要：Tier 3 のアプリでは GitHub Actions を使ってデプロイする必要があります

Tier 3 のアプリには、digitalocean/app_action/deploy@v2 でのみ解決される ${SECRET_NAME} プレースホルダーがあります。

• .do/app.yaml で deploy_on_push: false を設定します
• doctl apps create ではなく、git push（GitHub Actions を起動）を使ってデプロイします

---

ステージテンプレート

ステージテンプレートは templates/ ディレクトリにあります。

ディレクトリ	用途
templates/local/	ローカルのステージ 1～3（すべての Tier）
templates/tier-1-simple/	Tier 1 のクラウドステージ
templates/tier-2-database/	Tier 2 のクラウドステージ
templates/tier-3-complex/	Tier 3 のクラウドステージ

各ステージファイルは次の構成に従います。

# Stage N: [Stage Name]

**Status**: TODO
**Prerequisites**: Stage N-1 complete

## Tasks
- [ ] Task description
- [ ] Expected outcome

## Verification
[Commands to verify completion]

## Next Steps
Proceed to Stage N+1

重要な検証ゲート：ステージ 3 には doctl app dev build とヘルスチェックの検証が含まれます。

---

使用例

例 1：シンプルな静的サイト

ユーザー：「Next.js の静的サイトをデプロイする」

1. Tier 1（データベースなし）を検出する
2. Plan/ に 5 つのステージファイルを生成する
3. 「5 ステージの計画を作成しました。ステージ 1：ローカル設計から開始してください。」と返す

例 2：データベースを使用する API

ユーザー：「PostgreSQL を使用する Node.js API」

1. Tier 2（PostgreSQL）を検出します
2. Plan/ に 7 つのステージファイルを生成します
3. 次のメッセージを返します：「7 ステージのプランを作成しました。Stage 4 でデータベースクラスターを作成しました。」

例 3：イベント駆動型マイクロサービス

ユーザー：「Kafka と OpenSearch を使用するイベント駆動型アプリ」

1. Tier 3（Kafka + OpenSearch）を検出します
2. Plan/ に 9 つのステージファイルを生成します
3. 次のメッセージを返します：「デバッグコンテナの検証を含む 9 ステージのプランを作成しました。」

---

主な機能

セッションの再開

• ステージファイルは Git に保持されます（ステータスの追跡のみ）
• 取得したすべての値は .env.secrets に保存されます（Git で追跡されません）
• AI アシスタントは .env.secrets を読み取り、任意のステージから再開します

成果物の保存

• プランファイルに含まれるのはステータスのみで、シークレットは含まれません
• すべての ID、パスワード、URL は .env.secrets に保存されます
• 考え方については、artifact-storage.md を参照してください

一時停止ポイント

• 各ステージは検証チェックリストで終了します
• 「Stage N+1 に進む」ための明確な案内があります
• よくある障害に関するトラブルシューティングのセクションがあります

---

参照ファイル

• build-local-first.md — doctl app dev build ワークフローの全体
• artifact-storage.md — 保存に関する考え方、AI への指示

---

他のスキルとの連携

• ← designer：存在する場合、複雑さの検出に .do/app.yaml を使用します
• → deployment：Plan/ ファイルがコンテキストを提供します。Stage 7 では GitHub Actions ワークフローを作成します
• → troubleshooting：Plan/ のステージを使って、障害が発生した箇所を特定できます
• → devcontainers：テスト用のローカル開発環境をセットアップします