From git init to first paying user.

The day-zero ritual.

Six commits you make once. Get them right and the rest of the week flows. Get them wrong and you fight your own setup forever.

CLAUDE.md, written right.

The single most important file in your repo for working with Claude Code. Write it with the discipline of a hiring manager writing a job description.

Copy# CLAUDE.md

## What this repo is
A SaaS that does X for Y customers. Built in [stack]. Production at [domain].

## How to run
- Setup: make setup
- Run: make run
- Test: make test (pytest with coverage gate at 80%)
- Lint: make lint (ruff + mypy)

## Conventions (the ones I actually want enforced)
- Use sqlalchemy 2.0 style. Never db.query() — always db.execute(select()).
- All routes go through app/routes/. No new top-level routers.
- Tests in tests/. Mirror the source tree.
- Type hints required on every function signature.

## Do NOT
- Use type-ignore casually.
- Add a JavaScript framework. We're on vanilla.
- Mock the database in tests. Use the test container.
- Write docstrings longer than 3 lines.

## Security guardrails
- Never log a token, password, or PII.
- All user input is parameterized in SQL.
- All external API calls use the configured retry harness.
- Claude must not run git push or npm publish autonomously.

Dependencies & conventions.

Pick a small, opinionated stack. Pin everything. Let Claude know what you’ve picked.

GitHub MCP server.

The official GitHub MCP server gives Claude Code direct access to issues, PRs, code search, and CI status — without you copy-pasting.

Copy# .mcp.json at repo root or ~/.claude/.mcp.json
# Option A — local Docker (recommended for self-hosted setups)

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_PAT}"
      }
    }
  }
}

# Option B — remote (OAuth, no Docker needed)
# {
#   "mcpServers": {
#     "github": {
#       "url": "https://api.githubcopilot.com/mcp/"
#     }
#   }
# }

# Claude can now: list issues, read PR diffs, search code across repos,
# check CI runs, comment on issues.
# Note: the older `npx @modelcontextprotocol/server-github` package was
# deprecated in April 2025 — use the official Docker image or remote URL.

The feature-dev loop.

The shape of every feature you ship. Six steps. Don’t skip any.

Real prompts for real features.

The four prompts that earn their keep on every feature.

1. Plan mode kickoff

Copy[plan mode]
Read the issue at .claude/issues/{n}.md.
Read the relevant code under app/services/.
Read CLAUDE.md.

Produce a plan with:
- Files to modify (list with one-line reason each)
- Files to create
- Tests to add
- Migration changes (if any)
- Open questions you'd want me to answer

Do not touch any files yet.

2. Implement after plan approval

CopyImplement the plan we just agreed on.

Rules:
- Write the failing test first, then the code that makes it pass.
- Commit after each step.
- After the last step, run `make test && make lint` and fix issues.
- Do not push. Do not open the PR.

3. Critique your own diff

CopyReview the diff for this branch as a hostile reviewer.
Push back hard on:
- Tests that don't actually exercise the new logic
- Functions over 40 lines
- Magic numbers / strings
- Missing error handling at boundaries
- Anything that violates CLAUDE.md

Quote specific lines. Don't be polite.

4. PR description

CopyWrite the PR description for this branch.

Sections:
- One-line summary
- Why (link the issue)
- What changed (bulleted, code-level)
- How to test
- Risks I should think about

No emoji. Write as if I'll read it on the train.

The guardrails layer.

Six rules a SaaS-shipping Claude session should never violate. Encode them as hooks; trust them.

• No git push without explicit approval. A PreToolUse hook on git push requires the magic word.
• No rm -rf outside the repo root. Pattern-match on Bash; reject anything that escapes.
• No secrets in commits. Pre-commit hook scans for high-entropy strings.
• No new top-level dependencies. See check-package.sh from Practice 02.
• Tests must pass before commit. A pre-commit runs make test; aborts on failure.
• No type-ignore without a comment. Lint catches it.

Pre-commit hooks.

The line of defense between “Claude wrote good code” and “the commit on main is good code.” Run on every commit, no exceptions.

Copy# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.7.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.13.0
    hooks:
      - id: mypy
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.20.0
    hooks:
      - id: gitleaks      # blocks secrets in commits

  - repo: local
    hooks:
      - id: pytest-fast
        name: pytest (fast subset)
        entry: pytest -m 'not slow' -q
        language: system
        pass_filenames: false
        stages: [commit]

Setting up testing.

Three layers. Each catches a different class of bug. Skip any one and the bugs come at the wrong time.

The PR review pipeline.

Six specialized reviewers run in parallel against every PR. Each looks for one class of bug. The orchestrator aggregates.

The security review agent.

The reviewer that pays for itself the first time it catches an injection. Run it on every PR; run it again before every deploy.

Copy---
name: security-review
description: Review the diff for security issues. Run before every merge.
tools: [Bash, Read, Grep]
---

You are a senior application-security engineer reviewing a pull request
for a SaaS service. Check for:

1. SQL injection — raw SQL with f-strings or string concatenation
2. Command injection — subprocess calls with user input
3. Path traversal — user input in file paths without normalization
4. Secret exposure — tokens / passwords / keys logged or in errors
5. Auth gaps — endpoints without auth, or auth checked AFTER work
6. SSRF — user-supplied URLs fetched without validation
7. Unsafe deserialization (use only safe loaders)
8. CORS gaps — wildcards in production
9. Dependency vulnerabilities — recent CVEs in pinned versions
10. Logging hygiene — PII or secrets in log lines

For each finding:
- Severity: BLOCKER / HIGH / MEDIUM / LOW
- File:line
- Quote the problem line
- Suggested fix

No preamble. Just the table.

/ultrareview workflow.

One slash command dispatches the six reviewers in parallel against the current diff. Returns a ranked report. Use before every merge.

Deploy pipeline.

Three environments. Two gates. One easy rollback. Boring on purpose.

Copy# main branch → preview env → staging → production
#                  (auto)      (manual)   (manual after staging soak)

# CI gates (must pass before each promotion):
#   1. pytest + mypy + ruff (all tests pass)
#   2. /ultrareview (no BLOCKER or HIGH security findings)
#   3. integration tests against staging DB
#   4. Playwright e2e against preview URL

# Rollback: git revert + redeploy. 90 seconds.

Secrets & auth.

Get this right once on day three and forget it. Get it wrong and you’ll find a token in a public repo on day forty.

• Secrets live in the platform’s secret manager. Render/Fly/Vercel environment variables, not .env files committed.
• .env is gitignored. .env.example is committed with placeholder values.
• Gitleaks runs in pre-commit AND in CI. Two layers; the second catches your team.
• Rotate tokens quarterly. Especially the GitHub PAT used by the MCP server.
• Use a managed auth service. Clerk, Auth.js, Stytch. Do not write password hashing yourself.

Observability from day one.

Adding observability after the first incident is twice as much work as adding it before. Three things on day one.

1. Structured logging. Every log line is JSON with level, request_id, user_id, route. Use structlog (Python) or pino (Node).
2. Error tracking. Sentry or equivalent. Hooked into your framework’s exception handler.
3. One dashboard. Requests/sec, p50/p90 latency, error rate, cost per day. Practice 14 covers the agent-specific stack on top.

The post-launch loop.

Shipping is the start, not the end. The five Friday-afternoon rituals that keep a SaaS healthy.

1. Read the dashboard. 15 minutes. Note what changed and why.
2. Read three random support threads. User language is the real spec.
3. Run /ultrareview against main. Surface what slipped in during the week.
4. Update CLAUDE.md. Every correction you made twice this week belongs in the file.
5. Write one paragraph to your team. What shipped, what’s next, what you learned.