Guidelines for development

Slightly customized guidelines for LLMs, heavily based on https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md.

1. Think Before Coding🔗

Don’t assume. Don’t hide confusion. Surface tradeoffs.

Before implementing:

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them - don’t pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what’s confusing. Ask.

Once aligned, implement directly: the code is the output. Don’t wrap it in preamble, narration, or after-the-fact reasoning unless asked. The clarifying questions, stated assumptions, and the step plan (§4) are where prose belongs - the implementation itself is not.

2. Simplicity First🔗

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No “flexibility” or “configurability” that wasn’t requested.
• No error handling for impossible scenarios.
• No cleverness for its own sake - write code that reads plainly.
• If you write 200 lines and it could be 50, rewrite it.

Ask yourself: “Would a senior engineer say this is overcomplicated?” If yes, simplify.

3. Surgical Changes🔗

Touch only what you must. Clean up only your own mess.

When editing existing code:

• Don’t “improve” adjacent code, comments, or formatting.
• Don’t refactor things that aren’t broken.
• Match existing style, even if you’d do it differently.
• If you notice unrelated dead code, mention it - don’t delete it.

When your changes create orphans:

• Remove imports/variables/functions that YOUR changes made unused.
• Don’t remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user’s request.

4. Goal-Driven Execution🔗

Define success criteria. Loop until verified.

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”
• “Refactor X” → “Ensure tests pass before and after”

For anything larger than a single function, state a brief plan and work one step at a time, finishing and verifying each step before starting the next:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Each step ships with its own tests; a step isn’t done until it’s tested.

Split by change size. Use semver as a yardstick: anything above a minor change - i.e. a breaking / major change - must be split into separate steps. Never bundle a breaking change into a single pass.

Strong success criteria let you loop independently. Weak criteria (“make it work”) require constant clarification.

5. Code & Documentation Standards🔗

Readable, typed, and documented at the function level.

• When the language supports type hints or equivalent (annotations, generics, typed signatures), always use them.
• Prefer modern, idiomatic techniques and current language/library features over legacy patterns - as long as they’re stable and well-supported, not novel for novelty’s sake.
• Use the language and tooling that fit the task.
• Every function carries at least a comment stating its purpose, inputs/outputs, and any non-obvious behavior. Self-documenting names complement these comments; they don’t replace them.
• For non-trivial logic, comment the why, not just the what.
• When implementing a third-party integration, link the relevant API documentation in comments where possible - the specific endpoint/method, not just the product homepage.

6. Safety🔗

Validate what comes from outside. Stay inside your output path.

• Validate input at trust boundaries (user input, external data, API responses). Fail clearly on invalid input rather than continuing in a bad state. This governs real external input - it is not a license to add handling for impossible internal states (§2 still applies).
• Never create or write files outside the designated output path unless the user explicitly asks.