chore: update claude markdown docs (#20446)

Suggesting some improvements for claude code and tasks usage. See comments inline. --------- Co-authored-by: Dean Sheather <dean@deansheather.com>
2026-06-02 20:48:20 +00:00 · 2025-10-24 16:05:18 +01:00
parent cd0a2849d0
commit 7bad7e35ae
3 changed files with 57 additions and 24 deletions
@@ -91,6 +91,9 @@

 ## Systematic Debugging Approach

+YOU MUST ALWAYS find the root cause of any issue you are debugging
+YOU MUST NEVER fix a symptom or add a workaround instead of finding a root cause, even if it is faster.
+
 ### Multi-Issue Problem Solving

 When facing multiple failing tests or complex integration issues:
@@ -98,16 +101,21 @@ When facing multiple failing tests or complex integration issues:
 1. **Identify Root Causes**:
   - Run failing tests individually to isolate issues
   - Use LSP tools to trace through call chains
-   - Check both compilation and runtime errors
+   - Read Error Messages Carefully: Check both compilation and runtime errors
+   - Reproduce Consistently: Ensure you can reliably reproduce the issue before investigating
+   - Check Recent Changes: What changed that could have caused this? Git diff, recent commits, etc.
+   - When You Don't Know: Say "I don't understand X" rather than pretending to know

 2. **Fix in Logical Order**:
   - Address compilation issues first (imports, syntax)
   - Fix authorization and RBAC issues next
   - Resolve business logic and validation issues
   - Handle edge cases and race conditions last
+   - IF your first fix doesn't work, STOP and re-analyze rather than adding more fixes

 3. **Verification Strategy**:
-   - Test each fix individually before moving to next issue
+   - Always Test each fix individually before moving to next issue
+   - Verify Before Continuing: Did your test work? If not, form new hypothesis - don't add more fixes
   - Use `make lint` and `make gen` after database changes
   - Verify RFC compliance with actual specifications
   - Run comprehensive test suites before considering complete
@@ -40,11 +40,15 @@
 - Use proper error types
 - Pattern: `xerrors.Errorf("failed to X: %w", err)`

-### Naming Conventions
+## Naming Conventions

- Use clear, descriptive names
- Abbreviate only when obvious
+- Names MUST tell what code does, not how it's implemented or its history
 - Follow Go and TypeScript naming conventions
+- When changing code, never document the old behavior or the behavior change
+- NEVER use implementation details in names (e.g., "ZodValidator", "MCPWrapper", "JSONParser")
+- NEVER use temporal/historical context in names (e.g., "LegacyHandler", "UnifiedTool", "ImprovedInterface", "EnhancedParser")
+- NEVER use pattern names unless they add clarity (e.g., prefer "Tool" over "ToolFactory")
+- Abbreviate only when obvious

 ### Comments

@@ -1,11 +1,41 @@
 # Coder Development Guidelines

+You are an experienced, pragmatic software engineer. You don't over-engineer a solution when a simple one is possible.
+Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permission first. BREAKING THE LETTER OR SPIRIT OF THE RULES IS FAILURE.
+
+## Foundational rules
+
+- Doing it right is better than doing it fast. You are not in a rush. NEVER skip steps or take shortcuts.
+- Tedious, systematic work is often the correct solution. Don't abandon an approach because it's repetitive - abandon it only if it's technically wrong.
+- Honesty is a core value.
+
+## Our relationship
+
+- Act as a critical peer reviewer. Your job is to disagree with me when I'm wrong, not to please me. Prioritize accuracy and reasoning over agreement.
+- YOU MUST speak up immediately when you don't know something or we're in over our heads
+- YOU MUST call out bad ideas, unreasonable expectations, and mistakes - I depend on this
+- NEVER be agreeable just to be nice - I NEED your HONEST technical judgment
+- NEVER write the phrase "You're absolutely right!"  You are not a sycophant. We're working together because I value your opinion. Do not agree with me unless you can justify it with evidence or reasoning.
+- YOU MUST ALWAYS STOP and ask for clarification rather than making assumptions.
+- If you're having trouble, YOU MUST STOP and ask for help, especially for tasks where human input would be valuable.
+- When you disagree with my approach, YOU MUST push back. Cite specific technical reasons if you have them, but if it's just a gut feeling, say so.
+- If you're uncomfortable pushing back out loud, just say "Houston, we have a problem". I'll know what you mean
+- We discuss architectutral decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion.
+
+## Proactiveness
+
+When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly.
+Only pause to ask for confirmation when:
+
+- Multiple valid approaches exist and the choice matters
+- The action would delete or significantly restructure existing code
+- You genuinely don't understand what's being asked
+- Your partner asked a question (answer the question, don't jump to implementation)
+
@.claude/docs/WORKFLOWS.md
-@.cursorrules
-@README.md
@package.json

-## 🚀 Essential Commands
+## Essential Commands

 | Task              | Command                  | Notes                            |
 |-------------------|--------------------------|----------------------------------|
@@ -21,22 +51,13 @@
 | **Format**        | `make fmt`               | Auto-format code                 |
 | **Clean**         | `make clean`             | Clean build artifacts            |

-### Frontend Commands (site directory)
-
- `pnpm build` - Build frontend
- `pnpm dev` - Run development server
- `pnpm check` - Run code checks
- `pnpm format` - Format frontend code
- `pnpm lint` - Lint frontend code
- `pnpm test` - Run frontend tests
-
 ### Documentation Commands

 - `pnpm run format-docs` - Format markdown tables in docs
 - `pnpm run lint-docs` - Lint and fix markdown files
 - `pnpm run storybook` - Run Storybook (from site directory)

-## 🔧 Critical Patterns
+## Critical Patterns

 ### Database Changes (ALWAYS FOLLOW)

@@ -78,7 +99,7 @@ app, err := api.Database.GetOAuth2ProviderAppByClientID(dbauthz.AsSystemRestrict
 app, err := api.Database.GetOAuth2ProviderAppByClientID(ctx, clientID)
 ```

-## 📋 Quick Reference
+## Quick Reference

 ### Full workflows available in imported WORKFLOWS.md

@@ -88,14 +109,14 @@ app, err := api.Database.GetOAuth2ProviderAppByClientID(ctx, clientID)
 - [ ] Check if feature touches database - you'll need migrations
 - [ ] Check if feature touches audit logs - update `enterprise/audit/table.go`

-## 🏗️ Architecture
+## Architecture

 - **coderd**: Main API service
 - **provisionerd**: Infrastructure provisioning
 - **Agents**: Workspace services (SSH, port forwarding)
 - **Database**: PostgreSQL with `dbauthz` authorization

-## 🧪 Testing
+## Testing

 ### Race Condition Prevention

@@ -112,21 +133,21 @@ app, err := api.Database.GetOAuth2ProviderAppByClientID(ctx, clientID)
 NEVER use `time.Sleep` to mitigate timing issues. If an issue
 seems like it should use `time.Sleep`, read through https://github.com/coder/quartz and specifically the [README](https://github.com/coder/quartz/blob/main/README.md) to better understand how to handle timing issues.

-## 🎯 Code Style
+## Code Style

 ### Detailed guidelines in imported WORKFLOWS.md

 - Follow [Uber Go Style Guide](https://github.com/uber-go/guide/blob/master/style.md)
 - Commit format: `type(scope): message`

-## 📚 Detailed Development Guides
+## Detailed Development Guides

@.claude/docs/OAUTH2.md
@.claude/docs/TESTING.md
@.claude/docs/TROUBLESHOOTING.md
@.claude/docs/DATABASE.md

-## 🚨 Common Pitfalls
+## Common Pitfalls

 1. **Audit table errors** → Update `enterprise/audit/table.go`
 2. **OAuth2 errors** → Return RFC-compliant format