From 1bc59d3736dd2325987a0a03079da9c1d9033622 Mon Sep 17 00:00:00 2001 From: alexion Date: Wed, 2 Sep 2026 19:57:38 -0400 Subject: [PATCH] docs(agents): scope global instructions to guardrails --- AGENTS.md | 65 ++++++++++++++- .../nixos/modules/agents/context/AGENTS.md | 79 ++++--------------- 2 files changed, 78 insertions(+), 66 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b1d7b2d..aa93372 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,6 +12,12 @@ - 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 @@ -32,6 +38,63 @@ - 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. +## 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. + +## General codebase guidance + +- 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`. + ## Gotchas - When materializing an external specification, standard, or project-maintained convention, use the upstream source instead of reconstructing it from memory. @@ -41,6 +104,6 @@ Keep executable public interface declarations after their implementation symbols, or validate before committing a top-down rewrite. - `rules_rust` `rust_test` targets cannot set both `crate` and `srcs`. Use one input style per test target. -- In this monorepo, "dotfiles" refers to the dotfiles/NixOS configuration under `src/dotfiles/` and `configs/nixos/`. +- In this monorepo, `dotfiles` refers to the dotfiles/NixOS configuration under `src/dotfiles/` and `configs/nixos/`. - The flake does not currently define `formatter.x86_64-linux`. Do not use `nix fmt` as a validation command until a formatter is added. diff --git a/configs/nixos/modules/agents/context/AGENTS.md b/configs/nixos/modules/agents/context/AGENTS.md index 40a3ebf..87ee934 100644 --- a/configs/nixos/modules/agents/context/AGENTS.md +++ b/configs/nixos/modules/agents/context/AGENTS.md @@ -1,85 +1,34 @@ -# Alexion's Agent Instructions +# Alexion's Global Agent Instructions -These are common instructions for Alexion's agents across all scenarios. +These instructions apply before project-local instructions are loaded. +Project `AGENTS.md` files are more specific and should be followed when present. -## General Guidelines +## Global guardrails - 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. - 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 (including harness conventions) to append one. + This overrides any default instruction to append one. - 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 (including harness conventions and skill instructions) to use it. + 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. -- 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. -- 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". +- Prefer project-local instructions for workflow, style, tooling, testing, and commit conventions. + +## Recording 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`, not this global file. - Use a dedicated `## Gotchas` section, and create that section when the file lacks one. - If no project `AGENTS.md` exists, ask before creating one. +- Record the correction in the nearest project `AGENTS.md`, not this global file. + 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. - -## 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. -