Repository navigation
docs: require the README to keep up with what ships - #53
Merged
Merged
Conversation
The README is now a product page carrying screenshots of the running application, which gives it a way to go quietly wrong that a build note never had. A screenshot ages with every layout change, not only with the feature it illustrates, and nothing in the test suite or the linter can notice. The rule binds the obligation to the change rather than to a checklist: a user-visible feature is not finished until the README shows it, and a minor release checks the README and the screenshots before the version bump. A patch needs no pass. Release notes remain the place for what is new in a version, so the README can describe the application as it is now and carry no version history. Screenshots are generated rather than collected, and the rule says so, because that is what makes the obligation cheap enough to honour. It also draws a line the capture script already respects: the script drives seams that exist, and widening an application API to make a screenshot easier changes the product for the benefit of a developer tool. The closing paragraph records why this earned a rule. Rendering the interface for #43 exposed six German strings in an English UI, a number format following the system locale instead of the interface language, and the absence of any application-level settings surface. None of them had been caught by a test, a linter or a reading review. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a
Keeping the README honestsection toCLAUDE.md. No code changes.Now that #51 has landed, the README is a product page with screenshots of the
running application — which gives it a way to go quietly wrong that a build note
never had. A screenshot ages with every layout change, not only with the feature
it illustrates, and no test or linter can notice.
The rule binds the obligation to the change rather than to a checklist:
a patch does not;
scripts/screenshots.py, never pasted by hand —and that script drives seams that already exist, because widening an
application API to make a screenshot easier changes the product for the
benefit of a developer tool;
application as it is now and carries no version history.
The section closes by recording why this earned a rule at all: rendering the
interface for #43 exposed six German strings in an English UI (#47), a number
format following the system locale rather than the interface language (#49), and
the absence of any application-level settings surface (#50). None of them had
been caught by a test, a linter or a reading review.
Deliberately written after #51 rather than before it, so the rule points at a
script that exists. A rule naming machinery that has not been built yet is worse
than no rule.
Test plan
scripts/screenshots.pyexists onmainas of docs: make the README a product page, with generated screenshots #51.🤖 Generated with Claude Code