After months of experimenting with Claude Code and "vibe coding" a production project, here's the practical template that actually prevents Claude from nuking your app. This repo shows how to use a CLAUDE.md and modular agent prompts to reduce the risk of AI-induced disasters.
Claude has zero memory between sessions and no innate sense of danger. Left unchecked, it'll cheerfully:
- Run
rsync --deleteand wipe 11,000+ irrecoverable images (ask me how I know 🙃) - Open issues in the wrong GitHub repo
- Deploy broken code directly to production
The lesson: Treat onboarding your project assistant like onboarding a developer with amnesia who will forget everything tomorrow. This README is your map for how to do exactly that.
The repo and its CLAUDE.md include:
List EVERY forbidden command, directory, and production URL. Spell out what is truly destructive.
Example: Never run tests on production. Never use rsync --delete outside a wrapper script. Never deploy to prod unless explicitly asked!
Define your staging and production URLs, ports, and which files belong where. Claude cannot infer your infrastructure!
Example: Staging = staging.yourapp.com, Prod = app.yourapp.com, Database = PostgreSQL @ localhost:5432.
Copy-paste-ready commands to:
- Start backend/frontend
- Run and debug tests (ALWAYS against staging by default)
- Safely deploy and rollback
- Backup/restore the database
Note every quirk or trap you’ve hit:
- “Server only has python3”
- “ALWAYS activate the virtualenv or dependencies will break”
- “Node scripts need a login shell for nvm to kick in”
Every time something blows up, document what happened and how to prevent it next time.
Example: 2024-01-15 – Used rsync --delete, wiped server; PREVENTION: always use wrapper script with exclusions.
Modular agent prompt files in .claude/commands/ like:
/dev– Backend/API/DB expert/web– Frontend (React/Tailwind) expert/test– QA who only runs tests on staging/sync– Deployment agent (never touches prod without explicit approval)/manager– Orchestrator: plans and delegates, never writes code
# Start backend
cd apps/api && source venv/bin/activate && python run.py
# Start frontend
cd apps/web && npm install && npm run dev
# Run E2E tests (against staging!)
cd apps/web && npx playwright test
# Database shell
psql -U postgres -d yourdb
# Deploy safely (ask for explicit prod approval first!)
./tools/scripts/sync-to-server.sh --dry-run
./tools/scripts/deploy.shClaude reads CLAUDE.md plus your slash-command markdowns in .claude/commands/ at session start, "remembers" the rules, and only acts within your explicit constraints.
- You type
/dev fix the login endpoint - Claude loads
.claude/commands/dev.md, acts as a backend expert, and follows only the allowed patterns - It refuses to deploy to production, run forbidden commands, or do anything involving "danger zones" without your confirmation
Gotchas, lessons, and incident logs act as AI guardrails.
- Fill out CLAUDE.md: Document everything you wish a new dev (or AI) would know
- Write prompt markdowns in
.claude/commands/for each expert role needed - Update when things go wrong: Add them to the incident log
- Be explicit: The dumber and more explicit, the safer
- See CLAUDE.md for the full live template (ready to drop into your own repo)
- Example expert-agent prompts in
.claude/commands/ - Detailed docs in
docs/(if you want to go deeper)
- AI is not magic—define your danger zones or it WILL break things.
- All context and rules must be in plain text in your repo, every session.
- Use custom slash commands in
.claude/commands/to set AI “expert mode.” - Treat CLAUDE.md like onboarding a forgetful junior programmer.
- Add to the incident log every time anything goes sideways.
- Never EVER trust a default deployment/test command to "just work."
Questions? Want to share your own best practices or horror stories? [Link to template in comments/repo].