From 66cdc11dfb249596708d3bf3d4a88105af89fa01 Mon Sep 17 00:00:00 2001 From: Jakob Heuser Date: Wed, 26 Aug 2026 12:21:10 -0700 Subject: [PATCH] docs: raise the per-PR diff target to ~1200 hand-written lines The ~300-line target did not fit the normal shape of a change here: an OpenSpec proposal, design, spec deltas and tasks, plus the implementation and its tests. Since the guidance elsewhere forbids splitting tests from the code they cover, a number that only fits the code half pushed people to cut along a seam the rest of the file tells them not to. Generated files no longer count. PR #182 was 515 lines of which 346 was pnpm-lock.yaml and a regenerated schema, none of which a reviewer reads. Fixes #191 --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 55ee4838..5c5b0771 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -103,7 +103,7 @@ The proposal states which of these the change is, and why. Decide it while writi | **Stacked, merging forward** | Each unit is independently safe in production. | Each PR merges to `main` in turn; the last one archives the change. | | **Stacked, merging down** | The units are only correct together, and an intermediate state would ship a broken or half-migrated product. | Merge each PR **down** into its parent from the tip, then one protected merge of the bottom branch to `main`. The change reaches `main` atomically. | -**Prefer stacking, and aim to keep an individual diff under ~300 lines.** A 900-line PR does not get reviewed, it gets approved. Tests count toward the total but never split from the code they cover. If a unit is oversized because of its tests, that is usually a sign the unit itself should be smaller. +**Prefer stacking, and aim to keep an individual diff under ~1200 lines of hand-written change.** A PR far past that does not get reviewed, it gets approved. Generated files (lockfiles, regenerated schemas, vendored artifacts) do not count toward the total, since a reviewer does not read them. Tests and OpenSpec artifacts do count, but never split from the change they describe. The number is set so that a task change, its implementation, and its tests fit together comfortably, rather than forcing a split along the seam the rest of this guidance tells you not to cut. A diff well past this is not automatically wrong, but it should come with a reason. The deciding question between forward and down is only this: **can each unit reach production on its own without breaking anything?** If landing unit 1 alone would leave `check` broken, tests failing, or a migration half-applied, the answer is no and the stack merges down. Do not assume forward because it is tidier. Verify it, since "each unit is safe" is a claim about behavior, not intent.