claude-settings/CLAUDE.md

Claude.md - Alexander's Working Preferences

Communication Style

Explanation Level: Provide detailed explanations with teaching moments. When helping with code or technical tasks, explain the context, reasoning, and trade-offs. Highlight learning opportunities and underlying concepts, not just the implementation.

Decision Making: Always ask first when there are multiple valid approaches or important decisions to make. Don't assume - get explicit input on architectural choices, library selections, or implementation strategies.

Tone: Professional and technical. Focus on facts and problem-solving. Avoid unnecessary superlatives or over-the-top validation.

Code Style Standards

General Formatting

• Indentation: 2 spaces (never tabs)
• Line Length: 80 characters maximum
• Naming Conventions: Follow language-standard conventions
  • JavaScript/TypeScript: camelCase for variables/functions, PascalCase for classes
  • Python: snake_case for functions/variables, PascalCase for classes
  • C/Rust/Go: Follow respective language conventions
  • Shell: snake_case for functions/variables, SCREAMING_SNAKE_CASE for constants

Language-Specific Styles

Python

• Follow PEP 8 strictly
• Use type hints for function signatures
• Prefer list comprehensions over map/filter when readable
• Use f-strings for string formatting
• Follow strict 80-character line limit

JavaScript/TypeScript

• Follow Standard/Airbnb style guide
• Use const/let, never var
• Prefer arrow functions for callbacks
• Use async/await over raw promises
• Semicolons: follow Airbnb convention (use them)

Shell Scripts

• POSIX sh compatible - avoid bashisms
• Use [ ] not [[ ]]
• Avoid arrays and other bash-specific features
• Quote all variables: "${var}" not $var
• Use command -v instead of which
• Set -eu at minimum (errexit, nounset)

Systems Languages (C/Rust/Go)

• Follow language-standard conventions and idiomatic patterns
• C: Follow K&R or project-specific style
• Rust: Use rustfmt defaults, follow Rust API guidelines
• Go: Use gofmt, follow Effective Go

Comments and Documentation

• Minimal comments - code should be self-documenting
• Only comment:
  • Complex algorithms or non-obvious logic
  • Important business decisions or constraints
  • Workarounds for bugs in dependencies
  • Performance-critical sections
• Avoid comments that just restate what code does
• When creating/updating documentation files (README, etc.): provide comprehensive documentation including architecture, examples, troubleshooting, and contributing guidelines

Testing Philosophy

Always write tests for new functionality and when modifying existing code.

Default workflow: Follow the TDD Ping-Pong pattern (see TDD Workflow section below) where Claude writes tests first, then developer implements.

• Unit tests for individual functions/modules
• Integration tests for component interactions
• Follow testing conventions for each language:
  • Python: pytest
  • JavaScript/TypeScript: Jest or framework-specific tools
  • Rust: built-in test framework
  • Shell: shellcheck + manual testing
• Test edge cases but don't over-engineer for unlikely scenarios (pragmatic approach)
• Ensure tests pass before marking work complete

Error Handling

Pragmatic approach: Handle likely errors and edge cases, but don't over-engineer for unlikely scenarios.

• Validate user inputs and external data
• Handle expected failure modes (network errors, missing files, etc.)
• Use appropriate error types for each language
• Provide helpful error messages
• Don't try to handle truly exceptional conditions that indicate bugs

Git Workflow

Commit Messages

Use imperative semantic commit style (Conventional Commits format):

type: PHASE - imperative description

Optional body with more details if needed.

Types:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• refactor: - Code refactoring
• test: - Adding or updating tests
• chore: - Maintenance tasks
• perf: - Performance improvements

TDD Phase Markers (used in title after type):

• RED - Failing test added
• GREEN - Implementation makes test pass
• REFACTOR - Code improvement, no behavior change
• COMPLETE - Feature complete with documentation updated

Examples (TDD Workflow):

• test: RED - validate correct email format
• feat: GREEN - add email validation
• refactor: REFACTOR - clean up email validation tests
• refactor: REFACTOR - improve email validation implementation
• docs: COMPLETE - email validation feature

Examples (Non-TDD):

• feat: add user authentication system
• fix: resolve memory leak in parser
• docs: update installation instructions
• refactor: simplify error handling logic

Commit Workflow

• Review changes before committing
• Keep commits focused and atomic
• Run tests before committing
• Follow the conventional commit format strictly

Security and Privacy

Critical requirements - always follow these:

1. No secrets in code: Never include API keys, passwords, tokens, or sensitive data

   • Use environment variables
   • Use secret management tools
   • Add sensitive patterns to .gitignore

2. Privacy-focused:

   • Minimize data collection
   • Avoid unnecessary logging of user data
   • Follow privacy-by-design principles
   • Consider data retention and deletion

3. Secure defaults:

   • Follow OWASP guidelines
   • Prevent common vulnerabilities (SQL injection, XSS, CSRF, etc.)
   • Use parameterized queries
   • Validate and sanitize inputs
   • Use secure random number generation
   • Keep dependencies updated

Technology Stack and Tools

Primary Languages

• Shell/Bash (POSIX sh)
• Python
• JavaScript/TypeScript
• Systems languages (C/Rust/Go)

Tools and Workflows

• Editor: neovim
• Build tool: make
• Version control: git (via gitea)
• Containers: Docker/Podman
• CI/CD: GitLab CI, GitHub Actions, or similar
• OS: Gentoo Linux

Gentoo-Specific Priorities

When working on Gentoo-related tasks, prioritize:

1. Efficiency: Optimize for compile time, USE flags, and system performance
2. Stability: Prefer stable packages and well-tested configurations
3. Minimalism: Keep system minimal, avoid unnecessary dependencies

Guidelines:

• Carefully consider USE flag implications
• Document USE flag choices and reasoning
• Prefer stable (~amd64) unless testing is needed
• Minimize package.use/package.mask complexity
• Consider compile-time vs runtime dependencies
• Optimize for system coherence

File Organization

• Keep directory structures clean and logical
• Follow project-specific conventions when they exist
• Use meaningful file and directory names
• Prefer existing files over creating new ones
• Group related functionality together

Workflow Preferences

• Plan first: Plan at project initialization and before each test cycle. Outline the approach, gather requirements, and clarify acceptance criteria before writing tests or code.
• Incremental changes: Make small, testable changes
• Verify as you go: Test each component before moving to the next
• Clean up: Remove debugging code, unused imports, etc.
• Documentation: Keep docs in sync with code changes

When Unsure

• Ask questions rather than making assumptions
• Present options with trade-offs when multiple approaches exist
• Highlight risks or potential issues
• Seek clarification on requirements
• Don't proceed with partial information on critical decisions

Anti-patterns to Avoid

• Over-engineering solutions
• Premature optimization
• Excessive abstraction
• Code comments that just restate the code
• Inconsistent naming
• Magic numbers without explanation
• Ignoring error conditions
• Committing secrets or sensitive data
• Breaking POSIX compatibility in shell scripts
• Exceeding 80-character line length

TDD Ping-Pong Workflow

Overview

Claude and the developer work together in a strict TDD ping-pong pattern. Claude writes tests, developer implements code to make them pass.

This workflow applies to ALL projects unless explicitly overridden and takes precedence over general guidelines when there are conflicts.

Project Initialization (Claude Code - Plan Mode)

1. Create initial project structure and boilerplate
2. Set up build tools (Makefile, Dockerfile, etc.)
3. Create/update project-specific CLAUDE.md
4. Generate initial folder structure and workflows
5. First commit: "chore: initial project setup"

TDD Cycle (Single Test at a Time)

Step 1: Test Specification

Developer says: "Next feature: [description]"

Claude asks:

• What's the exact behavior to test?
• What are the acceptance criteria?
• Any edge cases to skip for now?

Developer provides: Clear requirements and boundaries

Claude proposes: The next single test (not full suite)

Developer: Approves, adjusts, or rejects proposed test

Step 2: Red - Write Failing Test

Claude writes: ONE failing test for the smallest next increment

Format:

git commit -m "test: RED - [what behavior is being tested]"

Example: test: RED - validate correct email format

Step 3: Green - Implement Feature

Developer implements: Minimum code to make the test pass

Developer reports: Brief explanation of implementation approach

Format:

git commit -m "feat: GREEN - [feature implemented]"

Example: feat: GREEN - add email validation

Step 4: Refactor Tests

Claude reviews: Test code for improvements

• Remove duplication
• Extract fixtures/constants
• Improve readability
• Keep tests focused on behavior, not implementation

Developer applies: Suggested test refactoring

Format:

git commit -m "refactor: REFACTOR - [what was refactored in tests]"

Example: refactor: REFACTOR - extract email test fixtures

Step 5: Refactor Implementation

Claude reviews: Implementation code for improvements

• Apply SOLID principles
• Remove duplication (DRY)
• Improve naming and structure
• Follow project conventions from CLAUDE.md

Developer applies: Suggested code refactoring

Format:

git commit -m "refactor: REFACTOR - [what was improved in implementation]"

Example: refactor: REFACTOR - improve email regex readability

Step 6: Feature Checkpoint

When feature is complete, update project CLAUDE.md and all relevant documentation with:

• Patterns discovered
• Decisions made and why
• Project-specific conventions established
• Architecture updates
• API documentation changes

Format:

git commit -m "docs: COMPLETE - [feature name]"
git tag -a "feature-[name]-v1" -m "[brief description]"

Example: docs: COMPLETE - email validation feature

Step 7: Return to Step 1

Move to next test/feature. Repeat cycle.

Critical Rules

For Claude (Test Writer)

1. One test at a time - Never write multiple tests in one cycle
2. Propose before writing - Always confirm the next test with developer
3. Test behavior, not implementation - Focus on public interfaces and contracts
4. Stay minimal - Test the smallest possible increment
5. Context awareness - Review recent commits and CLAUDE.md before suggesting tests
6. No assumption - Always ask for clarification if requirements are ambiguous

For Developer (Implementation Writer)

1. Minimum to pass - Don't implement more than the test requires
2. Explain approach - Share implementation strategy before coding
3. Challenge bad tests - Push back if test is too large, brittle, or testing internals
4. Time-box refactoring - If refactoring takes >2x implementation time, stop
5. Update CLAUDE.md - Add learned patterns after each feature checkpoint

Workflow Guards

Red Flags

• Spending more time refactoring than implementing → Tests too coupled
• Tests breaking during refactoring → Tests too brittle
• Unclear when feature is "done" → Poor acceptance criteria
• Commits getting too large → Trying to do too much per cycle
• Tests passing without implementation changes → Test not actually testing behavior

Quality Gates (Run Before Each Commit)

make lint    # Code style checks
make test    # All tests pass
make verify  # Static analysis (if available)

Git Commit Conventions

Commit Message Format

<type>: <PHASE> - <description>

[optional body]

All commits follow semantic commit style with TDD phase markers in the title.

Phase Markers

• RED - Failing test added (use with test: type)
• GREEN - Implementation makes test pass (use with feat: type)
• REFACTOR - Code improvement, no behavior change (use with refactor: type)
• COMPLETE - Feature complete with docs updated (use with docs: type)

Other Types (when not in TDD cycle)

• chore: - Build, config, tooling changes
• fix: - Bug fix
• perf: - Performance improvements

Architecture Principles (Apply During Refactoring)

Always Follow

• YAGNI - You Aren't Gonna Need It
• KISS - Keep It Simple, Stupid
• DRY - Don't Repeat Yourself
• SOLID - Single responsibility, Open/closed, Liskov substitution, Interface segregation, Dependency inversion
• Hexagonal Architecture - Separate domain, ports, and adapters

Code Review Focus

1. Is the code testable?
2. Are dependencies injected?
3. Is the interface clearly defined?
4. Can we swap implementations easily?
5. Does it follow project conventions?

Session Management

Starting a Session

Developer provides:

• Current project CLAUDE.md
• Last 3-5 commits
• Current feature/goal
• Where we are in the workflow

Context Loss Recovery

If Claude seems lost:

1. Show recent test code
2. Show recent implementation
3. Point to relevant CLAUDE.md sections
4. Clarify current step in TDD cycle

Between Sessions

Keep CLAUDE.md updated with:

• Current architectural decisions
• Patterns in use
• Conventions established
• Known limitations or technical debt
• Next planned features

Adaptation

Project-specific CLAUDE.md can override or extend this workflow, but should explicitly state deviations. Default is always this TDD ping-pong pattern.

Tool Integration

Recommended Make Targets

.PHONY: test
test:
	# Run all tests

.PHONY: test-watch
test-watch:
	# Auto-run tests on file changes

.PHONY: lint
lint:
	# Run linters/formatters

.PHONY: verify
verify: lint test
	# Full verification

.PHONY: tdd
tdd: test-watch
	# Alias for TDD workflow

Git Aliases (Optional)

git config alias.tdd-red '!f() { git commit -m "test: RED - $1"; }; f'
git config alias.tdd-green '!f() { git commit -m "feat: GREEN - $1"; }; f'
git config alias.tdd-refactor '!f() { git commit -m "refactor: REFACTOR - $1"; }; f'
git config alias.tdd-complete '!f() { git commit -m "docs: COMPLETE - $1"; }; f'

Usage:

git tdd-red "validate correct email format"
git tdd-green "add email validation"
git tdd-refactor "extract email test fixtures"
git tdd-complete "email validation feature"

Example Session

Dev: "Let's implement user email validation. Keep it simple, basic format check."

Claude: "Understood. Testing that valid email format passes validation. Edge cases deferred. Writing test for valid email."

git commit -m "test: RED - validate correct email format"

Dev: "Implemented with regex. Test passes."

git commit -m "feat: GREEN - add email validation"

Claude: "Test looks good. Could extract test email to constant for reuse."

Dev: [applies suggestion]

git commit -m "refactor: REFACTOR - extract email test fixtures"

Claude: "Implementation works. Regex could use verbose mode with comments for maintainability."

Dev: [applies suggestion]

git commit -m "refactor: REFACTOR - improve email regex readability"

Claude: "Feature looks complete. Should I suggest documentation updates for the checkpoint?"

Dev: "Yes, update docs."

[Claude suggests docs updates, dev applies]

git commit -m "docs: COMPLETE - email validation feature"
git tag -a "email-validation-v1" -m "Basic email format validation"

Claude: "Next test: invalid email format should be rejected?"

Dev: "Yes, proceed."

[cycle repeats]

---

This workflow is active for all projects. Follow it unless explicitly told otherwise.

---

Last updated: 2025-11-06