b0c0e75637
- docker-compose: mount ~/tcms-db-data for the sqlite database - add CLAUDE.md agent coding guidelines Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
85 lines
3.2 KiB
Markdown
85 lines
3.2 KiB
Markdown
# CLAUDE.md — Agent Instructions
|
|
|
|
Behavioral guidelines for AI coding agents. Merges Andrej Karpathy's
|
|
LLM coding-pitfall observations with the Ponytail minimalism ladder.
|
|
|
|
**Tradeoff:** bias toward caution *and* minimalism. On trivial tasks,
|
|
use judgment — don't ask when the answer is obvious, just write the
|
|
smallest thing that works.
|
|
|
|
---
|
|
|
|
## 1. Think before coding
|
|
|
|
Don't assume. Don't hide confusion. Surface tradeoffs.
|
|
|
|
- State assumptions explicitly.
|
|
- If interpretations genuinely diverge, ask ONE clarifying question.
|
|
Otherwise take the minimal reading, write the assumption as an inline
|
|
comment, and proceed — do not stall.
|
|
- If a simpler approach exists, say so. Push back when warranted.
|
|
|
|
## 2. Write the least code that works (the ladder)
|
|
|
|
Before writing any code, stop at the FIRST rung that solves the task:
|
|
|
|
1. **Skip it** — is the feature even needed? (YAGNI)
|
|
2. **Stdlib** — does the standard library already do this?
|
|
3. **Native** — does the platform/runtime have it built in?
|
|
4. **Existing dependency** — can something already installed do the job?
|
|
5. **One line** — can it be one line?
|
|
6. **Minimum** — only now, write the least code that works.
|
|
|
|
No features beyond what was asked. No abstractions for single-use code.
|
|
No speculative flexibility or configurability. No error handling for
|
|
impossible scenarios. If you wrote 200 lines and it could be 50, rewrite.
|
|
|
|
Test: "Would a senior engineer call this overcomplicated?" If yes, simplify.
|
|
|
|
## 3. Where laziness stops
|
|
|
|
Section 2 does NOT apply to these — here, do it properly:
|
|
|
|
- Input validation at trust boundaries.
|
|
- Error handling that prevents data loss.
|
|
- Security.
|
|
- Accessibility.
|
|
- Calibration real hardware needs (clocks drift, sensors read off — the
|
|
platform is never the spec ideal).
|
|
- Anything the user explicitly requested.
|
|
|
|
## 4. Mark and verify your shortcuts
|
|
|
|
Lazy code without a check is unfinished.
|
|
|
|
- Mark every intentional simplification with a `ponytail:` comment. If the
|
|
shortcut has a known ceiling (global lock, O(n²) scan, naive heuristic),
|
|
the comment names the ceiling and the upgrade path.
|
|
- Non-trivial logic leaves behind ONE runnable check — the smallest thing
|
|
that fails if the logic breaks (an assert-based self-check or one small
|
|
test file; no frameworks, no fixtures).
|
|
- Turn the task into a verifiable goal and loop until it passes:
|
|
- "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 multi-step tasks, state a brief plan: `1. step → verify: check`.
|
|
|
|
## 5. Surgical changes
|
|
|
|
Touch only what you must. Clean up only your own mess.
|
|
|
|
- Don't "improve" adjacent code, comments, or formatting.
|
|
- Don't refactor what isn't broken. Match existing style.
|
|
- Remove imports/variables/functions that YOUR changes made unused.
|
|
- Pre-existing dead code: mention it, don't delete it (unless asked).
|
|
|
|
Test: every changed line traces directly to the user's request.
|
|
|
|
---
|
|
|
|
**Working if:** fewer unnecessary changes in diffs, fewer rewrites from
|
|
overcomplication, clarifying questions come *before* implementation rather
|
|
than after mistakes, and intentional shortcuts are visible (`ponytail:`)
|
|
rather than silent.
|