AGENTS.md ยท diff
git:20260328.a6fd4f6 to git:20260412.eb0097c
138 added, 4 removed. Audit A to A.
# Claude Code Prompt for Plan Mode
#prompts
Review this plan thoroughly before making any code changes. For every issue or recommendation, explain the concrete tradeoffs, give me an opinionated recommendation, and ask for my input before assuming a direction.
My engineering preferences (use these to guide your recommendations):
+
- DRY is important--flag repetition aggressively.
- Well-tested code is non-negotiable; I'd rather have too many tests than too few.
- I want code that's "engineered enough" -- not under-engineered (fragile, hacky) and not over-engineered (premature abstraction, unnecessary complexity).
- I err on the side of handling more edge cases, not fewer; thoughtfulness > speed.
- Bias toward explicit over clever.
1. Architecture review
- Evaluate:
+ Evaluate:
+
- Overall system design and component boundaries.
- Dependency graph and coupling concerns.
- Data flow patterns and potential bottlenecks.
- Scaling characteristics and single points of failure.
- Security architecture (auth, data access, API boundaries).
2. Code quality review
- Evaluate:
+ Evaluate:
+
- Code organization and module structure.
- DRY violations--be aggressive here.
- Error handling patterns and missing edge cases (call these out explicitly).
- Technical debt hotspots.
- Areas that are over-engineered or under-engineered relative to my preferences.
3. Test review
- Evaluate:
+ Evaluate:
+
- Test coverage gaps (unit, integration, e2e).
- Test quality and assertion strength.
- Missing edge case coverage--be thorough.
- Untested failure modes and error paths.
4. Performance review
- Evaluate:
+ Evaluate:
+
- N+1 queries and database access patterns.
- Memory-usage concerns.
- Caching opportunities.
- Slow or high-complexity code paths.
For each issue you find
For every specific issue (bug, smell, design concern, or risk):
+
- Describe the problem concretely, with file and line references.
- Present 2-3 options, including "do nothing" where that's reasonable.
- For each option, specify: implementation effort, risk, impact on other code, and maintenance burden.
- Give me your recommended option and why, mapped to my preferences above.
- Then explicitly ask whether I agree or want to choose a different direction before proceeding.
Workflow and interaction
+
- Do not assume my priorities on timeline or scale.
- After each section, pause and ask for my feedback before moving on.
BEFORE YOU START,
Ask if I want one of two options:
1/ BIG CHANGE: Work through this interactively, one section at a time (Architecture -> Code Quality -> Tests -> Performance) with at most 4 top issues in each section
2/ SMALL CHANGE: Work through interactively ONE question per review section
FOR EACH STAGE OF REVIEW: output the explanation and pros and cons of each stage's questions AND your opinionated recommendation and why, and then use AskUserQuestion. Also NUMBER issues and then give LETTERS for options and when using AskUserQuestion make sure each option clearly labels the issue NUMBER and option LETTER so the user doesn't get confused. Make the recommended option always the 1st option.
+
+ # Ultracite Code Standards
+
+ This project uses **Ultracite**, a zero-config preset that enforces strict code quality standards through automated formatting and linting.
+
+ ## Quick Reference
+
+ - **Format code**: `pnpm dlx ultracite fix`
+ - **Check for issues**: `pnpm dlx ultracite check`
+ - **Diagnose setup**: `pnpm dlx ultracite doctor`
+
+ Oxlint + Oxfmt (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable.
+
+ ---
+
+ ## Core Principles
+
+ Write code that is **accessible, performant, type-safe, and maintainable**. Focus on clarity and explicit intent over brevity.
+
+ ### Type Safety & Explicitness
+
+ - Use explicit types for function parameters and return values when they enhance clarity
+ - Prefer `unknown` over `any` when the type is genuinely unknown
+ - Use const assertions (`as const`) for immutable values and literal types
+ - Leverage TypeScript's type narrowing instead of type assertions
+ - Use meaningful variable names instead of magic numbers - extract constants with descriptive names
+
+ ### Modern JavaScript/TypeScript
+
+ - Use arrow functions for callbacks and short functions
+ - Prefer `for...of` loops over `.forEach()` and indexed `for` loops
+ - Use optional chaining (`?.`) and nullish coalescing (`??`) for safer property access
+ - Prefer template literals over string concatenation
+ - Use destructuring for object and array assignments
+ - Use `const` by default, `let` only when reassignment is needed, never `var`
+
+ ### Async & Promises
+
+ - Always `await` promises in async functions - don't forget to use the return value
+ - Use `async/await` syntax instead of promise chains for better readability
+ - Handle errors appropriately in async code with try-catch blocks
+ - Don't use async functions as Promise executors
+
+ ### React & JSX
+
+ - Use function components over class components
+ - Call hooks at the top level only, never conditionally
+ - Specify all dependencies in hook dependency arrays correctly
+ - Use the `key` prop for elements in iterables (prefer unique IDs over array indices)
+ - Nest children between opening and closing tags instead of passing as props
+ - Don't define components inside other components
+ - Use semantic HTML and ARIA attributes for accessibility:
+ - Provide meaningful alt text for images
+ - Use proper heading hierarchy
+ - Add labels for form inputs
+ - Include keyboard event handlers alongside mouse events
+ - Use semantic elements (`<button>`, `<nav>`, etc.) instead of divs with roles
+
+ ### Error Handling & Debugging
+
+ - Remove `console.log`, `debugger`, and `alert` statements from production code
+ - Throw `Error` objects with descriptive messages, not strings or other values
+ - Use `try-catch` blocks meaningfully - don't catch errors just to rethrow them
+ - Prefer early returns over nested conditionals for error cases
+
+ ### Code Organization
+
+ - Keep functions focused and under reasonable cognitive complexity limits
+ - Extract complex conditions into well-named boolean variables
+ - Use early returns to reduce nesting
+ - Prefer simple conditionals over nested ternary operators
+ - Group related code together and separate concerns
+
+ ### Security
+
+ - Add `rel="noopener"` when using `target="_blank"` on links
+ - Avoid `dangerouslySetInnerHTML` unless absolutely necessary
+ - Don't use `eval()` or assign directly to `document.cookie`
+ - Validate and sanitize user input
+
+ ### Performance
+
+ - Avoid spread syntax in accumulators within loops
+ - Use top-level regex literals instead of creating them in loops
+ - Prefer specific imports over namespace imports
+ - Avoid barrel files (index files that re-export everything)
+ - Use proper image components (e.g., Next.js `<Image>`) over `<img>` tags
+
+ ### Framework-Specific Guidance
+
+ **Next.js:**
+
+ - Use Next.js `<Image>` component for images
+ - Use `next/head` or App Router metadata API for head elements
+ - Use Server Components for async data fetching instead of async Client Components
+
+ **React 19+:**
+
+ - Use ref as a prop instead of `React.forwardRef`
+
+ **Solid/Svelte/Vue/Qwik:**
+
+ - Use `class` and `for` attributes (not `className` or `htmlFor`)
+
+ ---
+
+ ## Testing
+
+ - Write assertions inside `it()` or `test()` blocks
+ - Avoid done callbacks in async tests - use async/await instead
+ - Don't use `.only` or `.skip` in committed code
+ - Keep test suites reasonably flat - avoid excessive `describe` nesting
+
+ ## When Oxlint + Oxfmt Can't Help
+
+ Oxlint + Oxfmt's linter will catch most issues automatically. Focus your attention on:
+
+ 1. **Business logic correctness** - Oxlint + Oxfmt can't validate your algorithms
+ 2. **Meaningful naming** - Use descriptive names for functions, variables, and types
+ 3. **Architecture decisions** - Component structure, data flow, and API design
+ 4. **Edge cases** - Handle boundary conditions and error states
+ 5. **User experience** - Accessibility, performance, and usability considerations
+ 6. **Documentation** - Add comments for complex logic, but prefer self-documenting code
+
+ ---
+
+ Most formatting and common issues are automatically fixed by Oxlint + Oxfmt. Run `pnpm dlx ultracite fix` before committing to ensure compliance.