alexion/dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(agents): merge global instructions into monorepo

Browse Source
This commit is contained in:
alexion
2026-09-02 20:03:56 -04:00
parent 6f92e170ed
commit 9d30d6bd01
1 changed files with 85 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
AGENTS.md
View File

@@ -6,12 +6,20 @@
Before writing a commit message, read `docs/conventional-commits.md`. Before writing a commit message, read `docs/conventional-commits.md`.
- Keep commit messages about the Git history, not the forge workflow. - Keep commit messages about the Git history, not the forge workflow.
Include external references only when they are stable context for the change. 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 ## Technical writing
- Use `docs/technical-writing.md` and `docs/dictionary.md` for authored prose. - Use `docs/technical-writing.md` and `docs/dictionary.md` for authored prose.
Use the nearest project dictionary for project-specific domain language. 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 ## Pull requests
@@ -19,6 +27,9 @@
Preserve review history until the pull request is ready to merge. 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. - 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. 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 ## Forge workflow
@@ -32,6 +43,79 @@
- Stage new files that Nix discovers through flake evaluation before testing. - 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. 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 <tool> on the target machine`.
Do not write `placeholder for <missing feature>`.
- 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 ## Gotchas
- When materializing an external specification, standard, or project-maintained convention, use the upstream source instead of reconstructing it from memory. - When materializing an external specification, standard, or project-maintained convention, use the upstream source instead of reconstructing it from memory.