GitBasedDocs was built with Claude Code over two days and 55 commits. The rules file, one commit per task, a Markdown task board as shared state, and the places where I had to step in.
GitBasedDocs was built with Claude Code as the coding agent, over two days and 55 commits: 33 features, 14 fixes, 6 docs commits, one performance change and the README. The repo keeps a good record of how the work was split, because the agent's instructions, its task list and its notes all live in it as plain files.
The rules file
The root AGENTS.md is 32 lines. It says dashboard/ is the only app, lists the commands, and sets the verify order: lint, then typecheck, then build. There is no test runner, so bun run build is the final check.
One line matters more than the rest: before writing Next.js code, read the relevant guide in node_modules/next/dist/docs/. The app is on Next.js 16, which breaks from what a model saw in training. The dashboard's own AGENTS.md opens with "This is NOT the Next.js you know". A concrete case: Next.js 16 renamed middleware to proxy, and the app's cookie gate lives in proxy.ts, as the version 16 docs say it should.
The file also sets rules for the task board. Keep every frontmatter key on edit. Moving a card means changing status and nothing else. Refresh modified to the current UTC time. Ask me before creating more than three new card files, and delete a card only when I say so.
One task, one commit
Each card was one unit of work, and each unit ended in its own commit. When a card held several fixes, it got several commits: the second UI critique card lists five fixes, and five commits landed between 18:23 and 18:31 on September 10.
The pace was high. Between 12:01 and 13:02 on day two there are 13 commits, including the page viewer (2,619 added lines across 26 files) and user management (1,977 lines).
The card is also where the agent reports back. After a card was done, its notes say what shipped and how it was checked. The webhook card has a table of seven requests sent over HTTP to the running server, with the response to each. The card for commit info on pages ends with "After it ran, 11 of 11 pages had one."
The board as shared state
The cards are written about me in the third person: "Safi chose the top five first", "Safi asked for these on doc pages". That is the point of the board. I read what happened from the files instead of asking. The board started with 18 cards and ended with 30, and every one is marked done.
Where I stepped in
The cards record where my input came in, and most of it came from using the app.
I couldn't find the Sync now button. It lived on /admin/connection, and no reader page linked to the admin area, so the only way in was typing the URL. The fix put an Admin link in the top bar for admins and Sync now on the admin home.
Pushes to my docs repo stopped updating the app. The follow-up on the webhook card found two causes. The hook URL in GitHub pointed at the site root, which answered 200, so GitHub's delivery log showed green while nothing synced. That one was mine to fix in the repo settings. The hook's content type was also form, GitHub's default, and the route only parsed JSON. The code fix made the route accept both, still checking the signature over the raw body first.
The rest was product calls:
- I picked ink blue as the accent colour.
- The page width control shipped as a menu. I asked for one button that cycles between widths, and that commit added 25 lines and removed 81.
- Commit info on pages first linked the commit for admins and editors. Ten minutes later I narrowed repo details to admins only.
- The second design critique scored the app 27 out of 40 with five P1 issues. I chose which five to fix first. The next tier (focus outlines, a skip link, contrast misses, small tap targets) is written on the card as not started.
Fixes that corrected earlier work
14 of the 55 commits are fixes, and some of them undo a decision made minutes earlier. The research notes planned database sessions. next-auth v4 only allows email and password sign-in with JWT sessions, and the fix landed 17 minutes after the login commit. The editor role was specified to see drafts, and a later fix made the code match. One problem was caught during testing rather than in use: the cookie gate in proxy.ts redirected GitHub's webhook calls to /login, because GitHub sends no cookie.
Shortcuts marked in the code
The code has nine comments that start with ponytail:. Each marks a deliberate shortcut, and most say where it stops working. The one in the sync engine reads: "in-process lock. One app instance is the v1 deploy shape. Swap for a DB advisory lock the day this runs on more than one node." Others cover the in-memory login rate limit, the recheck timer, the webhook delivery cache and the render cache.
Those five in-process pieces are the list of what has to change before the app runs on more than one instance.
