Files
praxis/docs/01-vibe-coding.md
T
阿白叔andClaude Opus 4.7 7f9ca07903 init: scaffold team-guide v0.1
Working agreements for our 1-3 person AI-assisted team. Six docs
(vibe coding, Claude Code, git workflow, skills/planning, code style,
handoff) plus four templates (CLAUDE.md, README, PR description,
handoff checklist).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 09:02:21 +08:00

3.2 KiB

01 — Vibe coding

How humans and AI split the work on this team.

The premise

Claude Code writes most of the code. Humans steer: framing problems, making decisions, deciding what's good enough to ship. We're not racing the AI — we're using it to skip typing so we can spend more time thinking.

The split

Claude does:

  • Read code and explain it
  • Write first-pass implementations against a clear spec
  • Refactor mechanically (renames, extractions, type changes)
  • Run tests, builds, linters; iterate on errors
  • Generate boilerplate (configs, fixtures, templates, CRUD)
  • Search across the workspace and summarize findings

Humans do:

  • Decide what to build and why
  • Frame the spec before Claude touches code
  • Approve any change with non-local consequences (deps, schema, infra, auth, secrets)
  • Read every diff before merging
  • Make the call when Claude has tried twice and is going in circles
  • Write the commit message and PR description (Claude drafts; you sign off)

If a task feels like it's drifting toward "Claude decides", stop and write a short spec yourself first.

Prompt habits

  • Frame, don't dictate. Tell Claude the goal, the constraints, and what you've already ruled out. Don't prescribe steps unless the steps are the point.
  • Name the file. "Fix the bug in eval-agent/runner.py" is better than "fix the bug." Save Claude a search.
  • Say what done looks like. "Tests pass and the new flag defaults to off" — measurable. "Make it cleaner" — not.
  • One task per turn. If you have three unrelated asks, send three messages or open three sessions. Mixed contexts produce mixed results.
  • Push back on bad output. If the diff is wrong, say so plainly and point at the part that's wrong. Don't accept code you wouldn't write yourself.

When to stop and take over

Stop letting Claude drive when:

  • It's failed the same approach twice and the error is unchanged.
  • It's adding code "for safety" that the task didn't ask for.
  • The diff has grown past what you can read in one sitting.
  • You can't explain the change to a teammate without re-reading the diff.
  • It's about to do something irreversible (delete data, force-push, change auth) — confirm explicitly.

If you stop and take over, write down why in the PR description so the next person doesn't repeat the loop.

Verifying AI output

Treat every Claude diff like a PR from a fast junior:

  1. Does it build?
  2. Do the tests pass — and do new tests actually test the new code?
  3. Did it touch files outside the stated scope? Look at every one.
  4. Did it add deps? Check the lockfile diff.
  5. Read every comment Claude added. Half of them are noise — delete those.
  6. Run the feature end-to-end if it's user-facing. Type checks ≠ working software.

Anti-patterns

  • Snowballing context. Long sessions accumulate stale assumptions. Start a new session for a new task.
  • Approval-by-default. "Looks good" without reading the diff is how bugs ship. Read it.
  • Outsourcing the spec. "Figure out what we should do" is not a prompt — it's avoidance.
  • Letting AI rewrite history. If Claude wants to refactor unrelated code "while we're here", say no. Open a separate task.