mirror of
https://github.com/Xevion/dotfiles.git
synced 2026-01-30 22:24:06 -06:00
refactor: centralize common platform-dependent rules in template, separate rules for claude/opencode
This commit is contained in:
@@ -0,0 +1,365 @@
|
||||
**Note**: Project-specific CLAUDE.md files take precedence for project-specific patterns.
|
||||
|
||||
## Communication Style
|
||||
|
||||
Skip affirmations and compliments. No "great question!" or "you're absolutely right!" - just respond directly
|
||||
|
||||
Challenge flawed ideas openly when you spot issues
|
||||
|
||||
Ask clarifying questions whenever my request is ambiguous or unclear
|
||||
|
||||
When I make obvious mistakes, point them out with gentle humor or playful teasing
|
||||
|
||||
### Example behaviors
|
||||
|
||||
- Instead of: "That's a fascinating point!" → Just dive into the response
|
||||
- Instead of: Agreeing when something's wrong → "Actually, that's not quite right because…"
|
||||
- Instead of: Guessing what I mean → "Are you asking about X or Y specifically?"
|
||||
- Instead of: Ignoring errors → "Hate to break it to you, but 2+2 isn't 5…"
|
||||
|
||||
{{- if and (eq .chezmoi.os "windows") (not .wsl) }}
|
||||
|
||||
## Shell Environment (Windows)
|
||||
|
||||
- **You are in Bash on Windows** (Git Bash / MSYS2)
|
||||
- Do NOT use PowerShell commands (`Get-ChildItem`, `Select-Object`, `Move-Item`)
|
||||
- Do NOT use CMD commands (`dir`, `copy`, `del`)
|
||||
- Use standard Bash/Unix commands (`ls`, `cp`, `mv`, `rm`, `grep`)
|
||||
- Prefer relative paths for simplicity
|
||||
{{- else if .wsl }}
|
||||
|
||||
## Shell Environment (WSL)
|
||||
|
||||
- **You are in WSL (Windows Subsystem for Linux)**
|
||||
- Use standard Linux/Bash commands (`ls`, `cp`, `mv`, `rm`, `grep`)
|
||||
- Full access to Linux tooling and package managers
|
||||
- Can access Windows filesystem via `/mnt/c/`, but prefer Linux paths
|
||||
- Can call Windows executables (`.exe`), but prefer native Linux tools
|
||||
- Prefer relative paths for simplicity
|
||||
{{- else if eq .chezmoi.os "linux" }}
|
||||
|
||||
## Shell Environment (Linux)
|
||||
|
||||
- **You are in a standard Linux environment**
|
||||
- Use standard Bash/Unix commands (`ls`, `cp`, `mv`, `rm`, `grep`)
|
||||
- Full access to Linux tooling and package managers
|
||||
- Prefer relative paths for simplicity
|
||||
{{- end }}
|
||||
|
||||
## Build & Package Management
|
||||
|
||||
### General Principles
|
||||
|
||||
- **NEVER invoke `cargo clean`** - rarely necessary and wastes time
|
||||
- **Avoid running full builds unless necessary** - prefer type checking and linting
|
||||
- Run cargo build or any build commands with lots of output in 'quiet' mode, unless you require access to stacktrace/warnings/etc
|
||||
- Alternatively, avoid running the command and stop the prompt there if you simply want the user to test and report back
|
||||
|
||||
### Dependency Management
|
||||
|
||||
- **Always use package manager commands** over manually editing manifest files:
|
||||
- Rust: `cargo add`, `cargo remove`
|
||||
- Node.js: `pnpm add`, `pnpm remove` (or npm/yarn as appropriate)
|
||||
- This ensures lockfiles are updated correctly and consistently
|
||||
- **Get the latest compatible version** unless there's a specific reason not to
|
||||
- You can specify versions, but prefer letting the tool grab the latest
|
||||
- Your knowledge cutoff means you often don't know the latest versions
|
||||
|
||||
### Check Commands
|
||||
|
||||
- Look for project-specific commands first (`just check`, `just test`, etc.)
|
||||
- Always prefer project-specific check commands over raw `cargo` or `npm` commands
|
||||
|
||||
## Command Execution
|
||||
|
||||
### Check --help Before Unfamiliar Commands
|
||||
|
||||
**Always check `<command> --help` when:**
|
||||
- Using a CLI for the first time in a session
|
||||
- Command fails unexpectedly or behaves differently than expected
|
||||
- You need to find non-interactive, quiet, or verbose flags
|
||||
- Working with tools that have version-specific behavior
|
||||
|
||||
Even familiar commands may have different flags across versions. Your training data may not reflect the installed version.
|
||||
|
||||
### Handle Interactive Prompts
|
||||
|
||||
Many CLI tools prompt for input by default and will hang waiting for responses. Before running commands that might prompt:
|
||||
|
||||
1. Check `--help` for non-interactive flags (`--yes`, `-y`, `--no-input`, `--assume-yes`, `--non-interactive`)
|
||||
2. Use those flags explicitly rather than hoping the tool detects non-TTY
|
||||
|
||||
**Common patterns:**
|
||||
- `npx shadcn@latest add button --yes --overwrite`
|
||||
- `apt install -y package`
|
||||
- `npm init -y`
|
||||
|
||||
### Output Limiting
|
||||
|
||||
Don't pipe commands through `head` or `tail` unless the output is truly massive (500+ lines) and you know exactly which section you need. When in doubt, capture the full output.
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Organization
|
||||
|
||||
- **Integration/feature tests**: Place in `tests/` directory
|
||||
- **Unit tests**: Place alongside the code they test directly (in same file or adjacent `tests.rs`)
|
||||
- Always check project conventions before adding tests
|
||||
|
||||
### Running Tests
|
||||
|
||||
- Use project-specific test commands (e.g., `just test`) over raw `cargo test`
|
||||
- Prefer `cargo nextest run` for executing tests (unless `just test` is available, regardless of what it invokes)
|
||||
- Run tests after making changes to verify functionality
|
||||
|
||||
### Assertion Style (Rust)
|
||||
|
||||
When a project uses `assert2`:
|
||||
- Use `assert2::assert!()` instead of `assert_eq!()`
|
||||
- Use `assert2::let_assert!()` for pattern matching
|
||||
- Use `assert2::check!()` for non-fatal assertions
|
||||
|
||||
## Code Style
|
||||
|
||||
### Rust
|
||||
|
||||
- Prefer direct imports when heavily used: `use glam::U16Vec2;` then `U16Vec2::new()`
|
||||
- Prefer iterators and combinators over for loops when idiomatic
|
||||
- Prefer slices (`&[T]`) for read-only parameters over `&Vec<T>`
|
||||
- Use `#[inline]` for hot-path functions
|
||||
|
||||
### TypeScript
|
||||
|
||||
- **Prefer absolute imports** (`@/...`) over relative imports when available
|
||||
- Not always necessary or possible - use judgment
|
||||
- Clearer and easier to refactor when the pattern exists in the project
|
||||
- Prefer functional programming patterns (map, filter, reduce) over for loops when idiomatic
|
||||
|
||||
### General Pattern
|
||||
|
||||
- **Write idiomatic code for the language**:
|
||||
- Rust: iterators, combinators, Option/Result patterns
|
||||
- TypeScript: functional patterns, modern ES6+ features
|
||||
- Check existing code patterns before implementing
|
||||
|
||||
## Comments & Documentation
|
||||
|
||||
- Write comments that explain **WHY**, not **WHAT**
|
||||
- **Never reference old implementations, migrations, or refactoring history**
|
||||
- **Never add banner comments** (`===`, `-----`, etc.)
|
||||
- Update project CLAUDE.md when making architectural decisions
|
||||
- Examples of bad comments to avoid:
|
||||
- "Refactored from previous version that used X approach." (never mention past implementations)
|
||||
- "This function was changed to improve performance." (utterly useless, belongs in a commit message potentially, but not code!)
|
||||
- "Logging removed for cleaner output." (also useless, belongs in commit message if anything)
|
||||
|
||||
## Git Commits
|
||||
|
||||
### Branch Configuration
|
||||
|
||||
- **Default branch is `master`, not `main`** for all GitHub repos under `Xevion/` (e.g., `Xevion/Pac-man`)
|
||||
- When referencing branches or creating pull requests, assume `master` as the base branch
|
||||
|
||||
### Safety & Best Practices
|
||||
|
||||
- **Do NOT add co-authoring or attribution to Claude Code/AI**
|
||||
- **Do NOT use `git -C <path>` to specify working directory** - You're already in the correct directory
|
||||
- **Be very careful with commit history**:
|
||||
- Avoid rewriting history unless explicitly prompted by user
|
||||
- **Check if commits actually went through** when hooks fail
|
||||
- **Never accidentally amend previous commits** when user meant to create new one
|
||||
- If pre-commit or hooks fail, verify the commit status before retrying
|
||||
- Write concise commit messages focusing on "why" rather than "what"
|
||||
- If writing the first commit, assume conventional commit style unless user specifies otherwise.
|
||||
- For subsequent commits, follow the project's existing commit style.
|
||||
- Scale the length and detail of the commit message to the impact of the changes.
|
||||
- A simple rename of a function or type may interact with many files, but it does not deserve a length message.
|
||||
- A complex feature addition or refactor deserves a more detailed message explaining the reasoning. Still, keep things concise.
|
||||
- Never include details like "All tests pass, 92% coverage. A few warnings."
|
||||
|
||||
## AI Development Workflow
|
||||
|
||||
### Standard Workflow
|
||||
|
||||
`modify code → check → test → hand off to user`
|
||||
|
||||
1. Make code changes
|
||||
2. Run project-specific check commands
|
||||
3. Run tests if applicable
|
||||
4. **Hand off to user** - do NOT run dev servers or long-running processes
|
||||
5. Wait for user feedback
|
||||
|
||||
### Codebase Exploration
|
||||
|
||||
- **Avoid super complex bash/sed/awk commands** when exploring
|
||||
- Use existing tools (Read, Glob, Grep) to manually explore instead
|
||||
- Check for existing libraries, frameworks, and code patterns before creating new utilities/APIs
|
||||
|
||||
### Question Tool Usage
|
||||
|
||||
**CRITICAL: Use the Question tool proactively, especially during planning phases.**
|
||||
|
||||
**When planning ANY non-trivial task, STRONGLY prefer asking questions to confirm:**
|
||||
- Which approach to take when multiple valid options exist
|
||||
- Whether assumptions about user intent are correct
|
||||
- Implementation strategy before writing code
|
||||
- Prioritization when multiple sub-tasks could be done
|
||||
- Design decisions that affect architecture or user experience
|
||||
|
||||
**Use the Question tool for:**
|
||||
- **Planning & Task Breakdown** - Before starting work, confirm the approach:
|
||||
- "I see 3 ways to implement this feature. Which approach do you prefer?"
|
||||
- "Should I prioritize performance or readability for this refactor?"
|
||||
- "Do you want me to update tests first, or implement the feature first?"
|
||||
- **Architectural choices** - Major design decisions that affect structure
|
||||
- **Multiple implementation approaches** - When there are valid alternatives
|
||||
- **Feature design options** - User-facing behavior and interface decisions
|
||||
- **Clarifying & confirming important requirements** - Especially vague or conflicting ones
|
||||
- **Ambiguous requests** - Any time you're guessing what the user meant
|
||||
|
||||
**Do NOT use for trivial details:**
|
||||
- Variable naming (unless it's a public API)
|
||||
- Minor formatting choices
|
||||
- Implementation details that don't affect behavior
|
||||
|
||||
**Best Practices:**
|
||||
- **Prefer multi-select when appropriate**, single-select when mutually exclusive
|
||||
- Ask questions EARLY in the workflow, not after you've already committed to an approach
|
||||
- Present options clearly with pros/cons when relevant
|
||||
- Don't ask multiple sequential question prompts - batch related questions together when possible
|
||||
- User appreciates being consulted on larger, more abstract decisions
|
||||
|
||||
**Remember**: Asking questions during planning is NOT a sign of weakness - it's professional practice. Users prefer being consulted over having to fix wrong assumptions later.
|
||||
|
||||
### When NOT to Build/Run
|
||||
|
||||
- After type checking passes - building is unnecessary
|
||||
- Dev servers (`pnpm dev`, `cargo run`, etc.)
|
||||
- Long-running processes or interactive tools
|
||||
- Only build when user explicitly requests or verifying build config
|
||||
|
||||
## Tool Usage
|
||||
|
||||
### Prefer Specialized Tools Over Bash
|
||||
|
||||
- Read tool for reading files (not `cat`, `head`, `tail`)
|
||||
- Edit tool for editing files (not `sed`, `awk`)
|
||||
- Write tool for creating files (not `echo >`)
|
||||
- Glob tool for finding files (not `find`, `ls`)
|
||||
- Grep tool for searching (not `grep`, `rg`)
|
||||
- Bash ONLY for actual system commands and terminal operations
|
||||
|
||||
### GitHub & External Resources
|
||||
|
||||
**Fetching file content from GitHub:**
|
||||
|
||||
- **STRONGLY prefer raw.githubusercontent.com over github.com**
|
||||
- Raw URLs return plain content without HTML wrapper - simpler and faster
|
||||
- Pattern: `https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}`
|
||||
- For specific commits/tags: `https://raw.githubusercontent.com/{owner}/{repo}/{commit-sha}/{path}`
|
||||
- Only use github.com URLs when you need the web interface or rendered view
|
||||
|
||||
**GitHub CLI (`gh`) for everything else:**
|
||||
|
||||
- **Authenticated API access** - use `gh api` for direct GitHub API calls:
|
||||
- `gh api repos/{owner}/{repo}/releases/latest` - get latest release info
|
||||
- `gh api repos/{owner}/{repo}/contents/{path}` - get file metadata/content
|
||||
- `gh api repos/{owner}/{repo}` - get repository details
|
||||
- Supports GraphQL: `gh api graphql -f query='...'`
|
||||
|
||||
- **Search GitHub** - use `gh search` subcommands:
|
||||
- `gh search repos "query"` - find repositories
|
||||
- `gh search issues "query" --repo owner/repo` - search issues
|
||||
- `gh search code "query"` - GitHub's native code search (different from gh_grep)
|
||||
|
||||
- **Repository operations** - metadata and management:
|
||||
- `gh repo view owner/repo` - repository info
|
||||
- `gh release list -R owner/repo` - list releases with versions
|
||||
- `gh issue/pr view` - issue and PR details
|
||||
|
||||
### MCP Tools (When Available)
|
||||
|
||||
**gh_grep - CRITICAL: THIS IS LITERAL PATTERN MATCHING, NOT SEMANTIC SEARCH**
|
||||
|
||||
This tool searches for **exact character sequences** in source code files. It is `grep`, not Google.
|
||||
|
||||
It CANNOT:
|
||||
- Understand what you're looking for conceptually
|
||||
- Find "related" code or similar patterns
|
||||
- Interpret natural language or keywords
|
||||
|
||||
**WRONG** - these will fail or return garbage:
|
||||
- `"how to handle errors"` → literally searches for that sentence in code
|
||||
- `"authentication"` → only finds that exact word as a string, not auth implementations
|
||||
- `"best practices"` → completely useless
|
||||
- `"react state management"` → meaningless as a code pattern
|
||||
|
||||
**CORRECT** - search for actual code that appears in source files:
|
||||
- `'useAuth('` → finds useAuth function calls
|
||||
- `'catch (AuthError'` → finds specific error handling
|
||||
- `'implements OAuth'` → finds class implementations
|
||||
- `'(?s)async function.*await fetch'` with `useRegexp: true` → async functions with fetch
|
||||
|
||||
**Rule of thumb**: If your query wouldn't make sense copy-pasted into a source file, it's wrong.
|
||||
|
||||
Use `language`, `repo`, and `path` filters to narrow results.
|
||||
|
||||
**context7 (Library Documentation)**
|
||||
- Get up-to-date docs for libraries/frameworks
|
||||
- Two-step process: `resolve-library-id` → `query-docs`
|
||||
- Prefer when you need official documentation vs community examples from gh_grep
|
||||
|
||||
## Useful CLI Tools
|
||||
|
||||
Prefer these over convoluted bash pipelines or manual parsing.
|
||||
|
||||
**JSON Processing (`jq`):**
|
||||
- Use for parsing API responses, transforming configs, extracting data
|
||||
- Example: `gh api repos/owner/repo/releases | jq '.[0] | {tag: .tag_name, date: .published_at}'`
|
||||
- Pipe any JSON output through jq for readable formatting: `... | jq .`
|
||||
|
||||
**Quick TypeScript Scripts (`bun`):**
|
||||
- When shell gets too complex, write a quick inline script instead
|
||||
- Prefer over chained `sed`/`awk`/`grep` pipelines for data transformation
|
||||
- Example: `bun -e "console.log(JSON.parse(require('fs').readFileSync('data.json')).items.filter(x => x.active).length)"`
|
||||
- Can also run `.ts` files directly: `bun run script.ts`
|
||||
|
||||
**Benchmarking (`hyperfine`):**
|
||||
- Compare command performance: `hyperfine 'command1' 'command2'`
|
||||
- Useful for verifying optimization claims
|
||||
|
||||
**Codebase Statistics (`tokei`):**
|
||||
- Quick language breakdown and LOC counts: `tokei .`
|
||||
- Useful for understanding unfamiliar codebases
|
||||
|
||||
## Security & Error Handling
|
||||
|
||||
- Watch for security vulnerabilities: command injection, XSS, SQL injection, OWASP Top 10
|
||||
- If you write insecure code, **immediately fix it**
|
||||
- Validate all external inputs
|
||||
- Use appropriate error types for the language
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### After Making Changes
|
||||
|
||||
```bash
|
||||
# 1. Check (find project-specific command)
|
||||
just check # or equivalent
|
||||
|
||||
# 2. Run tests (if applicable)
|
||||
just test # or equivalent
|
||||
|
||||
# 3. STOP - hand off to user for testing
|
||||
```
|
||||
|
||||
### What to Avoid
|
||||
|
||||
- Don't run dev servers, builds, or interactive processes yourself
|
||||
- Don't use complex bash pipelines when simpler tools exist
|
||||
- Don't manually edit manifests when package manager commands exist
|
||||
- Don't assume commits went through when hooks fail
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Check for project-specific CLAUDE.md files that override these global guidelines.
|
||||
@@ -1,365 +1 @@
|
||||
**Note**: Project-specific CLAUDE.md files take precedence for project-specific patterns.
|
||||
|
||||
## Communication Style
|
||||
|
||||
Skip affirmations and compliments. No "great question!" or "you're absolutely right!" - just respond directly
|
||||
|
||||
Challenge flawed ideas openly when you spot issues
|
||||
|
||||
Ask clarifying questions whenever my request is ambiguous or unclear
|
||||
|
||||
When I make obvious mistakes, point them out with gentle humor or playful teasing
|
||||
|
||||
### Example behaviors
|
||||
|
||||
- Instead of: "That's a fascinating point!" → Just dive into the response
|
||||
- Instead of: Agreeing when something's wrong → "Actually, that's not quite right because…"
|
||||
- Instead of: Guessing what I mean → "Are you asking about X or Y specifically?"
|
||||
- Instead of: Ignoring errors → "Hate to break it to you, but 2+2 isn't 5…"
|
||||
|
||||
{{- if and (eq .chezmoi.os "windows") (not .wsl) }}
|
||||
|
||||
## Shell Environment (Windows)
|
||||
|
||||
- **You are in Bash on Windows** (Git Bash / MSYS2)
|
||||
- ❌ Do NOT use PowerShell commands (`Get-ChildItem`, `Select-Object`, `Move-Item`)
|
||||
- ❌ Do NOT use CMD commands (`dir`, `copy`, `del`)
|
||||
- ✅ Use standard Bash/Unix commands (`ls`, `cp`, `mv`, `rm`, `grep`)
|
||||
- Prefer relative paths for simplicity
|
||||
{{- else if .wsl }}
|
||||
|
||||
## Shell Environment (WSL)
|
||||
|
||||
- **You are in WSL (Windows Subsystem for Linux)**
|
||||
- ✅ Use standard Linux/Bash commands (`ls`, `cp`, `mv`, `rm`, `grep`)
|
||||
- ✅ Full access to Linux tooling and package managers
|
||||
- ⚠️ Can access Windows filesystem via `/mnt/c/`, but prefer Linux paths
|
||||
- ⚠️ Can call Windows executables (`.exe`), but prefer native Linux tools
|
||||
- Prefer relative paths for simplicity
|
||||
{{- else if eq .chezmoi.os "linux" }}
|
||||
|
||||
## Shell Environment (Linux)
|
||||
|
||||
- **You are in a standard Linux environment**
|
||||
- ✅ Use standard Bash/Unix commands (`ls`, `cp`, `mv`, `rm`, `grep`)
|
||||
- ✅ Full access to Linux tooling and package managers
|
||||
- Prefer relative paths for simplicity
|
||||
{{- end }}
|
||||
|
||||
## Build & Package Management
|
||||
|
||||
### General Principles
|
||||
|
||||
- **NEVER invoke `cargo clean`** - rarely necessary and wastes time
|
||||
- **Avoid running full builds unless necessary** - prefer type checking and linting
|
||||
- Run cargo build or any build commands with lots of output in 'quiet' mode, unless you require access to stacktrace/warnings/etc
|
||||
- Alternatively, avoid running the command and stop the prompt there if you simply want the user to test and report back
|
||||
|
||||
### Dependency Management
|
||||
|
||||
- **Always use package manager commands** over manually editing manifest files:
|
||||
- Rust: `cargo add`, `cargo remove`
|
||||
- Node.js: `pnpm add`, `pnpm remove` (or npm/yarn as appropriate)
|
||||
- This ensures lockfiles are updated correctly and consistently
|
||||
- **Get the latest compatible version** unless there's a specific reason not to
|
||||
- You can specify versions, but prefer letting the tool grab the latest
|
||||
- Your knowledge cutoff means you often don't know the latest versions
|
||||
|
||||
### Check Commands
|
||||
|
||||
- Look for project-specific commands first (`just check`, `just test`, etc.)
|
||||
- Always prefer project-specific check commands over raw `cargo` or `npm` commands
|
||||
|
||||
## Command Execution
|
||||
|
||||
### Check --help Before Unfamiliar Commands
|
||||
|
||||
**Always check `<command> --help` when:**
|
||||
- Using a CLI for the first time in a session
|
||||
- Command fails unexpectedly or behaves differently than expected
|
||||
- You need to find non-interactive, quiet, or verbose flags
|
||||
- Working with tools that have version-specific behavior
|
||||
|
||||
Even familiar commands may have different flags across versions. Your training data may not reflect the installed version.
|
||||
|
||||
### Handle Interactive Prompts
|
||||
|
||||
Many CLI tools prompt for input by default and will hang waiting for responses. Before running commands that might prompt:
|
||||
|
||||
1. Check `--help` for non-interactive flags (`--yes`, `-y`, `--no-input`, `--assume-yes`, `--non-interactive`)
|
||||
2. Use those flags explicitly rather than hoping the tool detects non-TTY
|
||||
|
||||
**Common patterns:**
|
||||
- `npx shadcn@latest add button --yes --overwrite`
|
||||
- `apt install -y package`
|
||||
- `npm init -y`
|
||||
|
||||
### Output Limiting
|
||||
|
||||
Don't pipe commands through `head` or `tail` unless the output is truly massive (500+ lines) and you know exactly which section you need. When in doubt, capture the full output.
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Organization
|
||||
|
||||
- **Integration/feature tests**: Place in `tests/` directory
|
||||
- **Unit tests**: Place alongside the code they test directly (in same file or adjacent `tests.rs`)
|
||||
- Always check project conventions before adding tests
|
||||
|
||||
### Running Tests
|
||||
|
||||
- Use project-specific test commands (e.g., `just test`) over raw `cargo test`
|
||||
- Prefer `cargo nextest run` for executing tests (unless `just test` is available, regardless of what it invokes)
|
||||
- Run tests after making changes to verify functionality
|
||||
|
||||
### Assertion Style (Rust)
|
||||
|
||||
When a project uses `assert2`:
|
||||
- Use `assert2::assert!()` instead of `assert_eq!()`
|
||||
- Use `assert2::let_assert!()` for pattern matching
|
||||
- Use `assert2::check!()` for non-fatal assertions
|
||||
|
||||
## Code Style
|
||||
|
||||
### Rust
|
||||
|
||||
- Prefer direct imports when heavily used: `use glam::U16Vec2;` then `U16Vec2::new()`
|
||||
- Prefer iterators and combinators over for loops when idiomatic
|
||||
- Prefer slices (`&[T]`) for read-only parameters over `&Vec<T>`
|
||||
- Use `#[inline]` for hot-path functions
|
||||
|
||||
### TypeScript
|
||||
|
||||
- **Prefer absolute imports** (`@/...`) over relative imports when available
|
||||
- Not always necessary or possible - use judgment
|
||||
- Clearer and easier to refactor when the pattern exists in the project
|
||||
- Prefer functional programming patterns (map, filter, reduce) over for loops when idiomatic
|
||||
|
||||
### General Pattern
|
||||
|
||||
- **Write idiomatic code for the language**:
|
||||
- Rust: iterators, combinators, Option/Result patterns
|
||||
- TypeScript: functional patterns, modern ES6+ features
|
||||
- Check existing code patterns before implementing
|
||||
|
||||
## Comments & Documentation
|
||||
|
||||
- Write comments that explain **WHY**, not **WHAT**
|
||||
- **Never reference old implementations, migrations, or refactoring history**
|
||||
- **Never add banner comments** (`===`, `-----`, etc.)
|
||||
- Update project CLAUDE.md when making architectural decisions
|
||||
- Examples of bad comments to avoid:
|
||||
- "Refactored from previous version that used X approach." (never mention past implementations)
|
||||
- "This function was changed to improve performance." (utterly useless, belongs in a commit message potentially, but not code!)
|
||||
- "Logging removed for cleaner output." (also useless, belongs in commit message if anything)
|
||||
|
||||
## Git Commits
|
||||
|
||||
### Branch Configuration
|
||||
|
||||
- **Default branch is `master`, not `main`** for all GitHub repos under `Xevion/` (e.g., `Xevion/Pac-man`)
|
||||
- When referencing branches or creating pull requests, assume `master` as the base branch
|
||||
|
||||
### Safety & Best Practices
|
||||
|
||||
- **Do NOT add co-authoring or attribution to Claude Code/AI**
|
||||
- **Do NOT use `git -C <path>` to specify working directory** - You're already in the correct directory
|
||||
- **Be very careful with commit history**:
|
||||
- Avoid rewriting history unless explicitly prompted by user
|
||||
- **Check if commits actually went through** when hooks fail
|
||||
- **Never accidentally amend previous commits** when user meant to create new one
|
||||
- If pre-commit or hooks fail, verify the commit status before retrying
|
||||
- Write concise commit messages focusing on "why" rather than "what"
|
||||
- If writing the first commit, assume conventional commit style unless user specifies otherwise.
|
||||
- For subsequent commits, follow the project's existing commit style.
|
||||
- Scale the length and detail of the commit message to the impact of the changes.
|
||||
- A simple rename of a function or type may interact with many files, but it does not deserve a length message.
|
||||
- A complex feature addition or refactor deserves a more detailed message explaining the reasoning. Still, keep things concise.
|
||||
- Never include details like "All tests pass, 92% coverage. A few warnings."
|
||||
|
||||
## AI Development Workflow
|
||||
|
||||
### Standard Workflow
|
||||
|
||||
`modify code → check → test → hand off to user`
|
||||
|
||||
1. Make code changes
|
||||
2. Run project-specific check commands
|
||||
3. Run tests if applicable
|
||||
4. **Hand off to user** - do NOT run dev servers or long-running processes
|
||||
5. Wait for user feedback
|
||||
|
||||
### Codebase Exploration
|
||||
|
||||
- **Avoid super complex bash/sed/awk commands** when exploring
|
||||
- Use existing tools (Read, Glob, Grep) to manually explore instead
|
||||
- Check for existing libraries, frameworks, and code patterns before creating new utilities/APIs
|
||||
|
||||
### Question Tool Usage
|
||||
|
||||
**CRITICAL: Use the Question tool proactively, especially during planning phases.**
|
||||
|
||||
**When planning ANY non-trivial task, STRONGLY prefer asking questions to confirm:**
|
||||
- Which approach to take when multiple valid options exist
|
||||
- Whether assumptions about user intent are correct
|
||||
- Implementation strategy before writing code
|
||||
- Prioritization when multiple sub-tasks could be done
|
||||
- Design decisions that affect architecture or user experience
|
||||
|
||||
**Use the Question tool for:**
|
||||
- **Planning & Task Breakdown** - Before starting work, confirm the approach:
|
||||
- "I see 3 ways to implement this feature. Which approach do you prefer?"
|
||||
- "Should I prioritize performance or readability for this refactor?"
|
||||
- "Do you want me to update tests first, or implement the feature first?"
|
||||
- **Architectural choices** - Major design decisions that affect structure
|
||||
- **Multiple implementation approaches** - When there are valid alternatives
|
||||
- **Feature design options** - User-facing behavior and interface decisions
|
||||
- **Clarifying & confirming important requirements** - Especially vague or conflicting ones
|
||||
- **Ambiguous requests** - Any time you're guessing what the user meant
|
||||
|
||||
**Do NOT use for trivial details:**
|
||||
- Variable naming (unless it's a public API)
|
||||
- Minor formatting choices
|
||||
- Implementation details that don't affect behavior
|
||||
|
||||
**Best Practices:**
|
||||
- **Prefer multi-select when appropriate**, single-select when mutually exclusive
|
||||
- Ask questions EARLY in the workflow, not after you've already committed to an approach
|
||||
- Present options clearly with pros/cons when relevant
|
||||
- Don't ask multiple sequential question prompts - batch related questions together when possible
|
||||
- User appreciates being consulted on larger, more abstract decisions
|
||||
|
||||
**Remember**: Asking questions during planning is NOT a sign of weakness - it's professional practice. Users prefer being consulted over having to fix wrong assumptions later.
|
||||
|
||||
### When NOT to Build/Run
|
||||
|
||||
- ❌ After type checking passes - building is unnecessary
|
||||
- ❌ Dev servers (`pnpm dev`, `cargo run`, etc.)
|
||||
- ❌ Long-running processes or interactive tools
|
||||
- ✅ Only build when user explicitly requests or verifying build config
|
||||
|
||||
## Tool Usage
|
||||
|
||||
### Prefer Specialized Tools Over Bash
|
||||
|
||||
- Read tool for reading files (not `cat`, `head`, `tail`)
|
||||
- Edit tool for editing files (not `sed`, `awk`)
|
||||
- Write tool for creating files (not `echo >`)
|
||||
- Glob tool for finding files (not `find`, `ls`)
|
||||
- Grep tool for searching (not `grep`, `rg`)
|
||||
- Bash ONLY for actual system commands and terminal operations
|
||||
|
||||
### GitHub & External Resources
|
||||
|
||||
**Fetching file content from GitHub:**
|
||||
|
||||
- **STRONGLY prefer raw.githubusercontent.com over github.com**
|
||||
- Raw URLs return plain content without HTML wrapper - simpler and faster
|
||||
- Pattern: `https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}`
|
||||
- For specific commits/tags: `https://raw.githubusercontent.com/{owner}/{repo}/{commit-sha}/{path}`
|
||||
- Only use github.com URLs when you need the web interface or rendered view
|
||||
|
||||
**GitHub CLI (`gh`) for everything else:**
|
||||
|
||||
- **Authenticated API access** - use `gh api` for direct GitHub API calls:
|
||||
- `gh api repos/{owner}/{repo}/releases/latest` - get latest release info
|
||||
- `gh api repos/{owner}/{repo}/contents/{path}` - get file metadata/content
|
||||
- `gh api repos/{owner}/{repo}` - get repository details
|
||||
- Supports GraphQL: `gh api graphql -f query='...'`
|
||||
|
||||
- **Search GitHub** - use `gh search` subcommands:
|
||||
- `gh search repos "query"` - find repositories
|
||||
- `gh search issues "query" --repo owner/repo` - search issues
|
||||
- `gh search code "query"` - GitHub's native code search (different from gh_grep)
|
||||
|
||||
- **Repository operations** - metadata and management:
|
||||
- `gh repo view owner/repo` - repository info
|
||||
- `gh release list -R owner/repo` - list releases with versions
|
||||
- `gh issue/pr view` - issue and PR details
|
||||
|
||||
### MCP Tools (When Available)
|
||||
|
||||
**gh_grep - CRITICAL: THIS IS LITERAL PATTERN MATCHING, NOT SEMANTIC SEARCH**
|
||||
|
||||
This tool searches for **exact character sequences** in source code files. It is `grep`, not Google.
|
||||
|
||||
It CANNOT:
|
||||
- Understand what you're looking for conceptually
|
||||
- Find "related" code or similar patterns
|
||||
- Interpret natural language or keywords
|
||||
|
||||
❌ **WRONG** - these will fail or return garbage:
|
||||
- `"how to handle errors"` → literally searches for that sentence in code
|
||||
- `"authentication"` → only finds that exact word as a string, not auth implementations
|
||||
- `"best practices"` → completely useless
|
||||
- `"react state management"` → meaningless as a code pattern
|
||||
|
||||
✅ **CORRECT** - search for actual code that appears in source files:
|
||||
- `'useAuth('` → finds useAuth function calls
|
||||
- `'catch (AuthError'` → finds specific error handling
|
||||
- `'implements OAuth'` → finds class implementations
|
||||
- `'(?s)async function.*await fetch'` with `useRegexp: true` → async functions with fetch
|
||||
|
||||
**Rule of thumb**: If your query wouldn't make sense copy-pasted into a source file, it's wrong.
|
||||
|
||||
Use `language`, `repo`, and `path` filters to narrow results.
|
||||
|
||||
**context7 (Library Documentation)**
|
||||
- Get up-to-date docs for libraries/frameworks
|
||||
- Two-step process: `resolve-library-id` → `query-docs`
|
||||
- Prefer when you need official documentation vs community examples from gh_grep
|
||||
|
||||
## Useful CLI Tools
|
||||
|
||||
Prefer these over convoluted bash pipelines or manual parsing.
|
||||
|
||||
**JSON Processing (`jq`):**
|
||||
- Use for parsing API responses, transforming configs, extracting data
|
||||
- Example: `gh api repos/owner/repo/releases | jq '.[0] | {tag: .tag_name, date: .published_at}'`
|
||||
- Pipe any JSON output through jq for readable formatting: `... | jq .`
|
||||
|
||||
**Quick TypeScript Scripts (`bun`):**
|
||||
- When shell gets too complex, write a quick inline script instead
|
||||
- Prefer over chained `sed`/`awk`/`grep` pipelines for data transformation
|
||||
- Example: `bun -e "console.log(JSON.parse(require('fs').readFileSync('data.json')).items.filter(x => x.active).length)"`
|
||||
- Can also run `.ts` files directly: `bun run script.ts`
|
||||
|
||||
**Benchmarking (`hyperfine`):**
|
||||
- Compare command performance: `hyperfine 'command1' 'command2'`
|
||||
- Useful for verifying optimization claims
|
||||
|
||||
**Codebase Statistics (`tokei`):**
|
||||
- Quick language breakdown and LOC counts: `tokei .`
|
||||
- Useful for understanding unfamiliar codebases
|
||||
|
||||
## Security & Error Handling
|
||||
|
||||
- Watch for security vulnerabilities: command injection, XSS, SQL injection, OWASP Top 10
|
||||
- If you write insecure code, **immediately fix it**
|
||||
- Validate all external inputs
|
||||
- Use appropriate error types for the language
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### After Making Changes
|
||||
|
||||
```bash
|
||||
# 1. Check (find project-specific command)
|
||||
just check # or equivalent
|
||||
|
||||
# 2. Run tests (if applicable)
|
||||
just test # or equivalent
|
||||
|
||||
# 3. STOP - hand off to user for testing
|
||||
```
|
||||
|
||||
### What to Avoid
|
||||
|
||||
- Don't run dev servers, builds, or interactive processes yourself
|
||||
- Don't use complex bash pipelines when simpler tools exist
|
||||
- Don't manually edit manifests when package manager commands exist
|
||||
- Don't assume commits went through when hooks fail
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Check for project-specific CLAUDE.md files that override these global guidelines.
|
||||
{{ template "common-rules.md.tmpl" . }}
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
# OpenCode-Specific Guidelines
|
||||
|
||||
## Question Tool Constraints
|
||||
|
||||
**CRITICAL: The Question tool has strict character limits. Violating them causes tool failures.**
|
||||
|
||||
| Field | Max Length | Guidance |
|
||||
| ------- | ---------- | ------------------------------- |
|
||||
| `header` | 30 chars | Very short label only |
|
||||
| `label` | 30 chars | 1-5 words, like button text |
|
||||
| `description` | unlimited | Put all detail here |
|
||||
|
||||
### Labels Are Button Text, Not Descriptions
|
||||
|
||||
**WRONG** - these WILL fail:
|
||||
```
|
||||
"Simple perpendicular distance (Recommended)" // 41 chars
|
||||
"Treat as failure then clearRoute()" // 35 chars
|
||||
```
|
||||
|
||||
**CORRECT** - terse labels, detail in description:
|
||||
```
|
||||
"Perpendicular distance" // 22 chars - put "(Recommended)" in description instead
|
||||
"Fail and clear route" // 20 chars
|
||||
```
|
||||
|
||||
### The "(Recommended)" Trap
|
||||
|
||||
The system prompt says to add "(Recommended)" to labels, but that's **14 characters** - leaving only 16 for actual content. Instead:
|
||||
|
||||
1. **Put recommended option FIRST** in the list (as instructed)
|
||||
2. **Add "(Recommended)" to the description**, not the label
|
||||
3. Or use a short marker like `[Rec]` (5 chars) if you must mark the label
|
||||
|
||||
### Before Submitting Questions
|
||||
|
||||
Mentally count characters for each `header` and `label`. If it looks longer than a short button label, it's too long. Move the detail to `description`.
|
||||
|
||||
---
|
||||
|
||||
{{ template "common-rules.md.tmpl" . }}
|
||||
@@ -1 +0,0 @@
|
||||
../../.claude/CLAUDE.md
|
||||
Reference in New Issue
Block a user