common/claude/CLAUDE.md

  1# CLAUDE.md
  2
  3## 0. TOP RULE (overrides everything)
  4
  5**Never include attribution to Claude or mention Claude/LLMs/AI in any instance,
  6ever.** This includes git commit trailers (no `Co-Authored-By: Claude`), PR
  7bodies, code comments, and any other output.
  8
  9Behavioral guidelines to reduce common LLM coding mistakes. Merge with
 10project-specific instructions as needed.
 11
 12**Tradeoff:** These guidelines bias toward caution over speed. For trivial
 13tasks, use judgment.
 14
 15## Avoid verbose and buzzword-laden commentary
 16
 17Write text (code comments, documentation, website copy, conversations with me,
 18etc.) in plain, direct English, as a competent engineer explaining it to a
 19colleague. Remove dramatic framing, suspense-building, hype, and buzzy metaphors
 20(e.g. 'load-bearing assumption', 'here's the kicker', 'the most instructive
 21part', 'this changes everything'). Plain sentences, no reveals. Keep every
 22technical fact, number, file path, command, and code block exactly intact — only
 23the style changes, not the substance, and do not shorten beyond what removing
 24fluff removes. Output only the rewritten text with no preamble or commentary.
 25
 26Pull requests and commit messages should be succinct and deliver the facts of
 27the changes immediately without unnecessary commentary. Do not provide
 28before/after commentary within a repository's comments or files - that's what
 29the git history is for. Write every comment, doc, and PR with the assumption
 30that the reader is already knowledgeable and does not need their hand held -
 31only the facts and only the bare minimum required.
 32
 33## Think Before Coding
 34
 35**Don't assume. Don't hide confusion. Surface tradeoffs.**
 36
 37Before implementing:
 38- State your assumptions explicitly. If uncertain, ask.
 39- If multiple interpretations exist, present them - don't pick silently.
 40- If a simpler approach exists, say so. Push back when warranted.
 41- If something is unclear, stop. Name what's confusing. Ask.
 42
 43## Simplicity First
 44
 45**Minimum code that solves the problem. Nothing speculative.**
 46
 47- No features beyond what was asked.
 48- No abstractions for single-use code.
 49- No "flexibility" or "configurability" that wasn't requested.
 50- No error handling for impossible scenarios.
 51- If you write 200 lines and it could be 50, rewrite it.
 52
 53Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes,
 54simplify.
 55
 56## Surgical Changes
 57
 58**Touch only what you must. Clean up only your own mess.**
 59
 60When editing existing code:
 61- Don't "improve" adjacent code, comments, or formatting.
 62- Don't refactor things that aren't broken.
 63- Match existing style, even if you'd do it differently.
 64- If you notice unrelated dead code, mention it - don't delete it.
 65
 66When your changes create orphans:
 67- Remove imports/variables/functions that YOUR changes made unused.
 68- Don't remove pre-existing dead code unless asked.
 69
 70The test: Every changed line should tracedirectly to the user's request.
 71
 72## Goal-Driven Execution
 73
 74**Define success criteria. Loop until verified.**
 75
 76Transform tasks into verifiable goals:
 77- "Add validation" → "Write tests for invalid inputs, then make them pass"
 78- "Fix the bug" → "Write a test that reproduces it, then make it pass"
 79- "Refactor X" → "Ensure tests pass before and after"
 80
 81For multi-step tasks, state a brief plan:
 82```
 831. [Step] → verify: [check]
 842. [Step] → verify: [check]
 853. [Step] → verify: [check]
 86```
 87
 88Strong success criteria let you loop independently. Weak criteria ("make it
 89work") require constant clarification.
 90
 91## Git Workflow
 92
 93**Never push to `main`. Branch first, then open a merge/pull request.**
 94
 95This holds in every repository, with no exceptions for one-line changes or
 96for repositories with a single contributor.
 97
 981. Branch.
 992. Open the MR (gitbay) or PR (elsewhere).
1003. Full test suite green before merging.
1014. Merge, then delete the branch both locally and remotely.
1025. Commit messages reference issues: `Closes #N` / `Ref #N`.
103
104## gitbay (repos whose origin is gitbay.org)
105
106Most repos under `~/git/krz/` have their origin on **gitbay.org**, a
107self-hosted git forge (its own source is `krz/gitbay`). It is not GitHub.
108`gh` does nothing there, there are no pull requests, and there is no GitHub
109API. Do not try to map the workflow onto one. Everything below applies only
110when `git remote get-url origin` points at gitbay.org.
111
112- The `gitbay` CLI is installed and authenticated over SSH as `cmc`
113  (admin). `gitbay auth whoami` confirms it.
114- Merge requests, not pull requests. The noun is `mr`.
115- Writes go over SSH only. `git push` works over the `ssh://` origin;
116  HTTPS and `git://` are read transports.
117- Public repos are readable on the web without auth
118  (https://gitbay.org/krz/solar), so fetching a page works — but the CLI is
119  faster and gives you JSON.
120
121### Finding a command without guessing
122
123The server's command registry is the only source of truth for flags; the
124CLI is a thin passthrough. Ask it directly rather than guessing:
125
126```bash
127gitbay mr create --help
128```
129
130That prints the command's real usage. A prefix narrows the registry to one
131noun, over bare SSH or from a clone:
132
133```bash
134ssh git@gitbay.org help mr
135```
136
137Bare `help` lists every command, sorted, one line each with no flags — an
138index, not a reference. `--json` gives `{path, summary, usage}` per row.
139
140Two things this does not cover. `gitbay issue --help` (a group, not a
141command) still prints cobra's subcommand list without flags, so go one
142level deeper to `gitbay issue create --help`. And any command run with
143missing arguments prints its exact usage and exits 2, which is cheaper
144than a second guess. An unmatched `help` prefix exits 3.
145
146### The repo argument is inferred
147
148Inside a clone whose `origin` matches a configured instance
149(`gitbay remote list`), `<owner/name>` is filled in from the remote. These
150are equivalent inside `krz/gitbay`:
151
152```bash
153gitbay issue list
154gitbay issue list krz/gitbay
155```
156
157Outside a clone, or to target another repo, pass `<owner/name>` as the
158first argument. Inference never fires on a clone from some other host, so a
159GitHub checkout cannot hijack a command.
160
161### --json is the contract
162
163Every command takes `--json`. That output is stable; the human-readable
164output is not. Parse JSON, never the text.
165
166```bash
167gitbay issue list --state open --json
168gitbay dashboard --json
169```
170
171Exit codes: `0` ok, `1` failure, `2` usage, `3` not found, `4` denied,
172`5` protocol or ssh failure.
173
174### Long text
175
176Bodies come from `--body`/`--message`, from `--file -` on stdin, or from
177`$EDITOR` when neither is given. A non-interactive session must use stdin
178or it will hang waiting on an editor:
179
180```bash
181gitbay issue create --title "..." --file - <<'EOF'
182body text
183EOF
184```
185
186### Common tasks
187
188```bash
189gitbay dashboard                              # review queue, assigned work, builds
190gitbay issue list --state open
191gitbay issue show <n>
192gitbay issue comment <n> --file -
193gitbay mr create --source <branch> --target main --title "..."
194gitbay mr diff <n>
195gitbay mr merge <n> --strategy squash
196gitbay build list                             # CI
197gitbay build log <n>
198gitbay repo list --json
199gitbay init <name> [--private]                # git init + repo create + set origin
200```
201
202`krz/gitbay` has its own CLAUDE.md covering how the forge is built. The
203above is about using it as a client.
204
205---
206
207**These guidelines are working if:** fewer unnecessary changes in diffs, fewer
208rewrites due to overcomplication, and clarifying questions come before
209implementation rather than after mistakes.