okteto

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Okteto Development Environment Skill

Okteto开发环境技能

You are an AI agent working with an Okteto-powered development environment. This skill covers two modes of operation:

Collaborative -- a developer is actively working with you
Autonomous -- you are working independently (e.g., triggered by a ticket, PR, or CI pipeline)

你是一名在Okteto驱动的开发环境中工作的AI Agent。此技能涵盖两种操作模式：

协作模式——开发者与你协同工作
自主模式——你独立工作（例如由工单、PR或CI流水线触发）

Operating rules

操作规则

These five rules prevent the most common failures. The rest of this skill elaborates on them.

Read
okteto.yaml
first. Derive services, builds, and tests from it -- never hardcode names.
Never run
okteto up
. It is interactive and hangs. The user runs it in collaborative mode; it has no place in autonomous mode.

Mutate the cluster only through Okteto. Use

okteto build

and

okteto deploy

-- never local

docker build

kubectl apply

helm upgrade

. Read-only

kubectl

helm

(

get

describe

logs

events

helm status

) is fine for diagnostics.

One worktree = one namespace. When working in a git worktree, create a dedicated namespace and pass
```
-n <ns>
```
on every command (see Worktree isolation).
Never destroy without authorization.
```
okteto destroy
```
and
```
okteto namespace delete
```
require explicit policy or instruction (see Cleanup and teardown).

以下五条规则可避免最常见的故障。本技能的其余部分会对其进行详细说明。

先读取
okteto.yaml
：从中获取服务、构建和测试相关信息——绝不硬编码名称。
绝不运行
okteto up
：该命令是交互式的，会挂起。在协作模式下由用户运行；自主模式下完全不适用。
仅通过Okteto修改集群：使用
```
okteto build
```
和
```
okteto deploy
```
——绝不使用本地的
```
docker build
```
或
```
kubectl apply
```
/
```
helm upgrade
```
。用于诊断的只读
```
kubectl
```
/
```
helm
```
命令（如
```
get
```
、
```
describe
```
、
```
logs
```
、
```
events
```
、
```
helm status
```
）是允许的。
一个工作树 = 一个命名空间：在git工作树中工作时，创建专用命名空间，并在每个命令中传递
```
-n <ns>
```
参数（参见工作树隔离）。
未经授权绝不销毁：
```
okteto destroy
```
和
```
okteto namespace delete
```
需要明确的策略或指令（参见清理与拆除）。

Step 1: Discover the project

步骤1：发现项目

Read

okteto.yaml

in the project root. This is the source of truth for:

build: which services have container images
deploy: how services are deployed (usually Helm charts)
dev: which services support development mode, their images, sync paths, and commands
test: which test containers are available and how they run

Parse this file to understand the project's services, languages, and structure. Do not assume hardcoded service names -- always derive them from

okteto.yaml

读取项目根目录下的

okteto.yaml

。这是以下信息的唯一可信来源：

build：哪些服务有容器镜像
deploy：服务的部署方式（通常是Helm charts）
dev：哪些服务支持开发模式、它们的镜像、同步路径和命令
test：哪些测试容器可用以及如何运行

解析此文件以了解项目的服务、语言和结构。不要假设硬编码的服务名称——始终从

okteto.yaml

中获取。

Step 2: Determine your operating mode

步骤2：确定操作模式

Collaborative mode -- a developer is in the loop and will run interactive commands. Use this when:

A user is chatting with you in an IDE or terminal
Someone asks you to help debug, set up, or develop a service

Autonomous mode -- you are operating independently end-to-end. Use this when:

Triggered by a ticket (Jira, Linear, GitHub Issue, etc.)
Running as part of a CI/CD pipeline
No human is expected to intervene during execution

协作模式——开发者全程参与并会运行交互式命令。在以下场景使用：

用户在IDE或终端中与你聊天
有人请求你帮助调试、设置或开发某个服务

自主模式——你端到端独立操作。在以下场景使用：

由工单触发（Jira、Linear、GitHub Issue等）
作为CI/CD流水线的一部分运行
执行过程中无需人工干预

Collaborative mode

协作模式

Environment setup

环境设置

Check prerequisites: Run
```
okteto version
```
and
```
okteto context show
```
Isolate the worktree (if applicable): if this is a git worktree, create a namespace per Worktree isolation and add
```
-n <ns>
```
to every command below
Deploy: Run
```
okteto deploy --wait
```
to build images and deploy all services
Show endpoints: Run
```
okteto endpoints
```
to display the public URLs
Guide the user to start development on a specific service with
```
okteto up <service>
```

检查先决条件：运行
```
okteto version
```
和
```
okteto context show
```
隔离工作树（如适用）：如果处于git工作树中，请按照工作树隔离创建命名空间，并在以下所有命令中添加
```
-n <ns>
```
参数
部署：运行
```
okteto deploy --wait
```
来构建镜像并部署所有服务
展示端点：运行
```
okteto endpoints
```
来显示公共URL
引导用户使用
```
okteto up <service>
```
启动特定服务的开发

The

okteto up

rule

okteto up

规则

okteto up
is interactive and MUST be run by the user in their terminal. It opens a shell inside the development container with live file sync. Never run it yourself -- not as a background task, not with

, not at all. Instead, tell the user:

Run this in your terminal: okteto up <service>

If you are isolating a worktree (see Worktree isolation), include the namespace so they attach to the right environment:

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

okteto up

是交互式命令，必须由用户在其终端中运行。**它会在开发容器内打开一个shell并进行实时文件同步。绝不要自行运行它——无论是作为后台任务、带

参数，还是以任何方式运行。相反，请告知用户：

在你的终端中运行：okteto up <service>

如果正在隔离工作树（参见工作树隔离），请包含命名空间，以便用户连接到正确的环境：

在你的终端中运行：okteto up <service> -n <ns>

Working with the developer

与开发者协作

Once the user has

okteto up <service>

running:

Run diagnostics:
```
okteto exec -- <command>
```
to execute commands in the dev container
Read synced files: Use the Read tool to examine code syncing to the cluster
Analyze pasted output: When the user hits an error, they can paste terminal output
Check logs:
```
okteto logs <service>
```
for container logs
Run tests:
```
okteto test <test-name>
```
for test containers defined in okteto.yaml

You are facilitating their workflow, not trying to observe their terminal session.

当用户运行

okteto up <service>

后：

运行诊断：使用
```
okteto exec -- <command>
```
在开发容器中执行命令
读取同步文件：使用读取工具检查同步到集群的代码
分析粘贴的输出：当用户遇到错误时，他们可以粘贴终端输出
查看日志：使用
```
okteto logs <service>
```
查看容器日志
运行测试：使用
```
okteto test <test-name>
```
运行okteto.yaml中定义的测试容器

你是在协助他们的工作流程，而非试图监视他们的终端会话。

Debugging patterns

调试模式

Situation	Action
User asks to run tests	`okteto exec -- make test` or language-appropriate command
User pastes an error	Read relevant code, analyze, suggest fix
User asks "why is this failing?"	Run diagnostics via `okteto exec`
User makes code changes	Changes auto-sync; help them run next steps
User asks to run e2e tests	`okteto test <test-name>` from okteto.yaml

REQUIRED SUB-SKILL: For a broken or unhealthy environment -- CrashLoopBackOff, OOMKilled, ImagePullBackOff, pods stuck in Pending, deploy failures, or file sync not working -- use the okteto-debugging skill. It has the full triage algorithm and a playbook per failure mode.

场景	操作
用户要求运行测试	`okteto exec -- make test` 或适合对应语言的命令
用户粘贴错误信息	读取相关代码、分析并建议修复方案
用户询问“为什么失败？”	通过 `okteto exec` 运行诊断
用户修改代码	更改会自动同步；帮助他们执行后续步骤
用户要求运行端到端测试	使用okteto.yaml中的 `okteto test <test-name>`

必备子技能：对于损坏或不健康的环境——CrashLoopBackOff、OOMKilled、ImagePullBackOff、Pod处于Pending状态、部署失败或文件同步不工作——请使用okteto-debugging技能。它包含完整的分类算法和针对每种故障模式的操作手册。

Autonomous mode

自主模式

When operating without a developer in the loop, you own the full lifecycle: environment setup, code changes, validation, and reporting. Do not use

okteto up

-- it is interactive and requires a human. Instead, use

okteto deploy

for full environments and

okteto test

for validation.

在无开发者参与的情况下操作时，你需要负责完整的生命周期：环境设置、代码更改、验证和报告。不要使用

okteto up

——它是交互式的，需要人工参与。请改用

okteto deploy

部署完整环境，使用

okteto test

进行验证。

Workflow

工作流程

Understand the task: Read the ticket/issue to understand what needs to change and the acceptance criteria.
Deploy an environment:
- Run
```
okteto context show
```
  to verify cluster connection and see the active namespace
- If this run is one of several parallel branches/worktrees, create an isolated namespace first (see Worktree isolation) and pass
```
-n <ns>
```
  on every command below
- Run
```
okteto deploy --wait
```
  to spin up all services
- Run
```
okteto endpoints
```
  to capture the live URLs for later validation
Make code changes: Edit the relevant source files based on the task requirements. Use the Read tool, Grep, and Glob to explore the codebase. Inspect the service directories and
```
okteto.yaml
```
to understand service structure.
Rebuild and redeploy changed services:
- Run
```
okteto build <service>
```
  to rebuild only the changed service image
- Run
```
okteto deploy --wait
```
  to redeploy with the updated image
- Alternatively, if only one service changed, target it:
```
okteto build <service> && okteto deploy --wait
```
Validate:
- If
```
okteto.yaml
```
  was modified, run
```
okteto validate
```
  first to catch manifest errors before deploying
- Run
```
okteto test <test-name>
```
  for each test container in okteto.yaml
- Run
```
okteto endpoints
```
  and use curl or similar to smoke-test the live endpoints
- Check
```
okteto logs <service> --since 5m
```
  for errors in the changed services
Iterate if tests fail:
- Read test output and logs to diagnose the failure
- Fix the code, rebuild, redeploy, and re-test
- Repeat until all tests pass
Report results: Summarize what was changed, what tests passed, and provide the live environment URL for review. Include any relevant log output or test artifacts.
Clean up: Follow the rules in the Cleanup and teardown section below. Do not destroy without explicit authorization or a predefined cleanup policy.

理解任务：读取工单/问题以了解需要更改的内容和验收标准。
部署环境：
- 运行
```
okteto context show
```
  验证集群连接并查看活动命名空间
- 如果此运行是多个并行分支/工作树之一，请先创建隔离命名空间（参见工作树隔离），并在以下所有命令中传递
```
-n <ns>
```
  参数
- 运行
```
okteto deploy --wait
```
  启动所有服务
- 运行
```
okteto endpoints
```
  捕获实时URL以便后续验证
修改代码：根据任务要求编辑相关源文件。使用读取工具、Grep和Glob探索代码库。检查服务目录和
```
okteto.yaml
```
以了解服务结构。
重新构建并重新部署更改后的服务：
- 运行
```
okteto build <service>
```
  仅重新构建更改后的服务镜像
- 运行
```
okteto deploy --wait
```
  重新部署更新后的镜像
- 或者，如果仅更改了一个服务，可针对性操作：
```
okteto build <service> && okteto deploy --wait
```
验证：
- 如果修改了
```
okteto.yaml
```
  ，请先运行
```
okteto validate
```
  以在部署前捕获清单错误
- 为okteto.yaml中的每个测试容器运行
```
okteto test <test-name>
```
- 运行
```
okteto endpoints
```
  并使用curl等工具对实时端点进行冒烟测试
- 检查
```
okteto logs <service> --since 5m
```
  以查看更改后服务中的错误
测试失败时迭代：
- 读取测试输出和日志以诊断失败原因
- 修复代码、重新构建、重新部署并重新测试
- 重复直到所有测试通过
报告结果：总结更改内容、通过的测试，并提供用于审核的实时环境URL。包含任何相关的日志输出或测试工件。
清理：遵循清理与拆除部分的规则。未经明确授权或预定义的清理策略，绝不要销毁环境。

Autonomous example

自主模式示例

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

(On a single non-worktree checkout, drop the

okteto namespace create

step and the

-n

flags -- the context's default namespace is fine.)

触发条件：Jira工单“PROJ-123：为/api/rentals端点添加速率限制”

Agent操作（工作树位于分支proj-123，隔离命名空间ns=proj-123）：
  1. 读取工单的需求和验收标准
  2. okteto namespace create proj-123  -> 为此工作树创建隔离命名空间
  3. okteto deploy --wait -n proj-123  -> 完整环境运行中
  4. 读取okteto.yaml，探索api/目录
  5. 编辑api/handlers/rentals.go      -> 实现速率限制
  6. 编辑api/handlers/rentals_test.go  -> 添加单元测试
  7. okteto build api -n proj-123      -> 重新构建api服务镜像
  8. okteto deploy --wait -n proj-123  -> 使用更改重新部署
  9. okteto test e2e -n proj-123       -> 运行端到端测试套件
  10. okteto logs api --since 5m -n proj-123  -> 检查运行时错误
  11. curl实时端点以验证速率限制行为
  12. 提交更改，打开PR
  13. 向PROJ-123报告：已完成更改、测试通过、PR链接、实时URL

（在单个非工作树检出中，可省略

okteto namespace create

步骤和

-n

标志——上下文的默认命名空间即可。）

Worktree isolation

工作树隔离

An Okteto namespace is the unit of isolation -- it holds everything

okteto deploy

creates. The namespace comes from your active Okteto context (

~/.okteto

), which is global to the machine, not per-directory. That matters the moment you work in more than one checkout at once.

A single primary checkout (not a worktree) can use its context's default namespace -- no

-n

needed, and you can skip this section. Only reach for a dedicated namespace when parallel checkouts or worktrees would otherwise collide. The rest of this skill omits

-n

for brevity; add it to every command when you are isolating a worktree.

Okteto 命名空间是隔离的单元——它包含

okteto deploy

创建的所有资源。命名空间来自你的活动Okteto上下文（

~/.okteto

），它是机器全局的，而非按目录划分。当你同时在多个检出中工作时，这一点至关重要。

单个主检出（非工作树）可以使用其上下文的默认命名空间——无需

-n

参数，你可以跳过本节。仅当并行检出或工作树会发生冲突时，才需要使用专用命名空间。为简洁起见，本技能的其余部分省略了

-n

参数；当隔离工作树时，请将其添加到每个命令中。

One worktree = one namespace

一个工作树 = 一个命名空间

If you are working in a git worktree (or any second checkout of the same repo), you share the same
okteto.yaml
as the other worktrees -- same Helm releases, same resource names. If two worktrees deploy into the same namespace:

the second
```
okteto deploy
```
overwrites the first's environment,
```
okteto endpoints
```
/
```
okteto logs
```
return the wrong worktree's data,
an
```
okteto destroy
```
in one worktree tears down the other's environment.

Give each worktree its own namespace so the separation is complete.

Detect a worktree (when in doubt, check):

bash

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

Derive the namespace name from the branch (or worktree directory). Okteto namespace names must be lowercase alphanumeric and

, start and end with an alphanumeric character, and be at most 63 characters (regex

^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

bash

undefined

如果你在git工作树（或同一仓库的任何第二个检出）中工作，你会与其他工作树共享相同的
okteto.yaml
——相同的Helm版本、相同的资源名称。如果两个工作树部署到同一命名空间：

第二次
```
okteto deploy
```
会覆盖第一个的环境
```
okteto endpoints
```
/
```
okteto logs
```
返回错误工作树的数据
一个工作树中的
```
okteto destroy
```
会拆除另一个的环境

为每个工作树分配自己的命名空间，以实现完全隔离。

检测工作树（如有疑问，请检查）：

bash

git rev-parse --git-common-dir   # 与`git rev-parse --git-dir`不同 -> 你处于链接工作树中
git worktree list                # 显示此仓库的所有工作树
git branch --show-current        # 分支名称是命名空间名称的良好基础

从分支（或工作树目录）派生命名空间名称。Okteto命名空间名称必须是小写字母数字和

，以字母数字字符开头和结尾，且最多63个字符（正则表达式

^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

）：

bash

undefined

branch "feat/Rate_Limiting" -> "feat-rate-limiting"

分支"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)


If your team has a naming convention (e.g. `agent-<branch>` or `<user>-<branch>`), follow it.

ns=$(git branch --show-current | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g; s/^-//; s/-$//' | cut -c1-50)


如果你的团队有命名约定（例如`agent-<branch>`或`<user>-<branch>`），请遵循该约定。

Create once, then pass

-n

on every command

创建一次，然后在每个命令中传递

-n

bash

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

Then pass
-n <ns>
on every Okteto command for the rest of the session:

bash

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>

Do not use
okteto namespace use <ns>
to isolate worktrees. It switches the active namespace in the shared global context, which races with any other worktree or agent on the same machine -- silently redirecting their commands too. The

-n

flag is per-invocation and never mutates shared state, so it is safe under concurrency. (

okteto namespace use

is fine only when you have a single checkout and nothing else is running against the same context.)

bash

okteto namespace create <ns>     # 创建命名空间；如果已存在则会提示

然后在会话的所有后续Okteto命令中传递
-n <ns>
：

bash

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>

来隔离工作树。**它会切换共享全局上下文中的活动命名空间，这会与同一机器上的任何其他工作树或Agent产生冲突——悄悄重定向他们的命令。

-n

参数是每次调用的，绝不会修改共享状态，因此在并发场景下是安全的。（仅当你只有一个检出且没有其他进程针对同一上下文运行时，

okteto namespace use

才适用。）

Cleanup and teardown

清理与拆除

Tearing down an environment is as important as standing one up. Get the command right, and get the authorization right.

拆除环境与搭建环境同等重要。要选择正确的命令，并获得正确的授权。

Pick the right command

选择正确的命令

Command	What it does	When to use
`okteto down`	Exits dev mode for one service; restores the original deployment. Does not destroy the environment.	The developer is done iterating on a service but wants the environment to keep running.
`okteto destroy`	Tears down every resource created by `okteto deploy` in the current namespace. Destructive.	The environment is no longer needed and teardown is authorized.
`okteto namespace delete <name>`	Deletes an entire namespace and everything in it. Very destructive.	Only for a namespace the agent itself created for an isolated worktree (see Worktree isolation), or with explicit user instruction. Never for a shared or pre-existing namespace as cleanup from a task.

A common mistake is reaching for

okteto destroy

when the user only wanted to exit dev mode. If in doubt,

okteto down

is the safe choice.

命令	功能	使用场景
`okteto down`	退出单个服务的开发模式；恢复原始部署。不会销毁环境。	开发者完成某个服务的迭代，但希望环境继续运行。
`okteto destroy`	拆除当前命名空间中由 `okteto deploy` 创建的所有资源。具有破坏性。	环境不再需要且拆除已获授权。
`okteto namespace delete <name>`	删除整个命名空间及其中的所有内容。破坏性极强。	仅适用于Agent为隔离工作树创建的命名空间（参见工作树隔离），或有明确用户指令的情况。绝不要用于共享或预先存在的命名空间作为任务后的清理。

常见错误是当用户只想退出开发模式时使用

okteto destroy

。如有疑问，

okteto down

是安全的选择。

Tearing down an isolated worktree namespace

拆除隔离工作树的命名空间

If you created a dedicated namespace for a worktree (see Worktree isolation), that namespace is yours to remove once the work is done and the worktree is going away:

bash

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

This is the one case where

okteto namespace delete

is appropriate without a separate instruction -- you created it, so you own its teardown. It does not override the rule below for namespaces you did not create.

如果你为工作树创建了专用命名空间（参见工作树隔离），则在工作完成且工作树即将移除时，你可以删除该命名空间：

bash

okteto destroy -n <ns>           # 删除已部署的资源
okteto namespace delete <ns>     # 然后删除你创建的现已为空的命名空间

这是无需单独指令即可使用

okteto namespace delete

的唯一情况——你创建了它，因此你负责拆除它。这不会覆盖以下针对你未创建的命名空间的规则。

Collaborative mode

协作模式

Do not run

okteto destroy

yourself. Surface it as a suggestion and let the developer run it:

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

okteto down

is fine for the agent to run when the developer has clearly finished with a service.

不要自行运行

okteto destroy

。将其作为建议告知用户，让开发者自行运行：

你已完成此环境的使用。要拆除它，请运行：
  okteto destroy

当开发者明确完成某个服务的工作时，Agent可以运行

okteto down

。

Autonomous mode

自主模式

Run

okteto destroy

only when one of these is true:

The task explicitly authorizes cleanup (e.g., "destroy the environment when the PR is merged")
There is a predefined cleanup policy documented in the repo's
```
CLAUDE.md
```
or the ticket
The environment is ephemeral and owned by the pipeline (e.g., a per-run preview environment)

If none of those apply, leave the environment running and note in the report that it is still up, with the command the caller would use to tear it down. It is always safer to leave a running environment than to destroy one that someone else depended on.

仅当以下情况之一成立时，才可运行

okteto destroy

：

任务明确授权清理（例如“PR合并后销毁环境”）
仓库的
```
CLAUDE.md
```
或工单中记录了预定义的清理策略
环境是临时的且归流水线所有（例如每个运行的预览环境）

如果以上情况均不适用，请保持环境运行，并在报告中注明环境仍在运行，以及调用者可用于拆除环境的命令。保留运行中的环境比销毁他人依赖的环境更安全。

Never do this

绝对禁止的操作

Delete a namespace you did not create
Destroy a shared or named environment (e.g.,
```
staging
```
,
```
dev
```
) without explicit instruction
Treat
```
okteto destroy
```
as a recovery step when something goes wrong — diagnose first

删除你未创建的命名空间
未经明确指令销毁共享或命名环境（例如
```
staging
```
、
```
dev
```
）
当出现问题时将
```
okteto destroy
```
作为恢复步骤——先进行诊断

Discovering dev commands

发现开发命令

Look at the

dev

section of

okteto.yaml

for each service. The

command

field tells you how the service starts:

If
```
command: bash
```
-- the service needs manual build/start (check for Makefile, package.json, pom.xml in the service directory)

command: yarn start

command: mvn spring-boot:run

-- the service auto-starts in dev mode

Check for
```
Makefile
```
,
```
package.json
```
,
```
pom.xml
```
, or
```
go.mod
```
in the service directory to determine available commands

查看每个服务在

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 quick reference

CLI快速参考

Command	Collaborative	Autonomous	Purpose
`okteto deploy --wait`	Agent	Agent	Build images and deploy all services
`okteto build <service>`	Agent	Agent	Build and push a single service image
`okteto up <service>`	User only	Never	Start interactive dev container
`okteto down`	Agent/User	N/A	Stop dev mode, restore deployment
`okteto exec -- <cmd>`	Agent	N/A	Run command in active dev container
`okteto logs <service>`	Agent	Agent	View container logs
`okteto endpoints`	Agent	Agent	List public URLs
`okteto test <name>`	Agent	Agent	Run a test container from okteto.yaml
`okteto destroy`	User	With policy	Tear down all resources
`okteto doctor`	Agent	Agent	Generate a diagnostic bundle
`okteto status`	Agent	N/A	Check file sync progress
`okteto validate`	Agent	Agent	Validate okteto.yaml manifest syntax
`okteto context show`	Agent	Agent	Verify cluster and namespace
`okteto namespace create <ns>`	Agent	Agent	Create an isolated namespace for a worktree
`okteto namespace list`	Agent	Agent	List namespaces you have access to
`okteto namespace delete <ns>`	User	Self-created only	Delete a namespace (only one you created)

-n <ns>
flag: every command above (

deploy

build

up

down

exec

logs

test

endpoints

destroy

) accepts

-n <ns>

to target a specific namespace without changing the active context. Use it -- not

okteto namespace use

-- to isolate a worktree (see Worktree isolation).

命令	协作模式	自主模式	用途
`okteto deploy --wait`	Agent	Agent	构建镜像并部署所有服务
`okteto build <service>`	Agent	Agent	构建并推送单个服务镜像
`okteto up <service>`	仅用户	绝不	启动交互式开发容器
`okteto down`	Agent/用户	不适用	退出开发模式，恢复部署
`okteto exec -- <cmd>`	Agent	不适用	在活动开发容器中运行命令
`okteto logs <service>`	Agent	Agent	查看容器日志
`okteto endpoints`	Agent	Agent	列出公共URL
`okteto test <name>`	Agent	Agent	运行okteto.yaml中的测试容器
`okteto destroy`	用户	需策略授权	拆除所有资源
`okteto doctor`	Agent	Agent	生成诊断包
`okteto status`	Agent	不适用	检查文件同步进度
`okteto validate`	Agent	Agent	验证okteto.yaml清单语法
`okteto context show`	Agent	Agent	验证集群和命名空间
`okteto namespace create <ns>`	Agent	Agent	为工作树创建隔离命名空间
`okteto namespace list`	Agent	Agent	列出你有权访问的命名空间
`okteto namespace delete <ns>`	用户	仅自行创建的命名空间	删除命名空间（仅限你创建的）

-n <ns>
标志：上述所有命令（

deploy

、

build

、

up

、

down

、

exec

、

logs

、

test

、

endpoints

、

destroy

）都接受

-n <ns>

参数以指定目标命名空间，而无需更改活动上下文。请使用它——而非

okteto namespace use

——来隔离工作树（参见工作树隔离）。

Common mistakes to avoid

需避免的常见错误

Running
okteto up
in autonomous mode: There is no human to interact with the shell. Use
```
okteto deploy
```
+
```
okteto build
```
+
```
okteto test
```
instead.
Running
okteto up
as the agent in collaborative mode: It is interactive. Always tell the user to run it.
Forgetting to deploy first: Run
```
okteto deploy
```
before any validation or testing.
Not specifying the service: With multiple services, always specify which one.
Using kubectl/helm to change the cluster: Mutations (
```
kubectl apply
```
,
```
kubectl delete
```
,
```
helm upgrade
```
, ...) must go through
```
okteto deploy
```
so Okteto can track resources. Read-only kubectl/helm for diagnostics is fine.
Building Docker images locally: Use
```
okteto build
```
to leverage the Okteto Build Service.
Hardcoding service names: Always read
```
okteto.yaml
```
to discover services.
Destroying without authorization: In autonomous mode, do not run
```
okteto destroy
```
unless there is an explicit cleanup policy or instruction.
Sharing one namespace across worktrees: Two worktrees deploying into the same namespace overwrite each other and a
```
destroy
```
in one wipes the other. Give each worktree its own namespace (see Worktree isolation) and pass
```
-n <ns>
```
on every command.
Using
okteto namespace use
to isolate concurrent work: It mutates the global active context and races with other worktrees/agents. Use the per-command
```
-n <ns>
```
flag instead.

在自主模式下运行
okteto up
：没有人类与shell交互。请改用
```
okteto deploy
```
+
```
okteto build
```
+
```
okteto test
```
。
在协作模式下由Agent运行
okteto up
：它是交互式的。始终告知用户自行运行。
忘记先部署：在任何验证或测试前运行
```
okteto deploy
```
。
未指定服务：有多个服务时，始终指定目标服务。
使用kubectl/helm修改集群：修改操作（
```
kubectl apply
```
、
```
kubectl delete
```
、
```
helm upgrade
```
等）必须通过
```
okteto deploy
```
进行，以便Okteto跟踪资源。用于诊断的只读kubectl/helm命令是允许的。
在本地构建Docker镜像：使用
```
okteto build
```
以利用Okteto Build Service。
硬编码服务名称：始终读取
```
okteto.yaml
```
以发现服务。
未经授权销毁环境：在自主模式下，除非有明确的清理策略或指令，否则不要运行
```
okteto destroy
```
。
多个工作树共享一个命名空间：两个工作树部署到同一命名空间会相互覆盖，其中一个的
```
destroy
```
会清除另一个的环境。为每个工作树分配自己的命名空间（参见工作树隔离），并在每个命令中传递
```
-n <ns>
```
参数。
使用
okteto namespace use
隔离并发工作：它会修改全局活动上下文，与其他工作树/Agent产生冲突。请改用每个命令的
```
-n <ns>
```
标志。

okteto

Original

Translation

Okteto Development Environment Skill

Okteto开发环境技能

Operating rules

操作规则

Step 1: Discover the project

步骤1：发现项目

Step 2: Determine your operating mode

步骤2：确定操作模式

Collaborative mode

协作模式

Environment setup

环境设置

The okteto up rule

okteto up规则

Working with the developer

与开发者协作

Debugging patterns

调试模式

Autonomous mode

自主模式

Workflow

工作流程

Autonomous example

自主模式示例

Worktree isolation

工作树隔离

One worktree = one namespace

一个工作树 = 一个命名空间

branch "feat/Rate_Limiting" -> "feat-rate-limiting"

分支"feat/Rate_Limiting" -> "feat-rate-limiting"

Create once, then pass -n on every command

创建一次，然后在每个命令中传递-n

Cleanup and teardown

清理与拆除

Pick the right command

选择正确的命令

Tearing down an isolated worktree namespace

拆除隔离工作树的命名空间

Collaborative mode

协作模式

Autonomous mode

自主模式

Never do this

绝对禁止的操作

Discovering dev commands

发现开发命令

CLI quick reference

CLI快速参考

Common mistakes to avoid

需避免的常见错误

The
`okteto up`
rule

`okteto up`
规则

Create once, then pass
`-n`
on every command

创建一次，然后在每个命令中传递
`-n`