Working agreement
How I work with agents
The general rules I keep with any AI coding agent: collaboration, UI workflow, behavior, project conventions, and animation vocabulary. This page is my single source of truth; I copy it into CLAUDE.md / AGENTS.md when I start a new project.
Collaboration
- Before any non-trivial change (new deps, new files, architecture, security-sensitive code, "cleanup"), stop and propose. Wait for explicit approval.
- Never take autonomous decisions on design, path / folder structure, or dependencies.
- Give 2–3 options with a recommendation, not a single pre-decided path.
- When in doubt, ask.
UI changes need ASCII first
For any UI/UX change beyond a one-line tweak, sketch the proposed layout in ASCII and get sign-off before writing code. Skip only for pure typography/color tweaks or restoring an existing spec.
Why: silent visual decisions burn time. ASCII forces a shared mental model before code.
Behavioral rules
1. Think before coding. State assumptions explicitly. If multiple interpretations exist, present them. If a simpler approach exists, say so. If unclear, stop and ask.
2. Simplicity first. Minimum code that solves the problem. No speculative features, no abstractions for single-use code, no flexibility/configurability that wasn't requested, no error handling for impossible scenarios. If 200 lines could be 50, rewrite. Ask "would a senior engineer call this overcomplicated?" If yes, simplify.
3. Surgical changes. Touch only what you must. Don't "improve" adjacent code, formatting, or comments. Don't refactor what isn't broken. Match existing style even if you'd do it differently. Mention unrelated dead code, don't delete. Remove orphans your changes created; leave pre-existing dead code alone unless asked. Test: every changed line should trace directly to the user's request.
4. Goal-driven execution. Transform tasks into verifiable goals. "Add validation" → "write tests for invalid inputs, then make them pass." "Fix the bug" → "write a test that reproduces it, then make it pass." Loop until verified.
These bias toward caution over speed. For trivial tasks, use judgment.