chore(claude): add dev container skills for Claude Code by hvn2k1 · Pull Request #2741 · bucketeer-io/bucketeer

hvn2k1 · 2026-07-31T04:37:40Z

What this PR does

Adds three Claude Code project skills — devcontainer-run, devcontainer-generate, devcontainer-deploy — that let Claude detect the running Bucketeer dev container (local devcontainer or GitHub Codespace) and run development actions inside it, and updates .claude/CLAUDE.md to prefer the dev container + minikube flow for those actions.

Background / Why this PR is needed

Codegen and deploys are environment-sensitive: generated files must be produced with exactly protoc v23.4, minikube must be started via make start-minikube, and the *.bucketeer.io hosts entries only resolve inside the container. When Claude (or a human) runs these on the host, a protoc version mismatch silently churns every generated .pb.go file, and bare kubectl/helm can hit the wrong cluster — the host kubectl context may point at a real GKE cluster instead of minikube. These skills route all such actions through the dev container, where the toolchain is guaranteed.

Points

devcontainer-run/scripts/exec.sh detection order: already inside the container → local devcontainer (docker label devcontainer.local_folder) → GitHub Codespace (gh codespace ssh). When nothing is found it exits 2 with instructions to start one — deliberately no silent fallback to the host.
Ambiguity is never resolved by guessing: the local-devcontainer match is an exact devcontainer.local_folder label match against the repo root, and if several Bucketeer Codespaces are available the script exits 2 with the list and asks for BUCKETEER_CODESPACE=<name> rather than taking the first.
Every cluster command names its context explicitly (kubectl --context minikube, helm --kube-context minikube) and status warns when the active context is not minikube, so a stray kubectl config use-context cannot silently redirect a deploy at a real cluster.
The status health line counts only genuinely failing pods (CrashLoopBackOff, ImagePull errors, OOMKilled, Evicted) rather than a raw ready count, because batch CronJobs constantly spawn short-lived pods and make a ready count flap.
Codespace mode is flagged as a separate clone (generated files need gh codespace cp or a push to get back to the host); a local devcontainer is a bind mount, so no sync is needed. Verification steps therefore run through $DEVC too, so they inspect the clone where generation actually happened.
Verified against a live devcontainer: make proto-all run through the skill reproduced the committed generated files byte-for-byte (zero diff), and the single-service rollout commands were validated against the running minikube cluster.
Docker Compose stays documented in CLAUDE.md as the host-based alternative; build/test/lint commands are unchanged.

Add three project skills that route development actions through the Bucketeer dev container, where the toolchain is guaranteed: - devc: detect the running dev container (local devcontainer or GitHub Codespace) and run any command inside it via scripts/devc-exec.sh - devc-generate: proto/mock generation inside the container (protoc v23.4 guaranteed; host version mismatch churns every generated file) - devc-deploy: minikube deploys inside the container, incl. the faster single-service rollout path Also update .claude/CLAUDE.md to prefer the dev container + minikube flow for these actions, with Docker Compose as the host-based alternative. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Copilot

Pull request overview

This PR adds Claude Code project skills to standardize Bucketeer dev workflows through the devcontainer (and its minikube cluster), reducing host-environment drift for codegen, builds, and deploys.

Changes:

Add three Claude skills (devc, devc-generate, devc-deploy) documenting the recommended devcontainer-based workflows.
Introduce a devc-exec.sh wrapper script to detect a running devcontainer/Codespace and execute commands inside it.
Update .claude/CLAUDE.md to prefer the devcontainer + minikube flow for environment-sensitive tasks.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
.claude/skills/devc/SKILL.md	Documents the devcontainer as the canonical environment and how to route commands through the wrapper script.
.claude/skills/devc/scripts/devc-exec.sh	Adds container/Codespace detection and a status/exec command runner for devcontainer workflows.
.claude/skills/devc-generate/SKILL.md	Documents proto/mock generation via the devcontainer to ensure protoc version consistency.
.claude/skills/devc-deploy/SKILL.md	Documents deploy/redeploy workflows targeting minikube inside the devcontainer.
.claude/CLAUDE.md	Updates contributor guidance to prefer the devcontainer + minikube workflow for environment-sensitive actions.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Address review comments on PR #2741: - Guard kubectl get pods in the status report; print a clear message when kubectl fails while minikube is up instead of a misleading 0-pod count - Derive the repo root from the script location for an exact devcontainer.local_folder label match from any cwd; drop the fuzzy fallback that could pick the wrong container when multiple checkouts are running Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

manifests/datadog-agent.yaml was accidentally included in the previous commit; it is local work unrelated to this PR. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…ence Address review comments on PR #2741: - Rename skills for clarity: devc -> devcontainer-run, devc-generate -> devcontainer-generate, devc-deploy -> devcontainer-deploy; the wrapper script is now .claude/skills/devcontainer-run/scripts/exec.sh - Move human-facing environment knowledge into DEVELOPMENT.md (working with the dev container from the host, start-minikube exit-1 note, single-service redeploy flow) and cross-reference it from the skills, which keep only the Claude-oriented operational detail Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

DEVELOPMENT.md:99

The newly added single-service workflow now follows an existing instruction to install manifests/bucketeer/charts/backend, but that chart does not exist; the actual charts/deployments are the four listed here. Remove the obsolete block so readers are not given two conflicting workflows, one of which always fails.

For faster iteration on a single service after a Go code change, rebuild and load the images, then restart only that deployment (`api`, `web`, `batch-server`, or `subscriber`):

.claude/skills/devcontainer-deploy/SKILL.md:51

This description is incomplete: POSTGRES_ENABLED is true when either dataWarehouse or operationalDatabase is postgres, while only BigQuery is derived solely from dataWarehouse (Makefile:7-11). Document both inputs so troubleshooting guidance matches what the deploy target actually enables.

and monitor. Postgres/BigQuery enablement is auto-detected from
`dataWarehouse` in `values.dev.yaml` — don't set it manually, but remember the

Address review comments on PR #2741: - Name the kube context explicitly in every cluster command (kubectl --context minikube, helm --kube-context minikube) and warn in `status` when the active context is not minikube, so a stray `kubectl config use-context` cannot redirect a deploy at a real cluster. - Route the chart-level `helm upgrade` through $DEVC like every other deploy command instead of leaving it to run on the host. - Run the protoc-header spot-check through $DEVC: in codespace mode a bare grep reads the host clone and can falsely validate a stale file. - Refuse to guess between multiple available Bucketeer codespaces; exit 2 with the list and honour an explicit BUCKETEER_CODESPACE override.

Copilot

🟡 Changes recommended

Some documented commands can target the wrong Kubernetes cluster, and the execution wrapper mishandles multi-argument commands.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (3)

Previously missed (2) — in code that hasn't changed since the last review.

.claude/skills/devcontainer-run/scripts/exec.sh:149

Joining arguments with $* discards argument boundaries before the command reaches bash -c; for example, exec.sh git commit -m "two words" is reconstructed as git commit -m two words. Since the script advertises <command ...>, preserve multi-argument invocations while retaining the single-string form used for compound shell commands.
.claude/CLAUDE.md:106
make deploy-bucketeer begins with a bare helm uninstall bucketeer in delete-bucketeer-from-minikube; merely running inside the container does not make that safe when its active context was changed. Pin the context before this example invokes the target.

.claude/skills/devcontainer-run/SKILL.md:50

Exit code 2 is not unique to detection failures: run_inside deliberately passes through the invoked command's status, and many commands also return 2. Treating every 2 as “no container/ambiguity” can make the agent report the wrong remediation after a command actually ran; document that the diagnostic output must be used to distinguish these cases (or reserve a non-forwarded status).

Exit code 2 means no container was found (or the codespace was ambiguous); the
script prints how to start one.

Files reviewed: 6/6 changed files
Comments generated: 4
Review effort level: Balanced

+  # the wrong container when multiple checkouts are running.
+  local repo_root
+  repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)"
+  CID="$(docker ps -q --filter "label=devcontainer.local_folder=$repo_root" 2>/dev/null | head -1 || true)"


+## 2. Full deploy
+
+```bash
+$DEVC 'make deploy-bucketeer'


+
+# Run any command in /workspaces/bucketeer inside the container
+bash .claude/skills/devcontainer-run/scripts/exec.sh 'make build-api'
+bash .claude/skills/devcontainer-run/scripts/exec.sh 'kubectl get pods'


+make build-go-embed
+TAG=localenv make build-docker-images
+TAG=localenv make minikube-load-images
+kubectl rollout restart deployment web && kubectl rollout status deployment web


t-kikuc

let's truy

Copilot AI review requested due to automatic review settings July 31, 2026 04:37

Copilot started reviewing on behalf of hvn2k1 July 31, 2026 04:38 View session

Copilot AI reviewed Jul 31, 2026

View reviewed changes

Comment thread .claude/skills/devc/scripts/devc-exec.sh Outdated

Comment thread .claude/skills/devc/scripts/devc-exec.sh Outdated

hvn2k1 and others added 2 commits July 31, 2026 13:44

chore: remove unrelated datadog-agent manifest from this branch

9cb9185

manifests/datadog-agent.yaml was accidentally included in the previous commit; it is local work unrelated to this PR. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

hvn2k1 marked this pull request as ready for review July 31, 2026 04:57

hvn2k1 requested review from cre8ivejp and t-kikuc as code owners July 31, 2026 04:57

t-kikuc reviewed Aug 3, 2026

View reviewed changes

Comment thread .claude/skills/devcontainer-run/SKILL.md

Comment thread .claude/skills/devcontainer-generate/SKILL.md

Comment thread .claude/skills/devcontainer-run/SKILL.md

hvn2k1 requested a review from t-kikuc August 3, 2026 08:26

t-kikuc reviewed Aug 10, 2026

View reviewed changes

Comment thread .claude/skills/devcontainer-deploy/SKILL.md Outdated

Update SKILL.md

a6ce77a

hvn2k1 requested a review from t-kikuc August 26, 2026 08:43

t-kikuc requested a balanced review from Copilot August 28, 2026 07:24

Copilot started reviewing on behalf of t-kikuc August 28, 2026 07:25 View session

Copilot AI reviewed Aug 28, 2026

View reviewed changes

hvn2k1 requested a balanced review from Copilot September 2, 2026 09:51

Copilot started reviewing on behalf of hvn2k1 September 2, 2026 09:51 View session

Copilot AI reviewed Sep 2, 2026

View reviewed changes

t-kikuc approved these changes Sep 2, 2026

View reviewed changes

t-kikuc merged commit 27df25a into main Sep 2, 2026
13 checks passed

t-kikuc deleted the chore/add-devc-claude-skills branch September 2, 2026 13:09

bucketeer-release-bot Bot mentioned this pull request Sep 2, 2026

chore(main): release 2.4.0 #2748

Draft

Navigation Menu

Uh oh!

chore(claude): add dev container skills for Claude Code - #2741

chore(claude): add dev container skills for Claude Code#2741
t-kikuc merged 6 commits into
mainfrom
chore/add-devc-claude-skills

hvn2k1 commented Jul 31, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

t-kikuc left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

hvn2k1 commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does

Background / Why this PR is needed

Points

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Suppressed comments (3)

Uh oh!

t-kikuc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

hvn2k1 commented Jul 31, 2026 •

edited

Loading