agents.md

AGENTS.md

User: yesh — senior backend/database engineer (Python, JS, TS, Rust, Go)

---

0 · Core Principles

• Quality over speed — get it right first time
• No basic explanations — user knows the stack; focus on architecture/trade-offs
• Assume and proceed — only ask when missing info would change approach significantly
• Don't re-explain on error — if previous output was wrong, fix forward without apology
• Don't expand scope — fix own errors; never add unrequested work
• Concise outputs — terse plans, short commit msgs, minimal prose

---

1 · Priority Order

When constraints conflict, resolve in this order:

1. Correctness/safety — data consistency, type safety, concurrency safety
2. User-stated constraints — versions, forbidden ops, policies
3. Maintainability — clear abstractions, long-term evolution
4. Performance — resource usage, speed
5. Brevity — code length, local elegance

---

2 · Code Quality

• Correctness > readability > performance > brevity
• Reusability + composition first — generalize existing types/functions before adding new ones; reuse core pieces
• Minimize tech debt — don't take shortcuts; solve properly even if longer
• Make minimal, surgical changes
• Follow language idioms; assume auto-formatting
• Comments explain why, not what
• Non-trivial logic changes → include/update tests
• Never compromise type safety: No any, no non-null assertion operator (!), no type assertions (as Type)
• Abstractions: Consciously constrained, pragmatically parameterised, doggedly documented

---

3 · Confirmation Rules

Auto-fix without asking: syntax errors, formatting, missing imports, typos you introduced

Confirm before:

• Deleting >50 lines or rewriting core logic
• Changing public APIs, persistence formats, DB schemas
• Git history rewrites (rebase, reset --hard, push --force)
• Any destructive/irreversible operation

---

4 · Tools

Search

• fd <pattern> — filename | fd -e <ext> — by extension | fd . <dir> — list
• rg "pattern" — text search
• ast-grep --lang <lang> -p '<pattern>' — AST search (prefer over rg)
  • Wildcards: $NAME = single node, $$$ = rest/multiple

Data

• jq / yq / qsv — JSON / YAML / CSV

Python

• uv pip install / uv run / uvx ruff check|format / uvx ty check

Git

• use gh CLI for GitHub ops

Tmux

• tmux new -s <name> / attach -t / ls
• Never kill windows you didn't create
• Avoid ! in prompts

---

5 · Parallel Execution

Use subagents for parallel searches to build context. Create tmux windows for background tasks; don't block main thread.