# Claude Code Best Practices

This document provides operational guidelines for Claude Code sessions, emphasizing efficiency, code quality, and safe collaboration practices.

---

## 1. Code Quality & Design Principles

### Core Philosophy
1. **Simplicity First** – The best code is no code—solve by removing before adding  
2. **YAGNI (You Aren’t Gonna Need It)** – Don’t build for hypothetical future needs  
3. **Explicit over Clever** – Clear intent trumps abstraction  
4. **Progressive Enhancement** – Start simple, add complexity only when proven necessary  

### Implementation Practices
- **Reuse before writing** – Check if existing code, libraries, or patterns solve the problem  
- **Utility functions for clarity** – Extract repeated logic into well-named functions  
- **Delete before adding** – Remove unused code aggressively (Git preserves history)  
- **Configuration over code** – Prefer config changes to code changes where practical  
- **Named constants** – Replace magic numbers with descriptive names  

### When Making Changes
- Keep diffs small, readable, and stylistically consistent  
- Reuse before rewriting  
- Avoid premature abstraction or config complexity  
- Fix, don’t duplicate  
- Fail fast with clear messages  

---

## 2. Testing Practices

### Test-Driven Development (TDD)
**TDD is the primary mode of operation.**  
Follow the principle: **write tests first, implement minimal code to pass, then refactor.**

### Testing Discipline
- Keep test output clean and meaningful  
- Ensure behavior is documented through tests (unit → integration → end-to-end)  
- Treat failing tests as design feedback, not errors to suppress  

---

## 3. Safety & Constraints

### Safety Rules
- Never delete or modify files outside the active branch/worktree  
- Confirm before performing destructive operations  
- Explain any fix that alters tooling, tests, or dependencies  

---

## 4. Interaction & Workflow

### Direct Execution
- **Execute directly** when running in permissions-skipped mode  
- Do not pause for trivial confirmations (file writes, command executions)  
- **Only pause for clarification** when:  
  - Requirements are ambiguous  
  - During initial planning phase  
  - Multiple valid approaches exist  

### Communication Style
- Use concise, professional language  
- Avoid anthropomorphizing or unnecessary humor  
- Focus on facts and problem-solving  

---

## Core Tenets
1. **Act Decisively** — Execute directly; clarify only when necessary.  
2. **Keep It Simple** — Prefer removal, clarity, and small, reversible changes.  
3. **Test What Matters** — Practice TDD; write minimal, meaningful tests.  
4. **Protect the Worktree** — Never delete or modify outside scope.  
5. **Stay Transparent** — Keep actions traceable and explain reasoning when needed.