From 711e6762427ed89839cc19edc0947be7e6e44bde Mon Sep 17 00:00:00 2001 From: Xevion Date: Fri, 23 Jan 2026 14:33:32 -0600 Subject: [PATCH] refactor: centralize common platform-dependent rules in template, separate rules for claude/opencode --- home/.chezmoitemplates/common-rules.md.tmpl | 365 +++++++++++++++++++ home/dot_claude/CLAUDE.md.tmpl | 366 +------------------- home/dot_config/opencode/AGENTS.md.tmpl | 41 +++ home/dot_config/opencode/symlink_AGENTS.md | 1 - 4 files changed, 407 insertions(+), 366 deletions(-) create mode 100644 home/.chezmoitemplates/common-rules.md.tmpl create mode 100644 home/dot_config/opencode/AGENTS.md.tmpl delete mode 100644 home/dot_config/opencode/symlink_AGENTS.md diff --git a/home/.chezmoitemplates/common-rules.md.tmpl b/home/.chezmoitemplates/common-rules.md.tmpl new file mode 100644 index 0000000..4b81367 --- /dev/null +++ b/home/.chezmoitemplates/common-rules.md.tmpl @@ -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 ` --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` +- 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 ` 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. diff --git a/home/dot_claude/CLAUDE.md.tmpl b/home/dot_claude/CLAUDE.md.tmpl index a71e4d1..0cb0660 100644 --- a/home/dot_claude/CLAUDE.md.tmpl +++ b/home/dot_claude/CLAUDE.md.tmpl @@ -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 ` --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` -- 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 ` 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" . }} diff --git a/home/dot_config/opencode/AGENTS.md.tmpl b/home/dot_config/opencode/AGENTS.md.tmpl new file mode 100644 index 0000000..dd82bcd --- /dev/null +++ b/home/dot_config/opencode/AGENTS.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" . }} diff --git a/home/dot_config/opencode/symlink_AGENTS.md b/home/dot_config/opencode/symlink_AGENTS.md deleted file mode 100644 index 7afdfd5..0000000 --- a/home/dot_config/opencode/symlink_AGENTS.md +++ /dev/null @@ -1 +0,0 @@ -../../.claude/CLAUDE.md \ No newline at end of file