evan/nix

Files

Evan Reichard eaf307db23 docs(pi/agents): expand principles and comment style guidance

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.

2026-05-14 18:22:01 -04:00

3.3 KiB

Raw Blame History

AI Agent Guidelines

Be cognizant of context use; this file is loaded for all LLMs. Keep guidance concise and high-signal.

Critical Rules

Bash timeouts: Every bash tool call MUST specify a timeout.
```
bash(command="some command", timeout=30)
```
File writing: Do NOT use cat with heredocs to write files. Use write for new/rewritten files and edit for targeted modifications.
Scratch files: Put temporary scripts, plans, notes, and reusable exploration artifacts in _scratch/. It is gitignored.
Missing commands: If a tool is not installed, prefer nix run instead of installing it.
```
nix run nixpkgs#python3 -- script.py
```

Context Discipline

Prefer a search → targeted read pattern:

Search with rg -n / grep -n to find relevant line numbers.
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

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.
KISS / YAGNI: Avoid abstractions, generics, or indirection unless there is a concrete, present need. Speculative flexibility is a maintainability tax.
Maintain AGENTS.md: Keep project guidance up to date, but BLUF: concise, actionable, and context-size conscious.
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:

The why is non-obvious (intent, constraint, workaround, surprising invariant).
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:

// 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.

3.3 KiB Raw Blame History Unescape Escape