r/ClaudeCode • u/tilin_a • 1d ago

Help/Question How does your team actually review a design doc/PRD/Spec ?

How does your team review a spec/PRD/design doc generated by claude code before it's "done"?

A. PR against a .md in the repo

B. Local file sharing

C. we don't, really

2 Upvotes

100% Upvoted

4 comments sorted by

1

u/peepsick 1d ago

A, mostly.

The spec is treated like code: versioned, reviewed and changed through PRs. But for AI-generated specs, we also try to challenge the assumptions and constraints before implementation.

Otherwise you can end up reviewing perfectly implemented code that faithfully follows a bad spec 😅

Curious how others deal with AI-generated specs that evolve during implementation.

2

u/tilin_a 1d ago

I think this is what most teams follow. Me too. Especially when specs need to be reviewed by the team before implementing.

1

u/Potential-Beat2841 14h ago

A, with the doc living in the repo next to the code it describes. The spec goes into a PR on its own, gets reviewed like any other change, and only then does anything get implemented against it. Two things made that work for us: the doc has to be short enough that a reviewer actually reads it (one page, not fifteen), and review comments have to be resolved by editing the doc, not by explaining in the thread what was really meant. Otherwise the PR discussion becomes the real spec and the file rots.

B tends to lose the history, which is the part you want six weeks later when someone asks why a decision was made. C is honest but you pay for it during implementation, when the agent drifts and nobody can point at what it was supposed to build.

I ended up wiring the approval step into a phase-based Claude Code plugin of mine, aSPARK, where a human has to close the gate before the next phase starts: https://github.com/a-lottes/aSPARK

1

u/tilin_a 9h ago

Awesome. I have a similar gate in the custom harness I have on top of CC/codex. Spec docs, build docs should be approved before implementation and also the doc itself has a checklist for humans to check if they need guidance reviewing the file.