kitdocs · github

Working with AI coding agents

raw markdown reference/working-with-ai.md verified 2026-09-26

Each rule below came from a real mistake, and each says what went wrong. Put the ones that apply into your project's CLAUDE.md and your agent's global instructions.

1. Verify by doing, not by looking

A read-only walk through a signed-in site missed two bugs the owner then found within minutes. "Remove" on a completed item left it on screen, and a list/grid toggle broke every card. Reading pages can't exercise actions, and it can't see "the click worked but the screen didn't change".

• Drive a headless browser as a test account, at phone width.
• After every action: compare the DOM with the API, then reload, then compare again.
• Toggle every view switch and search on each list page.
• Write the flow from the user's exact numbers ("ticked 50, opened History, came back, sets said 45") and watch it fail on the old code before fixing. See workflows/browser-flow-testing.md.

2. Evidence before "done"

No "fixed", "passing" or "deployed" without the command output that shows it. A deploy is done when the live site shows the change and the flow passed against production, not when the script exited 0. If something was skipped, say so.

3. Measure, don't guess

• "Do we need a bigger server?" is answered with load, available RAM, swap, OOM kills, disk and per-app memory, plus the thresholds that would change the answer.
• "Did the email arrive?" is answered by the provider's delivery events, not the app's "sent" log line. That line counts attempts. A push service returning 201 does not mean the device saw it.
• Check the user's own settings before debugging delivery (notifications turned off explained a whole "nothing arrives" report).

4. Don't invent requirements

Build what the owner or client actually asked for. A feature built on an assumption (a waiting list the club did not run) had to be removed. A pitch with invented features reads as not having listened. When a client gives no requirements: list the questions, don't answer them yourself. The same applies to design tools. Forbid invented testimonials, user counts, features and data in every brief.

5. State recurring costs plainly

Say every recurring cost as "$X per month, until you remove it". Server snapshots, for example, bill monthly forever: take one only before a risky change, and delete it right after. Before fanning out parallel agents or design generations, say it will use a large share of the plan's usage limit.

6. Capture repeated work as a skill

The second time the same job is done (a password reset built for two apps), turn it into a reusable skill. Keep what transfers: the decisions, the infrastructure steps and the traps. Leave out what doesn't: the code (different hashing libraries, CSS systems and test harnesses per app). This kit is that idea applied to everything.

7. Keep agents small and bounded

• One small, checkable change per ticket. Multi-hour, multi-phase work handed to an unattended agent died on usage limits and restarts.
• Write each repo's autonomy level into CLAUDE.md (PR-and-stop / branch / deploys).
• Parallel agents need their own worktree, test DB, ports and profile dirs (workflows/parallel-agents.md).
• After a deploy from main, switch back to your working branch. Committing on main by accident was caught only by a pre-push hook.

8. Once the owner hands you the terminal, drive it

When learning is the goal, go step by step. Once the owner says "take control", run the commands yourself and explain what you ran and why. Handing them things to paste after that is friction. Don't tell them to stop or rest; offer the next step.

9. Keep secrets out of transcripts

Never cat a .env or a config holding tokens. Print key names, or pipe values straight into the next command. Run provider API calls from the server that holds the key, so the key never travels. Never publish IPs, tokens or real users' data, including in docs and screenshots.

10. Honest status everywhere

Status lines on a portfolio ("a pitch, not a commission", "in progress"), in summaries, and in commit messages stay honest. Upgrading the wording to sound better costs more trust than it earns.