pp-tcms/CLAUDE.md

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.