Deploy Anti-Patterns

About

The critical guardrail skill that prevents AI agents from using kubectl, helm, or docker commands directly for deployments. Includes a comprehensive anti-pattern table, explains when direct kubectl IS acceptable (read-only debugging only), and lists all the common mistakes that fumble deployments.

Skill Content

This is the raw markdown that gets installed as a Claude Code rule.

# Deploy Anti-Patterns

## What this skill covers
What you must NEVER do when deploying on Tawa, and the correct alternatives.

## CRITICAL: Use tawa CLI for All Deployments

NEVER use kubectl, helm, or docker commands directly for deployments. The tawa CLI and iec-builder handle the complete deployment flow.

## Anti-Patterns

| WRONG | RIGHT | Why |
|-------|-------|-----|
| `docker build && docker push` | `tawa deploy` | Builder auto-generates Dockerfile, handles registry auth |
| `helm upgrade my-svc ./helm` | `tawa deploy --prod` | Builder injects env vars, secrets, OAuth, DNS |
| `kubectl apply -f deployment.yaml` | `tawa deploy` | Builder handles namespace, secrets, ingress |
| `kubectl rollout restart` | `tawa deploy` | Redeploy with latest code and config |
| `kubectl create secret` | Declare in catalog-info.yaml | Builder provisions secrets automatically |
| `kubectl set env` | `tawa config set KEY=VALUE` | Config management via CLI |
| Hardcoding `MONGODB_URI` in .env | Declare `databases: [{type: mongodb}]` in catalog | Builder provisions connection string |
| Manual DNS records in Cloudflare | `tawa domain add` or auto via deploy | Builder manages DNS |
| Running `helm template` to debug | `tawa troubleshoot` | AI-powered diagnostics |

## When Direct kubectl IS Acceptable

Only for read-only debugging and observability:

```bash
# These are OK:
kubectl get pods -n my-svc-prod          # Check pod status
kubectl logs -n my-svc-prod <pod>        # View application logs
kubectl describe pod -n my-svc-prod <pod> # Inspect resources
kubectl port-forward -n my-svc-prod <pod> 3000:3000  # Local debugging
kubectl top pods -n my-svc-prod          # Resource usage

# These are NOT OK:
kubectl apply ...     # Use tawa deploy
kubectl delete ...    # Use tawa deploy (redeploy)
kubectl edit ...      # Use tawa config
kubectl scale ...     # Change pod-tier in catalog-info.yaml
```

## Other Anti-Patterns

- **Hardcoding secrets in code** — Use `process.env.BIO_CLIENT_ID`, the builder injects them
- **Creating OAuth clients manually** — The builder auto-provisions via Bio-ID
- **Writing custom Helm charts** — The builder generates Helm values; custom charts are only for advanced cases
- **SSH into nodes** — Never SSH into cluster nodes; use `kubectl logs` for debugging
- **Editing K8s resources directly** — All changes should go through `tawa deploy` to stay in sync

## Key Rule
If you are typing `kubectl`, `helm`, or `docker` followed by a write command, STOP. Use `tawa deploy` instead. The only exception is read-only debugging commands.

Install

Copy the skill content and save it to:

~/.claude/rules/deploy-anti-patterns.md

Details

Format

Rule

Category

deploy

Version

1.0.0

Tokens

~800

Updated

2026-02-13