AGENTS

Name: AGENTS
Author: okteto

4stars0forks

How to install AGENTS?

okteto/okteto-claude-plugins/agents

$curl -o .claude/agents/AGENTS.md https://raw.githubusercontent.com/okteto/okteto-claude-plugins/HEAD/agents/AGENTS.md

Installs into the current project.

Summary

This project uses Okteto for cloud development environments. When a developer asks you to make a change, test something, or interact with the running environment, use the instructions below.

Files · 1

View on GitHub

agents/AGENTS.md

1	# Okteto Development Environment
2
3	This project uses [Okteto](https://www.okteto.com) for cloud development environments. When a developer asks you to make a change, test something, or interact with the running environment, use the instructions below.
4
5	## Step 1: Discover the project
6
7	Read `okteto.yaml` in the project root. This is the source of truth for:
8
9	- build: which services have container images
10	- deploy: how services are deployed to the cluster
11	- dev: which services support development mode, their sync paths, and startup commands
12	- test: which test containers are available and their commands
13
14	Always derive service names from `okteto.yaml`. Never hardcode them.
15
16	## Step 2: Discover how to run commands for each service
17
18	Look at the `dev` section of `okteto.yaml` for each service. The `command` field tells you how the service starts inside the dev container:
19
20	- `command: bash` — the service needs manual build/start steps; check the service directory for a `Makefile`, `package.json`, `pom.xml`, or `go.mod` to find available commands
21	- `command: yarn start` or `command: mvn spring-boot:run` — the service auto-starts in dev mode; use the same runner for tests (`yarn test`, `mvn test`, etc.)
22
23	When a developer asks you to run tests or build a service and you're not sure what command to use, check these files in the service directory before guessing.
24
25	## Step 3: Running commands in the dev environment
26
27	When a developer has `okteto up <service>` running in their terminal, use `okteto exec` to run commands inside the dev container:
28
29	```
30	okteto exec -- <command>
31	```
32
33	Examples:
34	- `okteto exec -- go test ./...`
35	- `okteto exec -- npm test`
36	- `okteto exec -- make test`
37	- `okteto exec -- curl localhost:8080/health`
38
39	Do not use `kubectl exec` or try to open a shell directly into a pod. `okteto exec` is the correct way to run commands in the development container — it handles cluster authentication, namespace selection, and dev container routing automatically. Direct `kubectl exec` calls will not reach the right container and will confuse the session.
40
41	Read-only `kubectl` and `helm` are fine for diagnostics. Commands like `kubectl get pods`, `kubectl describe pod`, `kubectl logs <pod> --previous`, `kubectl get events`, and `helm status` only read cluster state and are the right tools for debugging unhealthy pods. The rule is about mutations: never change the cluster with `kubectl apply`/`edit`/`delete` or `helm install`/`upgrade` — all changes go through `okteto deploy`.
42
43	## The `okteto up` rule
44
45	`okteto up <service>` is interactive — it starts a live shell inside the dev container with automatic file sync. You must never run it yourself (not in the terminal, not in the background). It will hang waiting for input.
46
47	Instead, tell the developer:
48
49	> Run this in your terminal: `okteto up <service>`
50
51	If you are isolating a worktree, include the namespace: `okteto up <service> -n <ns>`.
52
53	Once they confirm it's running, you can use `okteto exec` freely.
54
55	## Worktrees and namespace isolation
56
57	An Okteto namespace is the unit of isolation. It comes from the active Okteto context (`~/.okteto`), which is global to the machine — not per-directory. If you work in a git worktree (or any second checkout of the same repo), you share the same `okteto.yaml` as the other worktrees, so deploying into the same namespace makes them collide: the second `okteto deploy` overwrites the first, logs/endpoints get crossed, and `okteto destroy` in one wipes the other.
58
59	Give each worktree its own namespace:
60
61	1. Detect a worktree: `git rev-parse --git-common-dir` differs from `git rev-parse --git-dir`, or check `git worktree list`.
62	2. Derive a name from the branch (lowercase alphanumeric and `-`, start/end alphanumeric, ≤ 63 chars):
63	```bash
64	ns=$(git branch --show-current \| tr '[:upper:]' '[:lower:]' \| sed 's/[^a-z0-9]/-/g; s/^-//; s/-$//' \| cut -c1-50)
65	```
66	3. Create it once: `okteto namespace create <ns>`.
67	4. Pass `-n <ns>` on every Okteto command (`deploy`, `build`, `logs`, `endpoints`, `test`, `destroy`, and `okteto up` when you hand it to the developer).
68
69	Do not use `okteto namespace use <ns>` to isolate worktrees — it switches the active namespace in the shared global context and races with other worktrees or agents on the same machine. The `-n` flag is per-invocation and safe under concurrency.
70
71	A single primary checkout (not a worktree) can use the context's default namespace — no `-n` needed.
72
73	## Common workflows
74
75	### Setting up the environment
76
77	1. Run `okteto version` to confirm the CLI is installed
78	2. Run `okteto context show` to confirm the cluster connection
79	3. Run `okteto deploy --wait` to build images and deploy all services
80	4. Run `okteto endpoints` to show the live URLs
81	5. Ask which service the developer wants to work on, then tell them to run `okteto up <service>` in their terminal
82
83	### Making a change and testing it in Okteto
84
85	1. Read the relevant source files and make the

People who liked this also viewed

6 picks

Type

AGENTS

4stars0forks

View on GitHub

How to install AGENTS?

okteto/okteto-claude-plugins/agents

$curl -o .claude/agents/AGENTS.md https://raw.githubusercontent.com/okteto/okteto-claude-plugins/HEAD/agents/AGENTS.md

Installs into the current project.

Summary

This project uses Okteto for cloud development environments. When a developer asks you to make a change, test something, or interact with the running environment, use the instructions below.

Files · 1

View on GitHub

agents/AGENTS.md

1	# Okteto Development Environment
2
3	This project uses [Okteto](https://www.okteto.com) for cloud development environments. When a developer asks you to make a change, test something, or interact with the running environment, use the instructions below.
4
5	## Step 1: Discover the project
6
7	Read `okteto.yaml` in the project root. This is the source of truth for:
8
9	- build: which services have container images
10	- deploy: how services are deployed to the cluster
11	- dev: which services support development mode, their sync paths, and startup commands
12	- test: which test containers are available and their commands
13
14	Always derive service names from `okteto.yaml`. Never hardcode them.
15
16	## Step 2: Discover how to run commands for each service
17
18	Look at the `dev` section of `okteto.yaml` for each service. The `command` field tells you how the service starts inside the dev container:
19
20	- `command: bash` — the service needs manual build/start steps; check the service directory for a `Makefile`, `package.json`, `pom.xml`, or `go.mod` to find available commands
21	- `command: yarn start` or `command: mvn spring-boot:run` — the service auto-starts in dev mode; use the same runner for tests (`yarn test`, `mvn test`, etc.)
22
23	When a developer asks you to run tests or build a service and you're not sure what command to use, check these files in the service directory before guessing.
24
25	## Step 3: Running commands in the dev environment
26
27	When a developer has `okteto up <service>` running in their terminal, use `okteto exec` to run commands inside the dev container:
28
29	```
30	okteto exec -- <command>
31	```
32
33	Examples:
34	- `okteto exec -- go test ./...`
35	- `okteto exec -- npm test`
36	- `okteto exec -- make test`
37	- `okteto exec -- curl localhost:8080/health`
38
39	Do not use `kubectl exec` or try to open a shell directly into a pod. `okteto exec` is the correct way to run commands in the development container — it handles cluster authentication, namespace selection, and dev container routing automatically. Direct `kubectl exec` calls will not reach the right container and will confuse the session.
40
41	Read-only `kubectl` and `helm` are fine for diagnostics. Commands like `kubectl get pods`, `kubectl describe pod`, `kubectl logs <pod> --previous`, `kubectl get events`, and `helm status` only read cluster state and are the right tools for debugging unhealthy pods. The rule is about mutations: never change the cluster with `kubectl apply`/`edit`/`delete` or `helm install`/`upgrade` — all changes go through `okteto deploy`.
42
43	## The `okteto up` rule
44
45	`okteto up <service>` is interactive — it starts a live shell inside the dev container with automatic file sync. You must never run it yourself (not in the terminal, not in the background). It will hang waiting for input.
46
47	Instead, tell the developer:
48
49	> Run this in your terminal: `okteto up <service>`
50
51	If you are isolating a worktree, include the namespace: `okteto up <service> -n <ns>`.
52
53	Once they confirm it's running, you can use `okteto exec` freely.
54
55	## Worktrees and namespace isolation
56
57	An Okteto namespace is the unit of isolation. It comes from the active Okteto context (`~/.okteto`), which is global to the machine — not per-directory. If you work in a git worktree (or any second checkout of the same repo), you share the same `okteto.yaml` as the other worktrees, so deploying into the same namespace makes them collide: the second `okteto deploy` overwrites the first, logs/endpoints get crossed, and `okteto destroy` in one wipes the other.
58
59	Give each worktree its own namespace:
60
61	1. Detect a worktree: `git rev-parse --git-common-dir` differs from `git rev-parse --git-dir`, or check `git worktree list`.
62	2. Derive a name from the branch (lowercase alphanumeric and `-`, start/end alphanumeric, ≤ 63 chars):
63	```bash
64	ns=$(git branch --show-current \| tr '[:upper:]' '[:lower:]' \| sed 's/[^a-z0-9]/-/g; s/^-//; s/-$//' \| cut -c1-50)
65	```
66	3. Create it once: `okteto namespace create <ns>`.
67	4. Pass `-n <ns>` on every Okteto command (`deploy`, `build`, `logs`, `endpoints`, `test`, `destroy`, and `okteto up` when you hand it to the developer).
68
69	Do not use `okteto namespace use <ns>` to isolate worktrees — it switches the active namespace in the shared global context and races with other worktrees or agents on the same machine. The `-n` flag is per-invocation and safe under concurrency.
70
71	A single primary checkout (not a worktree) can use the context's default namespace — no `-n` needed.
72
73	## Common workflows
74
75	### Setting up the environment
76
77	1. Run `okteto version` to confirm the CLI is installed
78	2. Run `okteto context show` to confirm the cluster connection
79	3. Run `okteto deploy --wait` to build images and deploy all services
80	4. Run `okteto endpoints` to show the live URLs
81	5. Ask which service the developer wants to work on, then tell them to run `okteto up <service>` in their terminal
82
83	### Making a change and testing it in Okteto
84
85	1. Read the relevant source files and make the

People who liked this also viewed

6 picks

Type