okteto

Okteto 開発環境スキル

あなたは Okteto を利用した開発環境で作業する AI エージェントです。このスキルでは、次の 2 つの運用モードについて説明します。

1. 共同作業モード -- 開発者があなたと一緒に作業しています
2. 自律モード -- あなたが独立して作業しています（例：チケット、PR、CI パイプラインによって起動された場合）

運用ルール

以下の 5 つのルールは、よくある失敗を防ぐためのものです。このスキルの残りの部分では、これらのルールを詳しく説明します。

1. まず okteto.yaml を読みます。 サービス、ビルド、テストはこのファイルから特定してください。名前をハードコードしないでください。
2. okteto up は実行しないでください。 インタラクティブなコマンドであり、処理が停止してしまいます。共同作業モードではユーザーが実行します。自律モードでは実行する必要がありません。
3. クラスターの変更は Okteto 経由でのみ行います。 okteto build と okteto deploy を使い、ローカルでの docker build や kubectl apply／helm upgrade は実行しないでください。読み取り専用の kubectl／helm（get、describe、logs、events、helm status）は診断に使用できます。
4. 1 つのワークツリーにつき 1 つの名前空間を使用します。 Git ワークツリーで作業するときは、専用の名前空間を作成し、すべてのコマンドで -n <ns> を指定してください（ワークツリーの分離を参照）。
5. 許可なく破棄しないでください。 okteto destroy と okteto namespace delete の実行には、明示的なポリシーまたは指示が必要です（クリーンアップとティアダウンを参照）。

ステップ 1：プロジェクトを確認する

プロジェクトのルートにある okteto.yaml を読みます。このファイルが信頼できる情報源です。

• build：コンテナーイメージを持つサービス
• deploy：サービスのデプロイ方法（通常は Helm チャート）
• dev：開発モードに対応するサービス、そのイメージ、同期パス、コマンド
• test：利用可能なテストコンテナーと実行方法

このファイルを解析して、プロジェクトのサービス、言語、構成を把握してください。サービス名をハードコードして想定せず、必ず okteto.yaml から特定してください。

ステップ 2：運用モードを判断する

共同作業モード -- 開発者が作業に参加しており、インタラクティブなコマンドを実行します。次の場合に使用します。

• IDE またはターミナルでユーザーがあなたと会話している
• サービスのデバッグ、セットアップ、開発を手伝ってほしいと依頼された

自律モード -- あなたが最初から最後まで独立して作業します。次の場合に使用します。

• チケット（Jira、Linear、GitHub Issue など）によって起動された
• CI/CD パイプラインの一部として実行されている
• 実行中に人間が介入することを想定していない

---

共同作業モード

環境のセットアップ

1. 前提条件を確認する：okteto version と okteto context show を実行します
2. ワークツリーを分離する（該当する場合）：Git ワークツリーの場合は、ワークツリーの分離に従って名前空間を作成し、以下のすべてのコマンドに -n <ns> を追加します
3. デプロイする：okteto deploy --wait を実行し、イメージをビルドしてすべてのサービスをデプロイします
4. エンドポイントを表示する：okteto endpoints を実行して公開 URL を表示します
5. 特定のサービスで開発を始めるようユーザーに案内する：okteto up <service> を実行してもらいます

okteto up のルール

okteto up はインタラクティブなコマンドであり、必ずユーザーが自分のターミナルで実行する必要があります。 このコマンドはライブファイル同期を有効にしたまま、開発コンテナー内のシェルを開きます。バックグラウンドタスクや & を使う場合も含め、決してあなた自身で実行しないでください。代わりに、ユーザーに次のように伝えてください。

Run this in your terminal: okteto up <service>

ワークツリーを分離している場合（ワークツリーの分離を参照）は、正しい環境に接続できるよう、名前空間を含めてください。

Run this in your terminal: okteto up <service> -n <ns>

開発者との作業

ユーザーが okteto up <service> を実行したら、次のように作業します。

• 診断を実行する：okteto exec -- <command> で開発コンテナー内のコマンドを実行します
• 同期されたファイルを読む：Read ツールを使って、クラスターに同期されているコードを確認します
• 貼り付けられた出力を分析する：ユーザーがエラーに遭遇した場合、ターミナルの出力を貼り付けてもらえます
• ログを確認する：コンテナーのログには okteto logs <service> を使います
• テストを実行する：okteto.yaml で定義されたテストコンテナーには okteto test <test-name> を使います

あなたの役割はユーザーのワークフローを支援することであり、ターミナルのセッションを監視しようとすることではありません。

デバッグパターン

状況	対応
ユーザーがテストの実行を依頼した	okteto exec -- make test または言語に適したコマンドを実行します
ユーザーがエラーを貼り付けた	関連するコードを読み、分析して修正案を提案します
ユーザーが「なぜ失敗するのですか？」と尋ねた	okteto exec で診断を実行します
ユーザーがソースコードを変更した	変更は自動で同期されます。次の手順の実行を支援します
ユーザーがビルド入力（Dockerfile、依存関係、okteto.yaml）を変更した	同期されません。再ビルドして検証します（同期ではなく再ビルドが必要な変更を参照）
ユーザーが E2E テストの実行を依頼した	okteto.yaml に記載された <test-name> に対して okteto test <test-name> を実行します

同期ではなく再ビルドが必要な変更

ファイル同期の対象は、実行中のコンテナが実行時に読み込むファイルだけです。ビルド時にイメージに組み込まれるものは対象外です。以下を変更すると、再ビルドするまで環境が古い状態になります。

• Dockerfile または .dockerignore
• 依存関係のマニフェスト（go.mod／go.sum、package.json、requirements.txt、pom.xml、...）
• コンパイル済みバイナリ、またはビルド手順で生成されるもの
• okteto.yaml 自体

再ビルドして、正常に動作することを確認します。

okteto build <service>      # rebuild the image through the Okteto Build Service
okteto deploy --wait        # redeploy with the new image

okteto.yaml を変更した場合は、デプロイの前に okteto validate を実行します。マニフェストに問題があるとデプロイの途中で失敗し、環境が中途半端に更新された状態になります。

okteto validate
okteto deploy --wait

依頼されなくても、これを実行してください。 手元のマシンでビルドできる Dockerfile でも、Build Service では失敗する場合があります。たとえば、.dockerignore で除外されたファイル、欠落した go.sum、ベースイメージが対応できないツールのバージョンなどが原因です。確認するには、実際にビルドするしかありません。成功した場合はエンドポイントを、失敗した場合はエラーと修正内容を報告します。デプロイできるまで繰り返します。

必須のサブスキル： 環境の障害や異常（CrashLoopBackOff、OOMKilled、ImagePullBackOff、Pending のままのポッド、デプロイの失敗、ファイル同期の不具合）がある場合は、okteto-debugging スキルを使用してください。完全なトリアージ手順と、障害の種類ごとの対応手順が記載されています。

---

自律モード

開発者が介在しない状態で作業する場合は、環境のセットアップ、コード変更、検証、報告まで、ライフサイクル全体を担当します。okteto up は対話型で人間による操作が必要なため、使用しないでください。代わりに、環境全体のデプロイには okteto deploy を、検証には okteto test を使用します。

ワークフロー

1. タスクを把握する：チケット／issueを読み、変更が必要な内容と受け入れ条件を確認します。

2. 環境をデプロイする：

   • okteto context show を実行して、クラスターへの接続を確認し、アクティブな名前空間を確認します
   • この作業が複数の並行ブランチ／worktreeのうちの1つである場合は、まず分離された名前空間を作成し（Worktree isolationを参照）、以下のすべてのコマンドに -n <ns> を指定します
   • okteto deploy --wait を実行して、すべてのサービスを起動します
   • okteto endpoints を実行し、後で検証するために稼働中のURLを記録します

3. コードを変更する：タスクの要件に基づいて、該当するソースファイルを編集します。Readツール、Grep、Globを使ってコードベースを調べます。サービスの構成を把握するために、サービスディレクトリと okteto.yaml を確認します。

4. 変更したサービスを再ビルドして再デプロイする：

   • okteto.yaml を変更した場合は、デプロイの前に okteto validate を実行します。不正なマニフェストがあるとデプロイの途中で失敗し、環境が中途半端な状態になります
   • okteto build <service> を実行して、変更したサービスのイメージのみを再ビルドします
   • okteto deploy --wait を実行して、更新後のイメージで再デプロイします
   • 代わりに、変更したサービスが1つだけの場合は、そのサービスを指定します：okteto build <service> && okteto deploy --wait
   • ソースコードだけでなく、Dockerfile、.dockerignore、依存関係マニフェスト、okteto.yaml などのビルド入力に変更を加えるたびに、これを実行します。自律モードでは何も同期されないため、再デプロイするまで環境は古いままです。

5. 検証する：

   • okteto.yaml にある各テストコンテナーに対して、okteto test <test-name> を実行します
   • okteto endpoints を実行し、curlなどを使って稼働中のエンドポイントをスモークテストします
   • okteto logs <service> --since 5m を確認し、変更したサービスにエラーがないか調べます

6. テストが失敗した場合は繰り返す：

   • テストの出力とログを読み、失敗の原因を調べます
   • コードを修正し、再ビルド、再デプロイして、再テストします
   • すべてのテストが合格するまで繰り返します

7. 結果を報告する：変更内容、合格したテスト、レビュー用の稼働中環境のURLをまとめます。関連するログ出力やテスト成果物も含めます。

8. クリーンアップする：以下のCleanup and teardownセクションのルールに従います。明示的な許可または事前に定められたクリーンアップポリシーがない限り、環境を破棄しないでください。

自律モードの例

Trigger: Jira ticket "PROJ-123: Add rate limiting to /api/rentals endpoint"

Agent actions (worktree on branch proj-123, isolated namespace ns=proj-123):
  1. Read ticket for requirements and acceptance criteria
  2. okteto namespace create proj-123  -> isolated namespace for this worktree
  3. okteto deploy --wait -n proj-123  -> full environment running
  4. Read okteto.yaml, explore api/ directory
  5. Edit api/handlers/rentals.go      -> implement rate limiting
  6. Edit api/handlers/rentals_test.go  -> add unit tests
  7. okteto build api -n proj-123      -> rebuild the api service image
  8. okteto deploy --wait -n proj-123  -> redeploy with changes
  9. okteto test e2e -n proj-123       -> run e2e test suite
  10. okteto logs api --since 5m -n proj-123  -> check for runtime errors
  11. curl the live endpoint to verify rate limiting behavior
  12. Commit changes, open PR
  13. Report back to PROJ-123: changes made, tests passing, PR link, live URL

（worktreeを使わない単一のチェックアウトでは、okteto namespace create の手順と -n フラグを省略します。コンテキストのデフォルトの名前空間を使用できます。）

---

Worktreeの分離

Oktetoの名前空間は分離の単位であり、okteto deploy が作成するすべてのものを保持します。名前空間はアクティブなOktetoコンテキスト（~/.okteto）から取得され、ディレクトリごとではなく、マシン全体で共通です。複数のチェックアウトを同時に扱う場合は、この点が重要になります。

worktreeではない単一のメインチェックアウトでは、コンテキストのデフォルトの名前空間を使用できます。-n は不要で、このセクションも読み飛ばせます。専用の名前空間を使うのは、並行するチェックアウトやworktreeが互いに競合する場合に限ります。このスキルでは簡潔さのために -n を省略していますが、worktreeを分離する場合は、すべてのコマンドに追加してください。

1 つのワークツリーにつき 1 つの名前空間

git worktree（または同じリポジトリの 2 つ目のチェックアウト）で作業している場合、他のワークツリーと*同じ okteto.yaml*を共有します。Helm リリースもリソース名も同じです。2 つのワークツリーが同じ名前空間にデプロイすると、次のことが起こります。

• 2 つ目の okteto deploy が、1 つ目の環境を上書きします。
• okteto endpoints／okteto logs は、別のワークツリーのデータを返します。
• 一方のワークツリーで okteto destroy を実行すると、もう一方の環境が削除されます。

分離を完全にするには、各ワークツリーに専用の名前空間を割り当ててください。

ワークツリーを検出する（判断に迷ったら確認してください）。

git rev-parse --git-common-dir   # differs from `git rev-parse --git-dir` -> you are in a linked worktree
git worktree list                # shows all worktrees of this repo
git branch --show-current        # the branch is a good basis for the namespace name

ブランチ（またはワークツリーのディレクトリ）から名前空間名を導出します。Okteto の名前空間名には、小文字の英数字と - のみを使用でき、英数字で始まり英数字で終わる必要があります。また、63 文字以内でなければなりません（正規表現 ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$）。

# branch "feat/Rate_Limiting" -> "feat-rate-limiting"
ns=$(git branch --show-current | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g; s/^-*//; s/-*$//' | cut -c1-50)

チームに命名規則（例：agent-<branch> または <user>-<branch>）がある場合は、それに従ってください。

一度作成したら、すべてのコマンドに -n を指定する

okteto namespace create <ns>     # creates it; reports if it already exists

その後、セッションの残りの間、Okteto のすべてのコマンドに**-n <ns> を指定してください**。

okteto deploy --wait -n <ns>
okteto build <service> -n <ns>
okteto endpoints -n <ns>
okteto logs <service> -n <ns>
okteto test <name> -n <ns>
okteto destroy -n <ns>

ワークツリーを分離するために okteto namespace use <ns> を使用しないでください。 これは共有のグローバルコンテキストでアクティブな名前空間を切り替えるため、同じマシン上の他のワークツリーやエージェントと競合し、他のコマンドも気付かないうちに別の名前空間へリダイレクトされます。-n フラグは呼び出しごとに指定するもので、共有状態を変更しないため、同時実行時も安全です。（okteto namespace use を使用してもよいのは、チェックアウトが 1 つだけで、同じコンテキストに対して他の処理が実行されていない場合に限ります。）

---

クリーンアップと終了処理

環境を終了することは、環境を起動することと同じくらい重要です。正しいコマンドと、適切な権限を確認してください。

適切なコマンドを選ぶ

コマンド	動作	使用する状況
okteto down	1 つのサービスの開発モードを終了し、元のデプロイ状態に戻します。環境は削除しません。	サービスでの作業は終えたものの、環境は稼働させたままにしたい場合。
okteto destroy	現在の名前空間で okteto deploy によって作成されたすべてのリソースを削除します。破壊的な操作です。	環境が不要になり、削除の承認を得ている場合。
okteto namespace delete <name>	名前空間全体と、その中のすべてを削除します。非常に破壊的な操作です。	エージェント自身が分離されたワークツリー用に作成した名前空間（ワークツリーの分離を参照）、またはユーザーから明示的な指示があった場合に限ります。タスクのクリーンアップとして、共有または既存の名前空間に対して絶対に実行しないでください。

ユーザーが開発モードの終了だけを求めていたのに、okteto destroy を実行してしまうのはよくある間違いです。判断に迷った場合は、安全な選択肢である okteto down を使用してください。

分離されたワークツリーの名前空間を終了する

ワークツリー専用の名前空間を作成した場合（ワークツリーの分離を参照）、作業が終わり、ワークツリーを削除する際に、その名前空間を削除して構いません。

okteto destroy -n <ns>           # remove the deployed resources
okteto namespace delete <ns>     # then remove the now-empty namespace you created

これは、別途指示がなくても okteto namespace delete を実行してよい唯一のケースです。自分で作成した名前空間なので、その削除についても自分が責任を持ちます。ただし、自分が作成していない名前空間に関する以下のルールが無効になるわけではありません。

共同作業モード

自分で okteto destroy を実行しないでください。提案として提示し、開発者に実行してもらってください。

You're done with this environment. To tear it down, run:
  okteto destroy

開発者がサービスの作業を明らかに終えた場合は、エージェントが okteto down を実行しても問題ありません。

自律モード

次のいずれかに該当する場合に限り、okteto destroy を実行してください。

• タスクでクリーンアップが明示的に許可されている（例：「PR がマージされたら環境を破棄する」）
• リポジトリの CLAUDE.md またはチケットに、事前に定められたクリーンアップポリシーが記載されている
• 環境が一時的なもので、パイプラインが所有している（例：実行ごとに作成されるプレビュー環境）

いずれにも該当しない場合は、環境を稼働したままにし、まだ稼働中であることと、呼び出し元が環境を破棄するときに使用するコマンドをレポートに記載してください。誰かが依存している環境を破棄するより、稼働中の環境をそのままにするほうが常に安全です。

絶対にしてはいけないこと

• 自分が作成していないネームスペースを削除する
• 明示的な指示なしに、共有環境や名前付き環境（例：staging、dev）を破棄する
• 問題発生時の復旧手段として okteto destroy を使う。まず原因を診断する

---

開発コマンドの確認

各サービスの okteto.yaml にある dev セクションを確認してください。command フィールドにサービスの起動方法が記載されています。

• command: bash の場合 -- サービスのビルドと起動は手動で行う必要があります（サービスディレクトリの Makefile、package.json、pom.xml を確認してください）
• command: yarn start または command: mvn spring-boot:run の場合 -- サービスは開発モードで自動的に起動します
• サービスディレクトリにある Makefile、package.json、pom.xml、または go.mod を確認し、利用可能なコマンドを特定してください

CLI クイックリファレンス

コマンド	協調モード	自律モード	目的
okteto deploy --wait	エージェント	エージェント	すべてのサービスのイメージをビルドしてデプロイする
okteto build <service>	エージェント	エージェント	単一サービスのイメージをビルドしてプッシュする
okteto up <service>	ユーザーのみ	禁止	インタラクティブな開発コンテナを起動する
okteto down	エージェント／ユーザー	該当なし	開発モードを停止し、デプロイを復元する
okteto exec -- <cmd>	エージェント	該当なし	アクティブな開発コンテナでコマンドを実行する
okteto logs <service>	エージェント	エージェント	コンテナログを表示する
okteto endpoints	エージェント	エージェント	公開 URL の一覧を表示する
okteto test <name>	エージェント	エージェント	okteto.yaml からテストコンテナを実行する
okteto destroy	ユーザー	ポリシーがある場合	すべてのリソースを破棄する
okteto doctor	エージェント	エージェント	診断バンドルを生成する
okteto status	エージェント	該当なし	ファイル同期の進行状況を確認する
okteto validate	エージェント	エージェント	okteto.yaml マニフェストの構文を検証する
okteto context show	エージェント	エージェント	クラスターとネームスペースを確認する
okteto namespace create <ns>	エージェント	エージェント	ワークツリー用の分離されたネームスペースを作成する
okteto namespace list	エージェント	エージェント	アクセス可能なネームスペースの一覧を表示する
okteto namespace delete <ns>	ユーザー	自分が作成したもののみ	ネームスペースを削除する（自分が作成したものに限る）

-n <ns> フラグ： 上記のすべてのコマンド（deploy、build、up、down、exec、logs、test、endpoints、destroy）は、アクティブなコンテキストを変更せずに特定のネームスペースを対象とするための -n <ns> を受け付けます。ワークツリーを分離するには、okteto namespace use ではなくこのフラグを使用してください（ワークツリーの分離を参照）。

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

• 自律モードで okteto up を実行する：シェルを操作する人間はいません。代わりに okteto deploy + okteto build + okteto test を使用してください。
• 共同作業モードでエージェントが okteto up を実行する：対話型のコマンドです。必ずユーザーに実行してもらってください。
• 最初にデプロイするのを忘れる：検証やテストの前に okteto deploy を実行してください。
• サービスを指定しない：複数のサービスがある場合は、必ず対象のサービスを指定してください。
• kubectl/helm を使ってクラスターを変更する：変更操作（kubectl apply、kubectl delete、helm upgrade など）は、Okteto がリソースを追跡できるよう、okteto deploy を通じて行う必要があります。診断目的の読み取り専用の kubectl/helm は問題ありません。
• Docker イメージをローカルでビルドする：Okteto Build Service を活用するために okteto build を使用してください。
• サービス名をハードコードする：必ず okteto.yaml を読み、サービスを確認してください。
• 許可なく破棄する：自律モードでは、明示的なクリーンアップポリシーまたは指示がない限り、okteto destroy を実行しないでください。
• 複数のワークツリーで同じ名前空間を共有する：2 つのワークツリーが同じ名前空間にデプロイすると互いの内容を上書きし、一方で destroy を実行するともう一方の内容も削除されます。各ワークツリーに個別の名前空間を割り当て（ワークツリーの分離を参照）、すべてのコマンドに -n <ns> を指定してください。
• 並行作業を分離するために okteto namespace use を使用する：グローバルなアクティブコンテキストが変更され、他のワークツリーやエージェントとの競合が発生します。代わりに、コマンドごとに -n <ns> フラグを使用してください。