AI Development Protocol — Pre-PR Checklist

For all engineers at CMMD building with AI agents (Cursor, Claude, Codex). Not about slowing down — about keeping velocity high without accumulating hidden debt.

For all engineers at CMMD building with AI agents (Cursor, Claude, Codex, or any other tool). Not about slowing down — about keeping velocity high without accumulating hidden debt.

The 6-question gate

Run before every PR — whether you wrote the code, paired with AI, or had an agent build the feature end-to-end.

1. Does it work?

Run the app, navigate to the feature, use it the way a real user would. Screenshots before and after for every UI change. npm run dev + manual verification is non-negotiable. Build passing ≠ feature working.

2. Does it have tests?

Every PR must include test coverage. Zero-test PRs do not merge.

API endpoints and business logic → TDD: write a failing test first, implement, refactor
Background services, jobs, AI pipelines → integration tests against observable outcomes. Mock external providers (LLM, Stripe, email), not the DB.
Pure functions and utilities → TDD always, no exceptions

3. Is it up to date with main?

Before pushing:

git fetch origin main
git merge origin/main

A branch behind main will fail CI, miss recent fixes, and create unnecessary merge commits. This is the most common oversight in long-running AI agent sessions — the agent starts from a stale branch and neither party notices until CI fails.

4. Does it pass the gates?

npm test               # unit tests pass
npm run check:client   # TypeScript — zero errors
npm run check:smart    # server TypeScript — zero errors
npm run lint           # ESLint — zero warnings

If pre-push fails, fix it. Do NOT skip with --no-verify unless explicitly discussed with the team first.

5. Does it follow our standards?

Review your changes against Standards. At minimum:

Every DB query is org-scoped (organizationId present)
Every log.error() includes stack: — ESLint enforces, but verify
No any types — use unknown with type guards
No console.error — use log from server/lib/logger
Design tokens only — no hardcoded Tailwind gray/neutral/slate/zinc
New page uses WorkspacePage / StandardPage / ControlPage wrapper

6. Should the standards change?

If your good work conflicts with a rule, that’s a signal, not a blocker. Surface the tension in the PR description under “Standards Discussion.” Rules encode lessons from past mistakes — but they should evolve as we learn. Propose the update alongside your code. Don’t silently comply with a rule that makes the codebase worse.

Working with AI agents

What AI is good at

Mechanical refactoring across many files
Boilerplate (routes, repos, types)
Catching established patterns and replicating them
Fast codebase exploration

What requires your judgment

Architecture decisions — the AI will build whatever you tell it. If you don’t question the approach, you get a plausible-sounding but potentially wrong one.
Prompt design for LLM-facing features — this is product design, not engineering
Whether a rule should change vs. code should change — you make the call
“Does this feel right?” — UX quality cannot be automated

The vibecoding trap

AI tools make it easy to generate a lot of code fast. The risk is not bad code — it’s code that looks right, passes lints, and has a subtle assumption baked in nobody questioned because velocity felt productive.

Slow down at these moments:

AI generated >3 new files in one PR → read each one
You can’t explain what a function does without reading the implementation
AI “fixes” something by adding complexity instead of removing it
Test passes but you’re not sure what it’s verifying
PR is long, every file “makes sense” individually, but you haven’t checked composition
Agent has been running long without check-ins — context drift accumulates

The rule: at any point during an AI session, you should be able to explain what changed and why. If you can’t, pause and read the diff before continuing.

Evolving our standards

CLAUDE.md, AGENTS.md, and .claude/rules/ are living documents. They encode lessons from real incidents — the data-access repository rule exists because AI-generated inline queries caused 6 production DB failures. The logging stack rule exists because a production bug took hours to diagnose without stack traces.

When to propose a rule change

Rule forces boilerplate with no reuse benefit
Rule written for one context (routes) being applied to another (background jobs) where risk profile is different
Rule prevents a clearly better pattern from emerging
Same tension between good work and a rule keeps surfacing across PRs

How to propose it

Add a “Standards Discussion” section to your PR description
State: what the rule says, what the conflict is, what you propose (fix code, update rule, or scoped exception)
Tag the team — rule changes are team decisions
If approved, update CLAUDE.md in the same PR as the feature

Quick reference

Situation	Action
Branch behind main	`git fetch && git merge origin/main`
AI-generated code, unsure	Read the diff. Explain every file.
Pre-push hook fails	Fix it. Don’t skip.
PR has zero new test files	Add tests before requesting review
Good code conflicts with rule	Surface in PR — propose rule update
Agent ran long	Check in. Re-read the goal. Verify approach.
Rule feels wrong	Say so. Rules evolve.