okteto-onboarding

Okteto オンボーディングスキル

1. 有効化

以下のすべてに該当する場合、このスキルが有効になります。

• リポジトリのルートに okteto.yaml または okteto.yml がない
• ユーザーが Okteto、開発環境、オンボーディングについて質問している（例：「これを Okteto に載せるにはどうすればよいですか」「このリポジトリを Okteto 用に設定してください」「Okteto マニフェストを作成してください」）

次の場合は有効化しないでください。

• リポジトリのルートに okteto.yaml または okteto.yml がすでに存在する場合 — その場合は既存の okteto スキルの範囲です。そちらに委ねてください。
• 既存のマニフェストで Okteto を使用する方法について質問している場合。既存の okteto スキルに委ねてください。

事前確認。 フェーズ 1 を開始する前に、次を実行します。

ls okteto.yaml okteto.yml 2>/dev/null

何かが返された場合は、処理を停止してユーザーに次のように伝えてください。

「okteto.yaml がすでに存在しています。okteto-onboarding スキルは、マニフェストがないリポジトリを対象としています。既存のマニフェストを操作するには、okteto スキルを使用するか、/dev-setup を実行してください。」

2 つの動作モード： 協調型（デフォルト — ユーザーが進行に関与）と自律型（人間が関与せず、PR を作成）です。セクション 7 を参照してください。ワークフローの大部分はモードに依存しません。異なるのはフェーズ 6 と「ユーザーに尋ねる」分岐の解決方法だけです。

2. フェーズ 1 — 調査

リポジトリの内部モデルを構築します。サービス、そのビルドコンテキスト、ポート、開発コマンド、既存のデプロイ成果物を把握します。シグナルを優先順位の高い順に確認してください。まだマニフェストを作成しないでください。

2.1 シグナルの優先順位

1. docker-compose.yml / compose.yaml — サービスと開発に関する情報が最も豊富で、単独で有効な deploy: のソースにもなります。存在する場合、build: と dev: の主要な設計図となり、Okteto は deploy: compose:（セクション 4.1）を介して直接デプロイできます。チャートや k8s マニフェストは不要です。以下のマッピング表を参照してください。
2. 既存の Helm チャート — chart/、charts/、helm/、または deploy/ 配下にある Chart.yaml。見つかった場合、deploy: は helm upgrade --install コマンドになります。チャートを生成または変更しないでください。
3. 既存の k8s マニフェスト — k8s/、manifests/、deploy/ 配下にある kind: ヘッダー付きの .yaml ファイル。ただし、templates/ サブディレクトリは除外します（Helm チャートに属し、直接適用できないためです）。見つかった場合、deploy: は kubectl apply -f ... になります。これらのマニフェストを作成しないでください。
4. サービスごとの Dockerfile — compose がないリポジトリでは、トップレベルの各 Dockerfile がサービス候補になります。サービス名は親ディレクトリから取得します。
5. 言語のマニフェスト — package.json、go.mod、pom.xml、pyproject.toml、Gemfile、Cargo.toml。開発用イメージの選択と開発コマンドの推測に使用します。これだけが手掛かりの場合（Dockerfile も compose もない場合）、プロジェクトの name フィールド（例：pyproject.toml の [project] name、package.json の name）をサービス名にします。それがなければ、リポジトリのディレクトリ名を使用します。
6. Procfile / Makefile — 言語のマニフェストだけでは判断しにくい場合の補助的な手掛かりです。

これらのシグナルは相互に補完するものであり、排他的ではありません。 1 つのリポジトリに複数が含まれることがあります。よくある組み合わせは次のとおりです。

• Compose のみ — compose が build:、dev:、さらに deploy: compose: を介して deploy: を決定します。チャートや k8s マニフェストがなくても、レベル 2 に到達するには十分です。
• チャートまたは k8s のみ — そのアーティファクトが deploy: を決定します。デプロイされたワークロード名から dev: を導き出します（フェーズ 3、箇条書き 4）。
• Compose とチャート／k8s の両方 — デプロイ元が曖昧です。Compose ファイルが開発用、チャートが本番用であることはよくありますが、常にそうとは限りません。チャートが deploy: を優先すると決めつけないでください。 どれを使うか（compose、チャート／マニフェスト、または両方を組み合わせたもの）をユーザーに確認します（セクション 2.5）。

優先順位の順番で勝者を決めるのではなく、各シグナルをマニフェスト内の該当セクションに適用します。

ルートの compose ファイルだけで調査を終えないでください。 実際のプロジェクトには複数のファイルが含まれていることがよくあります。たとえば、ベース用または本番用の compose（多くの場合リポジトリのルートにあり、公開済みの image: を使用）に加えて、docker/、dev/ 配下や、名前付きの *.dev.yml / compose.dev.yml といった開発用 compose が 1 つ以上あります。./docker-compose.yml だけでなく、**/docker-compose*.y*ml と **/compose*.y*ml を glob で検索します（node_modules、vendor、build ディレクトリは除外します）。通常、この使い分けは明確です。

• 開発用 compose — ソースからビルドするもの（context:／target: を含む build: と、ソースのバインドマウントを使用）が build: と dev: を決定します。
• ベース用／本番用／*.preview* compose は deploy: を決定できます。

compose ファイルが複数ある場合は、一覧を示して、どれが開発用でどれがデプロイ元かを尋ねます（セクション 2.5）。ルートのファイルが開発用の設計図だと決めつけないでください。 公開済みイメージだけで構成されたルートの compose は 実行／デプロイ 用のファイルであり、公開済みイメージを使って開発する意味はありません。

include: をたどり、アンカーを解決します。 compose ファイルが include:（または古い extends:）を介してほかのファイルを取り込むことがあります。サービスを見落とさないよう、それらも読み込みます。生の行ではなく、解決済み の YAML を解析してください。開発用 compose では、アンカーや x- 拡張フィールド（build: *some-anchor、<<: *some-env）をよく使用し、展開後でなければ意味を理解できません。

既存の Okteto 対応 compose は有力な手掛かりです。 compose ファイルですでに Okteto Compose 拡張（endpoints:、public:）が使用されている場合、または明らかに okteto のデプロイファイルである場合は、それを deploy: のソースとして優先し、新しいものを作成するのではなく、ユーザーに提示します。顧客はすでに希望するデプロイ方法を示しています。

2.2 Compose → Okteto のマッピング

docker-compose.yml がある場合は、次のようにフィールドを対応付けます。

Compose のフィールド	Okteto マニフェストのフィールド
services.<name>	build.<name>（build: ブロックがある場合）および dev.<name>
build.context、build.dockerfile	build.<name>.context、build.<name>.dockerfile
image（build がない場合）	直接 dev.<name>.image に指定します — ビルド済みイメージに対して build.<name> エントリーを追加しないでください
ports（レベル 1）	dev.<name>.forward — ユーザーが意図したローカルポートを維持します
ports（レベル 2 以上）	deploy: のソース（Compose の deploy:、Helm、または k8s）を通じて公開し、アクティブな開発セッション用に dev.<name>.forward も維持します
command	dev.<name>.command の開始点
volumes（ホストのバインドマウントのみ）	dev.<name>.sync の候補
depends_on	デプロイ手順の順序に関するヒント
environment	dev.<name>.environment

Compose 固有で変換できない概念（networks、restart、名前付きボリューム、extends）は無視します。

バックエンドサービスと開発対象。 build: がなく、リポジトリ内にソースもない公開済みの image: を使う Compose サービス（データベース、キャッシュ、オブジェクトストア、メールキャッチャー、メッセージブローカー — postgres、redis、minio、nats、mailpit など）はインフラストラクチャです。deploy: スタックには含めますが、通常は dev: には含めません。dev: は実際に編集するサービス、つまりリポジトリ内のソースからビルドするサービスに限定します。デフォルトですべての Compose サービスに dev: エントリーを作らないでください。Compose サービスが 10 個あるリポジトリでも、実際の開発対象は 1 つか 2 つだけということがよくあります。

2.3 言語マニフェストに基づく開発イメージの選択

言語マニフェストからイメージのファミリーを選び、リポジトリで宣言されているバージョンからタグを選びます — バージョンをハードコードしないでください。宣言されたバージョンを読み取ることで、古くなるマイナーバージョンに固定せず、最新の状態を保てます。

言語マニフェスト	イメージのファミリー	バージョンの確認場所
package.json	okteto/node	engines.node
go.mod	okteto/golang	go 1.x の行
pom.xml / build.gradle*	okteto/maven または okteto/gradle	maven.compiler.release / sourceCompatibility、またはラッパーのバージョン
pyproject.toml / requirements.txt	okteto/python	requires-python または .python-version
Gemfile	okteto/ruby	.ruby-version または ruby ディレクティブ
Cargo.toml	okteto/rust	設定されている場合は rust-version（MSRV）

宣言されたバージョンをイメージのタグに指定します。例：go.mod に go 1.23 とある場合は okteto/golang:1.23 を指定します。インラインコメントで参照元を明記してください（# go.mod declares Go 1.23）。

リポジトリにバージョンの宣言がない場合は、特定のマイナーバージョンを推測して指定しないでください — 正しい場合と同じくらい、誤っていることもあります。協調モードでは、対象とするバージョンをユーザーに確認します。自律モードでは、ファミリーの現在の安定版メジャーバージョンに固定し、確認が必要な決定事項として PR に明記します（# go.mod has no version line — defaulting to a recent stable; confirm）。

2.4 開発コマンドの選択

手掛かり	開発コマンドのデフォルト
scripts.dev がある package.json	npm run dev
scripts.start がある package.json（dev はない）	npm start
go.mod	bash（Go プロジェクトでは通常、go run を手動で実行できるシェルを使います）
spring-boot-maven-plugin がある pom.xml	mvn spring-boot:run
FastAPI/Flask を使う pyproject.toml	bash（プロジェクトによる違いが大きいため、デフォルトを指定できません）
web: 行がある Procfile	web: の値
Compose の entrypoint/command が sleep infinity または tail -f /dev/null	bash — これは開発コンテナー用のプレースホルダーです（コンテナーを起動したままにして、そこでコマンドを実行するためのものです）。実際のコマンドではありません。dev.<svc>.command にコピーしないでください。まさにこのパターンを Okteto の dev: が置き換えます。
上記のいずれにも該当しない	bash

2.5 検出結果が曖昧な場合

検出結果に実質的な曖昧さが残る場合は、推測せず、一度に1つ、的を絞った質問をしてください。例：

• 「api/ と web/ に Dockerfile がありますが、compose ファイルは見つかりませんでした。両方をサービスにしますか？」
• 「chart/ と infra/helm/ に Helm チャートがあります。正規のデプロイに使うのはどちらですか？」
• 「このリポジトリには docker-compose.yml と Helm チャートの両方があります。deploy: ではどちらを使いますか？compose ファイル、チャート、それとも両方ですか？（Compose は開発で、チャートは本番環境でよく使われますが、決めつけたくありません。）」
• 「compose ファイルが複数あります。ルートにある docker-compose.yml と docker/docker-compose.dev.yml のうち、ソースからビルドする開発方法を示しているのはどちらで、スタックのデプロイにはどちらを使えばよいですか？」
• 「package.json に scripts.dev がありません。開発サーバーを起動するコマンドは何ですか？」

ユーザーにあらゆることを質問しないでください。推測が間違っている可能性が高い場合に限り、質問してください。手がかりを信頼してください。

自律モードでは、質問しないでください。 最も保守的な解釈を選んで作業を進め、曖昧な点は PR の説明に記載してください（セクション 7.2 で説明します）。

2.6 フェーズ 1 の出力

内部的には、次のようなモデルができているはずです。

Services: [api, web, worker]
api:    Dockerfile @ ./api,    port 8080, dev cmd `bash`,        dev image `okteto/golang:1.22`
web:    Dockerfile @ ./web,    port 3000, dev cmd `npm run dev`, dev image `okteto/node:20`
worker: Dockerfile @ ./worker, no port,   dev cmd `bash`,        dev image `okteto/python:3.12`
Deploy: helm chart at ./chart
Tests: detected `go test ./...` in api, `npm test` in web

フェーズ 2 に進む前に、この概要をユーザーに提示してください。

3. フェーズ 2 — スコープを調整する

ドラフトを作成する前に、選択肢を提示し、段階的なレベルから1つ選びます。

3.1 説明ブロック（必ずユーザーに提示）

Okteto では、deploy: は Docker Compose ファイル、Helm チャート、または k8s マニフェストから環境をプロビジョニングする方法を示します。dev: は、ファイル同期、開発用イメージ、起動コマンドを使って、実行中のサービスをライブ編集する方法を示します。スタックをデプロイする方法がすでにある場合は dev: だけで Okteto を使用できます。また、デプロイと開発の両方を Okteto に任せることもできます。

同じ説明を、生成する okteto.yaml の先頭にヘッダーコメントとして記載します。

3.2 段階的なレベル

レベル	生成される内容	必要条件
1 — 開発のみ	dev: セクションのみ。ユーザーは別途、自分でデプロイを実行します。	追加条件なし。
2 — デプロイ＋開発	build:、deploy:、dev:。okteto deploy でスタックを起動します。	リポジトリに Helm チャート、k8s マニフェスト、または Docker Compose ファイルがあること。
3 — ライフサイクル全体	既存のテストコマンドに接続した test: コンテナーを追加します。	レベル 2 の必要条件に加え、テストが検出されていること。

3.3 推奨レベルの判断ロジック

フェーズ 1 で見つかった内容に基づいてレベルを推奨します。

デプロイソースとは、Helm チャート、k8s マニフェスト、またはデプロイ可能な Docker Compose ファイルです。

• デプロイソースが見つかり、テストも検出された → レベル 3を推奨
• デプロイソースが見つかり、テストはない → レベル 2を推奨
• デプロイソースがない（チャート、k8s マニフェスト、compose のいずれもない） → レベル 1を推奨（上位レベルが選べない理由も説明）

複数のデプロイソース（例：compose とチャートの両方）がある場合は、ドラフトを作成する前に、どれを deploy: に使うか確認してください（セクション 2.5）。チャートをデフォルトにしないでください。

続いて、ユーザーに質問するか（協働モード）、推奨をそのまま採用します（自律モード）。

「調査結果に基づくと、レベル [N] をおすすめします。このレベルで進めますか？別のレベルを選ぶか、トレードオフの説明を求めることもできます。」

3.4 レベルの確定

いったん選択したレベルは、セッションの残りの間、変更できません。作業の途中でレベルを交渉し直さないでください。ドラフトの作成後に別のレベルが必要だと判明した場合（例：チャートに問題がある場合）は、フェーズ 5 の失敗として提示し、フェーズ 2 に戻って改めて進めてください。

4. フェーズ 3〜4 — ドラフトを作成して改善する

4.1 ドラフト（フェーズ 3）

リポジトリのルートに okteto.yaml を作成します。ユーザーには概要だけでなく、実際のファイルを提示する必要があります。

すべてのドラフトに必須の内容：

1. ヘッダーコメントブロック — セクション 3.1 の枠組みに加え、このファイルは okteto-onboarding によって生成され、ユーザーが編集する想定であることを記載します。選択したスコープレベルと、その理由を一文で記載してください。

2. build: セクション（レベル 2 以上） — サービスごとに 1 エントリーを記載し、context と dockerfile を含めます。ビルド済みイメージはここでは省略します（dev.<svc>.image の下に直接記載します）。

3. deploy: セクション（レベル 2 以上） — 選択したデプロイソースを指定します。

   • Compose: deploy: { compose: docker-compose.yml }（任意で services: のサブセットを指定）。リポジトリにチャートやマニフェストがない場合に最も簡単な方法です。
   • Helm: helm upgrade --install コマンドを使い、ビルドしたイメージを --set ...=${OKTETO_BUILD_<SERVICE>_IMAGE} で渡します（下記「ビルドしたイメージの接続」を参照）。
   • k8s マニフェスト: kubectl apply -f ... コマンドを使います。

   下記のスキーマ例を参照してください。

4. dev: セクション（常に記載） — 開発モードで使うサービスごとに 1 エントリーを記載し、image、command、sync を含めます。キー名は Okteto がデプロイするワークロードと一致させる必要があります。

   • Compose リポジトリ: Compose サービス名（マッピング表、セクション 2.2）。
   • Helm／k8s リポジトリ（Compose なし）: チャート／マニフェストが作成する Kubernetes ワークロードの名前、つまり Deployment／StatefulSet の metadata.name（チャートをレンダリングするか、マニフェストを確認して特定します）。デプロイされたワークロードと一致しない dev: キーは接続されません。

   リポジトリの構成にかかわらず、image、command、sync は Dockerfile と言語マニフェスト（セクション 2.3～2.4）から決定します。

5. test: セクション（レベル 3） — 検出されたテストコマンドごとに 1 エントリーを記載します。下記のスキーマ例を参照してください。

同期パスのデフォルト：

• 単一サービスのリポジトリ（ルートに Dockerfile または言語マニフェストが 1 つある場合）：.:/usr/src/app が妥当なデフォルトです。Dockerfile で WORKDIR が設定されている場合は、右側に /usr/src/app ではなくそのパスを使います。
• 複数サービスのリポジトリ（サービスごとの Dockerfile がある、または複数のサービスを含む Compose の場合）：各サービスの同期対象を、それぞれのサブディレクトリに限定します（例：./api:/usr/src/app）。リポジトリ全体をすべてのコンテナーに同期するのは、ほとんどの場合適切ではありません。

明白でない選択にはすべてインラインコメントが必要です（イメージの選択、コマンドの選択、同期パス、forward: のポート）。イメージとコマンドの選択は、デフォルトで明白ではないものとしてコメントを付けてください。

deploy: と dev: へのビルド済みイメージの接続。 build: の下で定義したイメージは Okteto Registry にプッシュされ、マニフェスト内の他の部分から環境変数として参照できます。

• OKTETO_BUILD_<SERVICE>_IMAGE — イメージの完全な参照（通常はこれを使います）
• OKTETO_BUILD_<SERVICE>_REGISTRY、_REPOSITORY、_SHA — 必要に応じて使う各要素

<SERVICE> は build: のキーを大文字にし、- を _ に置き換えたものです（例：build.web-api → OKTETO_BUILD_WEB_API_IMAGE）。デプロイされたワークロードで、古いイメージやハードコードされたイメージではなく、新しくビルドしたイメージを実行するために、これらを使ってください。

• Helm: --set api.image=${OKTETO_BUILD_API_IMAGE}
• k8s マニフェスト: kubectl apply の前に値を置換する（例：envsubst）、またはイメージフィールドをテンプレート化します。
• Compose: build: セクションはサービス名に基づいて、一致する Compose の image: をすでに上書きするため、--set は不要です。
• dev:: 汎用ツールチェーンイメージではなく、ビルド済みのアプリケーションイメージを使って開発する場合は、dev.<svc>.image: ${OKTETO_BUILD_<SVC>_IMAGE} を設定します（セクション 2.3）。

例：レベル 2／3 の断片（build + deploy + dev + test）

build:
  api:
    context: ./api
    dockerfile: Dockerfile  # using the existing Dockerfile

deploy:
  - name: Deploy chart
    command: helm upgrade --install myapp ./chart --set api.image=${OKTETO_BUILD_API_IMAGE}  # built api image wired in

dev:
  api:
    image: okteto/golang:1.23  # tag from api/go.mod (go 1.23)
    command: bash               # Go services usually want a shell to `go run` manually
    sync:
      - ./api:/usr/src/app      # per-service sync; tighten if you have large generated dirs

test:
  api:
    image: okteto/golang:1.23
    context: ./api
    commands:
      - go test ./...           # detected from the project's test layout

例：レベル 2 の断片（Compose によるデプロイ、チャートなし）

build:
  api:
    context: ./api
    dockerfile: Dockerfile

deploy:
  compose: docker-compose.yml   # deploy the stack straight from compose — no chart or k8s manifests needed

dev:
  api:
    image: okteto/golang:1.23   # tag from api/go.mod (go 1.23)
    command: bash
    sync:
      - ./api:/usr/src/app

Compose をデプロイに使う場合の注意点。 ローカル開発向けに書かれた Compose ファイルは、そのままではクラスターに正常にデプロイできないことがよくあります。deploy: compose: を使うと決める前に、Compose ファイルを確認し、以下についてユーザーに警告してください。

• ホスト IP のポートバインディング（例：127.0.0.1:9229:9229）— Okteto の compose デプロイでは拒否されます（Host IP is not allowed）。ホスト IP のプレフィックスを削除してください（9229:9229）。
• ソースのバインドマウントボリューム（例：./api:/usr/local/app）— クラスター上では空のボリュームになり、イメージ内のアプリケーションコードを覆い隠すため、サービスがクラッシュします（can't open file 'app.py'）。これらはデプロイする compose ではなく、dev.<svc>.sync に記述します。

compose ファイルがこうした開発専用の構成に依存している場合は、デプロイ時に初めて気付くのではなく、最初に明示してください。推奨順は次のとおりです。

1. デプロイ可能な compose を生成する — 元のファイルからクラスターで問題になる部分を取り除いた compose.okteto.yaml を生成し、deploy: compose: compose.okteto.yaml を指定します。詳しくは、以下の「デプロイ可能な compose の生成」を参照してください。
2. 既存のデプロイ用 compose を再利用する — リポジトリにすでに用意されている場合（例：開発用ボリュームやポートを含まない *.preview* や本番用 compose）、deploy: compose: でそのファイルを指定します。
3. リポジトリにチャートがある場合は、代わりに deploy: でチャート／k8s マニフェストを使います。compose が dev: を動かす一方で、チャートを deploy: に使うのが適切なケースがあるのはこのためです（セクション 2.5）。

デプロイ可能な compose（compose.okteto.yaml）の生成。 compose をデプロイ元に選んだものの、ファイルに開発専用の構成が含まれている場合は、ユーザーの元ファイルを編集せず、派生コピーを作成してください。これはユーザー自身のファイルに機械的な変換を施したものであり、手作業で作成したデプロイ用アーティファクトではありません。そのため、ソースとの差分としてユーザーに提示してください。参照先は明示的に deploy: { compose: compose.okteto.yaml } と指定します。次の変換を適用してください。

• ホスト IP のポートプレフィックスを削除する — 127.0.0.1:9229:9229 → 9229:9229。デバッグ専用ポート（インスペクター）は完全に削除しても構いません。これらは dev.<svc>.forward に記述します。
• ソースのバインドマウントボリュームを削除する — ./src:/app などです。イメージにはすでにコードが含まれています。これらは dev.<svc>.sync に記述します。名前付きボリューム／データボリューム（例：db-data）は残してください。
• 開発コンテナー用プレースホルダーを置き換える — entrypoint／command が sleep infinity のサービスは、デプロイ時にアプリを実行できません。実際の起動コマンド（Dockerfile の CMD または本番用 compose から取得）に戻すか、オーバーライドを削除してください。

変換だけでは暗黙に修正できない点が 2 つあります。問題が解決したかのように見せるのではなく、ユーザーに伝えてください。

• ホストパスの設定／スクリプトマウント（例：コンテナーのエントリポイントとしてマウントされた初期化スクリプト）— マウントを削除してもサービスは動作しません。ファイルをイメージに含める必要があります。マウントは残し、警告してください。
• スキャンでは判断できない、その他のサービス固有の項目。

compose.okteto.yaml にヘッダーコメントを追加し、スキルが <original> から派生させたこと、変更内容、編集または再生成しても問題ないことを記載してください。生成されるファイルはベストエフォートです。スタックが実際に起動することを確認するため、引き続きフェーズ 5 の手順（検証 → ビルド → デプロイ）を進めてください。

例：レベル 1 の断片（開発専用、単一サービス）

dev:
  myapp:                        # service name from pyproject.toml [project] name
    image: okteto/python:3.12   # pyproject.toml declares requires-python >=3.12
    command: bash               # no FastAPI/Flask signal — shell is the safe default
    sync:
      - .:/usr/src/app          # full-repo sync; exclude .venv, __pycache__ if they grow

パフォーマンスの改善は、最初のデプロイに成功してから行います。 上記のドラフトは意図的にシンプルにしています。検証とデプロイが成功したら、okteto-manifest-optimizer スキルで最適化します。スコープを限定した .stignore／.dockerignore、volumes 内の依存関係ディレクトリ、resources、test.caches などです。まず動作するマニフェストを用意してください。これらをここにまとめて追加しないでください。

4.2 改善（フェーズ 4）

ファイルをユーザーに見せます。協調モードでは、次のように尋ねます。

「こちらがドラフトです。検証の前に変更したいところはありますか？よくある編集としては、node_modules／vendor／target を除外するよう同期パスを調整する、開発用イメージのバージョンを変更する、環境変数を追加する、デプロイコマンドを変更する、などがあります。」

よくある編集パターン：

ユーザーの発言	編集
「node_modules を除外して」	sync を !node_modules の除外パターンを含むリストに変更するか、より具体的なパスを使用します
「代わりに Go 1.21 を使って」	image: を okteto/golang:1.21 に更新します
「この環境変数が必要です」	dev.<svc>.environment: に追加します
「自分の値ファイルを使って」	deploy: の Helm コマンドに -f values.staging.yaml を追加します

編集はすぐにできるので、ユーザーが納得するまで続けてください。 ユーザーが「よさそうです」などの同意を示すまでは、フェーズ 5 に進まないでください。

自律モードでは、質問せずにフェーズ 5 へ直接進みます。編集の要望は PR のレビューを通じて伝えられます。

5. フェーズ 5 — 検証（段階別）

環境で可能な範囲で検証の段階を進めます。ティア 1 は必須です。ティア 2 と 3 は任意です。

5.1 ティア 1 — okteto validate（常に実施）

次を実行します。

okteto validate

検出できるもの： YAML の構文エラー、スキーマ違反、必須フィールドの欠落。 検出できないもの： 誤った同期パス、deploy: 内のサービス不足、壊れた Helm 参照、ビルドに失敗するイメージ。

失敗した場合はフェーズ 4 の問題として扱い、続行する前に修正します。

ティア 1 に合格しない限り、このスキルは完了しません。

5.2 ティア 2 — okteto build（Dockerfile または build: がある場合に提案）

事前確認として、okteto context show を実行します。エラーになるか、コンテキストが返されない場合は、ティア 2 をスキップして、ユーザーに次のように伝えます。

「Okteto コンテキストがないため、ビルドチェックをスキップします。マニフェストの構文は有効ですが、Dockerfile のビルドは確認していません。」

それ以外の場合は、次のように尋ねます。

「okteto build を実行して、すべての Dockerfile が解決され、プッシュされることを確認できます。サービスごとに数分かかります。スキップ／1 つのサービスをビルド／すべてビルド、どれにしますか？」

デフォルトではすべてビルドします。サービスが多数（≥ 4）あり、ユーザーが急いでいる場合は、対象を絞ることを提案します。

次を実行します。

okteto build

または

okteto build <service>

5.3 ティア 3 — okteto deploy --wait（ティア 2 に合格し、ユーザーにコンテキストがある場合に提案）

注：okteto deploy --dry-run フラグはありません。ティア 3 で選べるのは、完全なデプロイのみです。

次のように尋ねます。

「マニフェストがエンドツーエンドで機能することを確認するため、完全なデプロイを実行できます。これにより、名前空間 <ns> にリソースが作成されます。成功したら、エンドポイントを表示します。必要であれば、その後で okteto destroy を実行できます。続行しますか？」

次を実行します。

okteto deploy --wait
okteto endpoints

成功した場合： エンドポイントを表示します。自動で okteto destroy を実行しないでください。実行するかどうかはユーザーが決めます。

5.4 いずれかのティアで失敗した場合

1. CLI のエラーを一字一句そのまま提示します。 言い換えないでください。
2. マニフェスト内で該当するセクションに基づいて、考えられる原因を診断します（例：Helm エラー → deploy:、ビルドエラー → build: または Dockerfile）。
3. マニフェストの具体的な編集案を提示します。「X を変更してください」ではなく、差分を示してください。
4. ユーザーが修正を承認した後：
   • 編集によってマニフェストの構造（セクションの追加／削除／名前変更、YAML の形状の変更）が変わった場合は、新たなスキーマの問題を検出するため、まずティア 1を再実行し、その後で失敗したティアを再実行します。
   • 編集が値の変更（イメージのバージョン、同期パス、環境変数）のみの場合は、失敗したティアのみを再実行します。

5.5 最終的な要約

検証の段階を進め終えた（または中断した）時点で、次のように要約します。

「✅ okteto validate に合格しました ✅ すべてのサービスで okteto build に合格しました ⏭️ okteto deploy はスキップしました（実行しない選択をされました） 次の手順：/dev-setup を実行するか、okteto スキルを呼び出してデプロイし、開発を開始してください。」

環境の都合でティアをスキップした場合（コンテキストがない場合）は、次のように伝えます。

「⚠️ Okteto コンテキストがないため、ティア 2 と 3 をスキップしました。マニフェストの構文は有効ですが、デプロイのテストは行っていません。」

6. フェーズ 6 — 引き継ぎまたは PR

6.1 協働モード：引き継ぎ

ユーザーに次の手順を案内します。

「マニフェストの準備ができました。環境を起動するには、次のいずれかを実行してください。

• /dev-setup を実行して、ガイド付きのデプロイと開発モードを利用する
• または、今後のセッションで okteto スキルを呼び出す。先ほど作成したマニフェストを使用します

マニフェストを変更した場合は、okteto validate を再実行するか、もう一度私に相談してください。」

実行した検証ティアと、スキップした検証ティアを明記します（セクション 5.5 を参照）。

マニフェストを削除したり、okteto destroy を実行したり、リモートにプッシュしたりしてはいけません。 成果物はディスク上のファイルです。

6.2 自律モード：PR

ブランチを作成し、マニフェストをコミットしてプッシュし、PR を作成します。PR が人間によるレビューの関門となります。

以下のコマンドを実行する前に、すべての <placeholder> を Phase 1 / Phase 5 の結果に基づく実際の値に置き換えてください。 実際の PR に、<list>、<N>、<bulleted list of services...> などの文字列をそのまま含めてはいけません。検証チェックリストでは、ティアに合格した場合は [x]、スキップまたは失敗した場合は [ ] を使用してください。

git checkout -b okteto/onboarding
git add okteto.yaml
git commit -m "Add Okteto manifest

Generated by okteto-onboarding skill.
Discovered services: <list>
Scope level: <N>
Validation: <tiers passed>"
git push -u origin okteto/onboarding
gh pr create --title "Add Okteto manifest" --body "$(cat <<'EOF'
## Summary
This PR adds an Okteto manifest generated by the `okteto-onboarding` skill.

## Discovered services
<bulleted list of services with their Dockerfiles and dev commands>

## Scope level
Level <N> — <one-sentence rationale>

## Validation
- [<x or space>] `okteto validate` passed
- [<x or space>] `okteto build` ran for all services
- [<x or space>] `okteto deploy --wait` succeeded with endpoints

## Decisions to confirm
- [ ] Dev image picks (e.g., `okteto/golang:1.22`) match your toolchain
- [ ] Sync paths exclude appropriate generated dirs (node_modules, vendor, target)
- [ ] Helm/kubectl deploy command matches your usual workflow

🤖 Generated by the okteto-onboarding skill
EOF
)"

このスキルは PR をマージしません。人間がレビューしてマージします。

7. 動作モード

7.1 協働モード（デフォルト）

ユーザーが作業に関与します。判断が必要な各フェーズで質問を行います。デフォルトは提示しますが、自動選択はしません。

7.2 自律モード（オプトイン）

人間の介入は想定されません。既存の okteto スキルと同様に、コンテキストから推定されます。たとえば、CI パイプラインやチケット主導のセッションから呼び出された場合です。

自律モードでは：

• スコープレベル → 検出結果でサポートされる最高レベルを選択します。レベル 2 にはデプロイ元（チャート、k8s マニフェスト、またはデプロイ可能な compose ファイル）が必要です。レベル 3 にはさらに、検出されたテストが必要です。デプロイ元がまったくない場合は、テストが存在していてもレベル 1 にとどめます。compose とチャートの両方がある場合は、より保守的なデプロイ元を選び、その選択を PR に記載します。
• 検証ティア → 常にティア 1 を実行します。okteto context show が成功した場合はティア 2 を実行します。ティア 3 は、トリガーでデプロイが明示的に許可されている場合（ラベル、環境変数、または明示的な指示）のみ実行します。
• 検出時の曖昧さ → 最も保守的な解釈を選び、PR の説明に記載します。
• Phase 6 → 常に PR を作成し（セクション 6.2）、引き継ぎは行いません。

8. CLI クイックリファレンス

コマンド	実行タイミング	目的
okteto validate	Phase 5 ティア 1（常に）	マニフェストの構文とスキーマを確認する
okteto context show	Phase 5 の事前チェック	ティア 2/3 の前にクラスター接続を確認する
okteto build [<service>]	Phase 5 ティア 2	Dockerfile が解決され、プッシュされることを確認する
okteto deploy --wait	Phase 5 ティア 3	エンドツーエンドの検証を行う
okteto endpoints	Phase 5 ティア 3	デプロイ成功後に URL を表示する

このスキルから okteto up を実行してはいけません。これは対話型であり、既存の okteto スキルまたはユーザーが実行するものです。okteto destroy を実行してもいけません。ユーザーに任せてください。

9. 避けるべきよくある間違い

• すでに okteto.yaml が存在するのに処理を開始する。 必ずセクション 1 の事前チェックを行ってください。
• Helm チャートや k8s マニフェストを生成する。 このスキルではデプロイ用アーティファクトを作成しません。ユーザーがチャートも k8s マニフェストも デプロイ可能な compose ファイルも 持っていない場合は、レベル 1 を推奨して終了してください。compose ファイルだけでも、deploy: compose: によるレベル 2 には十分です。チャートがないという理由だけでレベル 1 に下げないでください。（唯一の例外は、ユーザー自身の compose を機械的に変換して作成する compose.okteto.yaml（セクション 4.1）です。一から作成するチャートや k8s マニフェストではありません。）
• compose ファイルもあるのに、チャートが deploy: を決めると思い込む。 ユーザーにどちらを使いたいか尋ねてください（セクション 2.5）。黙ってチャートを選ばないでください。
• 開発専用の構成を調べずに deploy: compose: を推奨する。 ホスト IP を指定したポートバインドやソースのバインドマウントボリュームは、クラスターへのデプロイを妨げます（セクション 4.1 の注意事項）。デプロイ時に初めて伝えるのではなく、あらかじめユーザーに警告してください。
• ルートの docker-compose.yml だけを読む。 プロジェクトでは、開発用 compose が docker/ の下や *.dev.yml として公開イメージ用のルート compose とは別に置かれていることがよくあります。すべての compose ファイルを glob で検索し、include: もたどってください（セクション 2.1）。公開イメージ用の compose から dev: を作ると、役に立たないマニフェストになります。
• すべての compose サービスを dev: に入れる。 データベース、キャッシュ、オブジェクトストア、ブローカーなどのバックエンドサービスは、デプロイ専用のインフラストラクチャです。dev: に含めるのは編集するサービスです（セクション 2.2）。
• sleep infinity のエントリーポイントを dev.<svc>.command にコピーする。 これは開発コンテナー用のプレースホルダーであり、実際のコマンドではありません。bash を使用してください（セクション 2.4）。
• 開発イメージのバージョンをハードコードする。 リポジトリで宣言されているバージョンを確認してください（セクション 2.3）。何も宣言されていない場合に限りデフォルト値を使い、その場合はデフォルト値であることを明記してください。
• ビルドしたイメージを後続の処理に渡し忘れる。 build: エントリーだけでは Helm／k8s のデプロイに不十分です。デプロイコマンドに ${OKTETO_BUILD_<SERVICE>_IMAGE} を渡し、今ビルドしたイメージでワークロードが実行されるようにしてください。
• 説明ブロックを省略する。 セクション 3.1 の dev: と deploy: の説明は、ユーザーに提示するとともに、マニフェストのヘッダーコメントとしても記述する必要があります。
• okteto context show を先に確認せず、検証の段階を進める。 レベル 2 と 3 には、動作するコンテキストが必要です。
• 検証に失敗した際、CLI エラーを言い換える。 出力をそのまま表示してください。ユーザー（または次のエージェント）が Okteto の出力を正確に確認する必要があります。
• 何でもユーザーに尋ねる。 フェーズ 1 で得た情報を信頼してください。調査結果が本当に曖昧な場合にのみ尋ねてください。
• 自律モードで PR をマージする。 PR は人間が確認するための関門です。決してマージしないでください。
• okteto/samples/ のテンプレートを推奨する。 これらはデモです。テンプレートではなく、調査で判明した事実に基づいてマニフェストを作成してください。