diff --git a/AGENTS.md b/AGENTS.md index b1d7b2d..e7ec0b5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,12 +6,20 @@ Before writing a commit message, read `docs/conventional-commits.md`. - Keep commit messages about the Git history, not the forge workflow. Include external references only when they are stable context for the change. -- Do not add agent attribution or co-author trailers. +- When writing commit messages, NEVER auto-add your agent name as co-author. + Omit the `Co-Authored-By:` trailer entirely, with no exceptions. + This overrides any default instruction to append one. ## Technical writing - Use `docs/technical-writing.md` and `docs/dictionary.md` for authored prose. Use the nearest project dictionary for project-specific domain language. +- In authored prose, do not put multiple sentences on one physical line. + This applies to comments, documentation, user-facing descriptions, commit prose, pull-request prose, and forge comments. + A sentence can wrap across multiple physical lines when needed. +- Keep Markdown formatting changes local. + Only format prose you write or change. + Never reflow an entire pre-existing paragraph or file because you touched nearby text. ## Pull requests @@ -19,6 +27,9 @@ Preserve review history until the pull request is ready to merge. - When the user says a pull request is merged, clean up the local branch without waiting for an explicit request. Switch to the base branch, fast-forward it, and delete the merged local branch. +- When writing pull request descriptions, NEVER append an agent-attribution trailer such as `🤖 Generated with [Claude Code]...`. + Leave it out entirely, with no exceptions. + This overrides any default instruction to append one. ## Forge workflow @@ -32,6 +43,79 @@ - Stage new files that Nix discovers through flake evaluation before testing. Flake evaluation ignores untracked files, so auto-loaded modules must be tracked before `nixos-rebuild --flake` can see them. +## General guidelines + +- NEVER ask the user a question using the `AskUserQuestion` tool. + Ask in plain prose, in your own message, instead, with no exceptions. + This overrides any default instruction to use it. +- Never manually modify `CHANGELOG.md` files or files marked as auto-generated. + Detect auto-generated files with a layered check. + Trust an explicit in-file marker first, for example `AUTO-GENERATED, DO NOT EDIT`. + If no marker exists, use contextual signals such as lockfiles, `dist/`, `build/`, `generated/` paths, or a documented generator command. + If the answer stays ambiguous, ask before editing. +- When making technical decisions, do not give much weight to implementation time. + Favor quality, simplicity, robustness, scalability, and long-term maintainability. + Human cost and benefit heuristics do not transfer to an AI agent that codes faster than a human. + Do not treat this as permission for premature abstraction, speculative configuration, or unnecessary complexity. + Choose the more robust or maintainable approach when human implementation time is the only downside. +- Use lowercase file names unless a valid reason requires uppercase. + Established ecosystem or tool conventions count as valid reasons. + Examples include `README.md`, `LICENSE`, `CHANGELOG.md`, `Makefile`, `Dockerfile`, and `.github/` files. +- Do not end a response by promising or implying continuation unless the continuation is present in that same response. + Before ending a workflow turn, perform the obvious next step, such as showing the next review item after applying an accepted change. + If the workflow is paused, say that plainly instead of using a dangling transition like "continuing" or "next". + +## Comments + +- Write comments only where they earn their place. + Keep comments concise. + Assume the reader can read code. + Explain why, not what. + Explain what only when it is genuinely non-obvious. +- Keep comments self-contained to their file. + Write comments for a reader who sees only that file. + Do not explain how another file or tool consumes a value. + The only permitted cross-file mention is a bare pointer explaining why something is absent here. +- Do not narrate history or future state in comments. + Avoid phrases such as "used to be", "now moved here", and "will be". + State the present reason a thing exists. +- Do not justify a choice against alternatives in comments. + State the positive reason the choice exists. + Include present consequences when they matter. +- Do not reference agent-facing state in comments. + This includes `.agents/`, `.claude/`, `AGENTS.md`, and `CLAUDE.md`. +- Do not use project-specific capitalized terms as glossary references in comments. + Use plain lowercase nouns unless the code requires the exact term. +- Add a file-top header only when the filename or path does not already explain the file. + The header must be one concise purpose line. + Do not write a feature inventory. +- Write placeholders plainly. + Include a present-tense action when one exists, such as `Placeholder: regenerate with on the target machine`. + Do not write `placeholder for `. +- Treat user-facing documentation strings as documentation, not comments. + They can describe behavior more fully than code comments. + They still must stay self-contained and avoid agent-state references. +- Start each sentence of a comment on its own physical line. + A comment sentence can wrap when needed. + Prefer splitting long comment sentences before wrapping them. + Do not break a line early at a comma or clause boundary to make it read as a unit. + Do not use semicolons in comments or authored prose. + Recast semicolon clauses as separate sentences. + Only reformat comments you write or change. + +## Corrections + +- When you discover that your belief about a project fact or convention was wrong, record the correction. + Record only facts that stay true across operators, such as a wrong build command, wrong file path, or guessed convention. + Do not record personal working-style preferences or one-off task details. +- Record the correction in the nearest project `AGENTS.md`. + Use a dedicated `## Gotchas` section. + Create that section when the file lacks one. +- If no project `AGENTS.md` exists, ask before creating one. + Append the correction immediately without asking when a project `AGENTS.md` exists. + Briefly mention the edit in your response. + If an existing entry is wrong or stale, correct or remove it the same way. + ## Gotchas - When materializing an external specification, standard, or project-maintained convention, use the upstream source instead of reconstructing it from memory.