Evan Reichard
eaf307db23
Add explicit priority order (correctness > maintainability > polish), tighten comment style to default-no-comment with why-only rationale, and document splitting skill workflow from reference sub-docs.
74 lines
3.3 KiB
Markdown
74 lines
3.3 KiB
Markdown
# AI Agent Guidelines
|
||
|
||
Be cognizant of context use; this file is loaded for all LLMs. Keep guidance concise and high-signal.
|
||
|
||
## Critical Rules
|
||
|
||
1. **Bash timeouts**: Every `bash` tool call MUST specify a timeout.
|
||
```bash
|
||
bash(command="some command", timeout=30)
|
||
```
|
||
|
||
2. **File writing**: Do NOT use `cat` with heredocs to write files. Use `write` for new/rewritten files and `edit` for targeted modifications.
|
||
|
||
3. **Scratch files**: Put temporary scripts, plans, notes, and reusable exploration artifacts in `_scratch/`. It is gitignored.
|
||
|
||
4. **Missing commands**: If a tool is not installed, prefer `nix run` instead of installing it.
|
||
```bash
|
||
nix run nixpkgs#python3 -- script.py
|
||
```
|
||
|
||
## Context Discipline
|
||
|
||
Prefer a **search → targeted read** pattern:
|
||
|
||
1. Search with `rg -n` / `grep -n` to find relevant line numbers.
|
||
2. Read only the needed range with `read(path, offset, limit)`.
|
||
|
||
Full-file reads are fine when genuinely needed, but avoid them as the default reflex.
|
||
|
||
## Principles
|
||
|
||
1. **Priority order**: When goals conflict, optimize in this order:
|
||
1. **Correctness** — solve the actual use case, including the realistic failure modes (not just the happy path).
|
||
2. **Maintainability / readability** — non-negotiable. Code is read far more than it is written; clarity wins over cleverness.
|
||
3. **Abstraction & polish** — only after the above are solid, and only when a concrete need justifies it.
|
||
|
||
All three matter, but never sacrifice (2) for (3). Prefer obvious, boring code over slick code that requires a paragraph to explain.
|
||
|
||
2. **KISS / YAGNI**: Avoid abstractions, generics, or indirection unless there is a concrete, present need. Speculative flexibility is a maintainability tax.
|
||
|
||
3. **Maintain AGENTS.md**: Keep project guidance up to date, but BLUF: concise, actionable, and context-size conscious.
|
||
|
||
4. **Knowledge Capture Check**: Before the final response, ask whether the task revealed a non-obvious convention, pitfall, repeatable workflow, or missing helper. If yes, briefly recommend exactly where to capture it: package/project AGENTS.md, global AGENTS.md, a skill, or a helper script. Skip this note when there is nothing meaningful.
|
||
|
||
## Style
|
||
|
||
### Comment Style
|
||
|
||
Default to **no comment**. Code should be self-explanatory through naming and structure. Only add a comment when it earns its place by explaining something the code cannot.
|
||
|
||
Write a comment when, and only when:
|
||
|
||
1. The _why_ is non-obvious (intent, constraint, workaround, surprising invariant).
|
||
2. A reader familiar with the language/codebase would otherwise stop and ask "why?".
|
||
|
||
Do not narrate _what_ the code does. Do not add Title Case section headers over logical blocks just to label them.
|
||
|
||
When a comment _is_ warranted, use a short Title Case label, a dash, and the _why_:
|
||
|
||
```go
|
||
// Map Component Results - Downstream consumers expect a name-keyed lookup.
|
||
for _, comp := range components {
|
||
results[comp.Name] = comp.Result
|
||
}
|
||
```
|
||
|
||
Rules for the explanation after the dash:
|
||
|
||
- Keep it to **2–3 sentences max**. Never a paragraph.
|
||
- State the _why_ directly. Do not restate what the code does, recap prior context, or hedge.
|
||
- Do **not** hard-wrap comments at 80 columns. Up to ~120 is fine.
|
||
|
||
If a block is complex enough that it needs a heading just to be navigable, that is usually a signal to extract a well-named function instead.
|