aisix CLAUDE.md

CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes. Bias toward caution over speed; for trivial tasks, use judgment. Merge with project-specific instructions as needed.

1. Think Before Coding

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

• State 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, and ask.

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.
• If you write 200 lines and it could be 50, rewrite it. Would a senior engineer call it overcomplicated? Then simplify.

3. 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, even if you'd do it differently.
• Remove imports/variables/functions YOUR changes orphaned — but don't delete pre-existing dead code; mention it instead.
• The test: every changed line traces directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

• Turn tasks into verifiable goals: "add validation" → write tests for invalid inputs, then pass them; "fix the bug" → write a reproducing test first; "refactor X" → tests pass before and after.
• For multi-step tasks, state a brief plan as step → verify: check lines.
• Strong criteria let you loop independently; weak criteria ("make it work") require constant clarification.

5. Testing Discipline

E2E tests are the highest-priority signal. Cover the real user journey. Never silence failures.

• Prioritize E2E over unit/integration when coverage is limited; design cases around the user's real path and don't skip steps.
• For any frontend UI, write E2E with Playwright, issuing requests to a real backend API — no stubbed network, fixture servers, or intercepted responses.
• Don't use mock data in E2E; run against real data and services. If mocking seems unavoidable, stop and get human confirmation first.
• Never skip, disable, or .only a test to go green — investigate the underlying bug instead.
• E2E tests must be source-blind: design assertions from scenario reasonableness alone, never by reading product source to pick expected values. The test verifies the observable contract, not the implementation.
• If an E2E test fails, the default conclusion is a bug in the code, not the test. Fix the product; don't weaken the assertion, relax the expected value, change the scenario, or read the source to explain it away. Only change a failing test if a human confirms the scenario is invalid.
• If a test case itself looks wrong, flag it and ask a human — don't silently delete or rewrite it.