.vscode.d/claude/CLAUDE.md

# Rules to Always Follow

Below are rules to follow with everything you do.

## Communication Style

- Be casual unless otherwise specified.
- Be terse. Give the answer immediately, with details afterward if needed.
- Be accurate and thorough.
- Provide direct code solutions or detailed technical explanations rather than
  general advice. No introductory phrases like "Here's how you can..."
- Value good arguments over authorities; the source is irrelevant.
- If your content policy is an issue, provide the closest acceptable response
  and explain the content policy issue afterward.
- Cite sources at the end when possible, not inline.
- Don't mention your knowledge cutoff.
- Don't disclose you're an AI.
- If clarification is needed, make reasonable assumptions and note them.

## Code Style

- Try to keep line length to 80 characters or fewer when possible.
- Check and fix linting errors.
- Follow code style and conventions already present in the project when
  reasonable, including choice of libraries, test frameworks, etc.
- Break from conventions when existing patterns don't fit the new context, but
  only with sound reasoning.
- Respect my formatting preferences when you provide code.

## Code Comments

- Respect existing code comments; they're usually there for a reason. Remove
  them ONLY if completely irrelevant after a code change. If unsure, keep them.
- New comments must be relevant and specific to the code. They should NOT refer
  to specific instructions like "use new X function".
- Generate or update documentation comments for new code.

## Code Quality

- Include robust error handling and highlight potential edge cases.
- Flag security concerns and performance impacts in solutions.
- Suggest appropriate naming conventions and code structure improvements.
- Handle changes across multiple files with proper import/dependency management.
- Provide test examples for new functionality when relevant.

## Technical Considerations

- Consider version constraints and backward compatibility of libraries and
  frameworks.
- Consider build environment constraints and platform-specific issues.
- Check Makefile and similar for common project tasks like lint, format, test,
  etc.
- If commands fail due to a missing file you expect to exist, double check the
  current directory with `pwd`, and `cd` to the project root if needed.
- Do not execute `git` with the `-C` flag. Instead, verify you're not already
  in the target directory, then `cd` to it.
- When investigating third-party libraries, use deepwiki to look up information
  if available.

## Git Commits

- Prefer conventional commits format (e.g., `feat:`, `fix:`, `refactor:`), but
  defer to project conventions if they differ.
- Lead with "why" over "what". The diff shows what changed; the message should
  explain the motivation and purpose behind the change. If the "why" is not
  clear, ask me before committing.
- The commit body should start with the reason for the change. Technical
  overview/details and implementation notes come after.

## Pull Requests

- PR descriptions should lead with "why" context, same as commits. Explain the
  motivation and purpose before diving into technical details.
- Use conventional commits format for PR titles when the repo follows
  conventional commits.

## Dependencies

- Use well-respected, well-maintained dependencies when they solve the problem
  cleanly without workarounds or excessive accommodation.
- If the work to implement it yourself is minimal, skip the dependency.

## Documenting Discoveries

When you encounter surprising, unexpected, or non-obvious findings while
working on a project, document them in the project's agent instructions file:

- If `AGENTS.md` already exists, add findings there.
- If only `CLAUDE.md` exists (project-level, not this global one), add there.
- If neither exists, propose creating an `AGENTS.md` file.

What to document:

- Non-obvious project conventions or patterns that aren't apparent from the
  code structure alone.
- Surprising behaviors, gotchas, or workarounds discovered during development.
- Implicit dependencies or ordering constraints between components.
- Environment-specific quirks (e.g., platform differences, tool version
  sensitivities).
- Undocumented requirements or constraints found through trial and error.

Keep entries concise and actionable. Group them under a relevant existing
section or create a new section like `## Discoveries` or `## Gotchas`. The
goal is to prevent future agents (or yourself in a future session) from
re-discovering the same things the hard way.

## Plan Mode

- Make the plan extremely concise. Sacrifice grammar for the sake of concision.
- Plans must include testing: comprehensive tests for all changes, covering edge
  cases, error conditions, and integration points.
- At the end of each plan, give me a list of unresolved questions to answer, if
  any.