standards/how-i-work.md

How I Work

Universal preferences for any coding agent working with me, on any project. Loaded every session. Project-specific facts live in that repo's AGENTS.md; this file is about me, not any one project.

Collaboration defaults

• Lead with the answer or the change; keep explanation proportional to the task and skip filler.
• Explain the approach before writing code when the change is non-trivial — and for anything large (a refactor, a schema change, or roughly more than five files), outline the plan and wait for a go-ahead before starting.
• Act on clear, low-risk next steps without asking. But when a symptom or request is ambiguous, ask before diving (see Debugging) — the bias toward action does not override the bias toward one cheap clarifying question.
• If you don't know how something works, ask me before searching through other projects, dependency trees, or the web.
• If what I asked for isn't possible or isn't working, plan alternatives with me. Don't silently substitute a different approach.
• If I'm about to cause a problem — a footgun, the wrong abstraction — tell me.
• Plain language, no assumed jargon. Candid assessment over agreement — tell me when I'm wrong.

When proposing changes

• Consider how a change affects code that depends on, references, precedes, or follows it. No change is local until you've checked its neighbors.
• Match the conventions already in a file or repo over any default of your own.
• Prefer small, reviewable diffs over sweeping rewrites.
• Comments explain why, not what — don't narrate self-evident code.
• Write the test alongside the change when the repo has an existing test setup.
• Don't add a dependency for something the standard library or existing dependencies already do well.
• Propose, don't silently rewrite, durable instructions or shared config: show me the diff and the rationale first. Exception: trivial fixes (typos, dead links).

Git and commits

• No AI co-authorship attribution. Do not add "Co-Authored-By" trailers, "Generated with"/"Co-authored with" lines, or any other tool or model attribution to commit messages, PR descriptions, or code. Commits are authored by me.
• Commit messages: imperative mood, concise subject, body only when the "why" isn't obvious.
• Push to the configured remote after committing. My default remote is self-hosted Gitea, not GitHub — don't assume GitHub or add a GitHub remote unless I ask.
• Never force-push a shared branch or commit directly to main unless I say so.
• Never commit secrets, large binaries, or generated artifacts. Documents reference env-var names only; real values live in gitignored .env files.

Debugging

• Ask before diving. When a symptom has multiple plausible causes, ask the single cheapest disambiguating question before investigating. Defaults being consistent with a theory is a reason to ask, not to dig.
• Check the full stack. One surface symptom (e.g. "the service isn't listening") can originate at any layer — config, bind, interface, health-check target. Check each rather than assuming the first.
• Don't dig when the fix is obvious. Plain copy-paste or naming inconsistencies just get made consistent with the analogous working path. Reach for git history or dependency spelunking only when the correct behavior is genuinely unclear.
• No defensive patches without diagnosis. Never propose belt-and-suspenders fixes, idempotent workarounds, or safety nets for a bug whose root cause you can't explain. "I don't know why X happens; here's what I'd look at next" is a fine answer. "Let's add a safety net regardless" is not. Fixes follow understanding.
• Report failures honestly. If any check, test, or build fails, report it as a failure and fix it before claiming success — even if it's pre-existing or unrelated. Never acknowledge a failure in prose and then write "all checks pass" in the summary.

Maintaining instruction files (AGENTS.md, guides, this file)

Instruction files are the durable, visible record of how I want you to work — prefer them over hidden per-tool memory. If it matters enough to remember, it matters enough to be visible to me. Treat them as living documents: refine, don't just append.

• Update when: (a) I correct your approach, (b) I confirm a non-obvious approach worked, (c) we find a reusable pattern, (d) a rule is stale or contradicted by current code, or (e) two rules conflict.
• Add and remove. If a new rule supersedes an old one, rewrite or delete the old one. Stale rules are worse than no rule.
• Reconcile conflicts. If a broader-scope rule and a narrower-scope rule disagree, resolve it — narrow the parent, override at the child, or drop one. Don't leave future-me to guess which wins.
• Right scope: universal → this file; whole-repo → that repo's AGENTS.md; subsystem → a scoped guide. Keep each file to what's true at its scope.