Skip to content

add claude.md file #92

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

add claude.md file #92

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
348 changes: 348 additions & 0 deletions claude.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,348 @@
# Development Guidelines

## Philosophy

### Core Beliefs

- **Incremental progress over big bangs** - Small changes that compile and pass tests
- **Learning from existing code** - Study and plan before implementing
- **Pragmatic over dogmatic** - Adapt to project reality
- **Clear intent over clever code** - Be boring and obvious

### Simplicity Means

- Single responsibility per function/class
- Avoid premature abstractions
- No clever tricks - choose the boring solution
- If you need to explain it, it's too complex

## Backwards compatibility

- If code was added in the current branch, it's not legacy code. Only code in the main (or master) branch is legacy code.
- If you need to change a method that's not legacy, you can change it instead of adding a new method and trying to maintain backwards compatibility.

## Agent Orchestration Framework

### When to Use Which Agent

- **Complex Features (>3 stages or unclear requirements)**: Start with `implementation-planner`
- **Test-First Development**: Use `unit-test-writer` before implementation
- **Debugging Issues**: Use `bug-root-cause-analyzer` after 2 failed attempts
- **Code Quality Checks**: Use `code-reviewer` before commits
- **Complex Discoveries**: Use `note-taker` for non-obvious insights gained through exploration
- **AI Prompt Issues**: Use `prompt-optimizer` for agent improvements
- **Task Planning**: Use `task-orchestrator` to determine optimal agent workflow

### Workflow Integration Patterns

#### Pattern 1: New Feature Development

1. **Task Assessment** → `task-orchestrator` determines if `implementation-planner` needed
2. **Planning** → `implementation-planner` creates staged plan (if complex)
3. **Test Design** → `unit-test-writer` writes tests for current stage
4. **Implementation** → Write minimal code to pass tests
5. **Quality Check** → `code-reviewer` reviews before commit
6. **Documentation** → `note-taker` documents complex discoveries
7. Repeat steps 3-6 for each stage

#### Pattern 2: Bug Investigation

1. **Initial Debugging** → Try fixing yourself (max 2 attempts)
2. **Systematic Analysis** → `bug-root-cause-analyzer` investigates
3. **Fix Implementation** → Implement the identified solution
4. **Regression Prevention** → `unit-test-writer` adds tests to prevent recurrence
5. **Quality Check** → `code-reviewer` reviews fix and tests
6. **Knowledge Capture** → `note-taker` documents root cause if complex

#### Pattern 3: Code Quality Improvement

1. **Review** → `code-reviewer` identifies improvement opportunities
2. **Test Safety Net** → `unit-test-writer` ensures comprehensive test coverage
3. **Refactor** → Make improvements with tests passing
4. **Final Review** → `code-reviewer` validates improvements

## Process

### 1. Planning & Staging

When approaching a new repository, first read the README.md file in the root of the repository and any other markdown files that describe the project.

For complex tasks, the `implementation-planner` agent creates durable, structured plans following the template and process defined in the `implementation-planner` agent documentation.

### 2. Implementation Flow

1. **Understand** - Study existing patterns in codebase
2. **Test** - Use the `unit-test-writer` agent to write tests first (red)
3. **Implement** - Minimal code to pass (green)
4. **Refactor** - Clean up with tests passing
5. **Commit** - With clear message linking to plan

### 3. When Stuck (After 2 Attempts)

**CRITICAL**: Maximum 2 attempts per issue, then use `bug-root-cause-analyzer` agent.

The agent will systematically:

1. **Document what failed** - What you tried, error messages, suspected causes
2. **Research alternatives** - Find similar implementations and approaches
3. **Question fundamentals** - Evaluate abstraction level and problem breakdown
4. **Systematic investigation** - Use proven debugging methodologies

## Technical Standards

### Architecture Principles

- **Composition over inheritance** - Use dependency injection
- **Interfaces over singletons** - Enable testing and flexibility
- **Explicit over implicit** - Clear data flow and dependencies
- **Test-driven when possible** - Never disable tests, fix them

### Code Quality

- **Every commit must**:
- Compile successfully
- Pass all existing tests
- Include tests for new functionality
- Follow project formatting/linting

- **Before committing**:
- Run formatters/linters
- In a Rust codebase, run `cargo fmt`, `cargo clippy --all-targets --all-features -- -D warnings`, and `cargo shear` to check for issues.
- If bin/fmt exists, run it.
- Otherwise, run the formatter for the language.
- Use `code-reviewer` agent for quality check
- Ensure commit message explains "why"

### Error Handling

- Fail fast with descriptive messages
- Include context for debugging
- Handle errors at appropriate level
- Never silently swallow exceptions

## Decision Framework

For implementation decisions, refer to the decision framework in the `implementation-planner` agent documentation. Key factors include testability, maintainability, consistency, simplicity, and reversibility.

## Documentation Framework

### Project Planning

- **Location**: `~/dev/ai/plans/{org}/{repo}/{issue-or-pr-or-branch-name-or-plan-slug}.md`
- **Purpose**: Durable implementation plans for complex features
- **Owner**: `implementation-planner` agent
- **Lifecycle**: Permanent reference for architecture decisions and implementation history

### Knowledge Capture

- **Location**: `~/dev/ai/notes/`
- **Purpose**: Permanent knowledge about complex discoveries
- **Owner**: `note-taker` agent
- **Trigger**: Non-obvious behaviors, complex debugging insights

### Code Documentation

- **Location**: In-code comments and README updates
- **Purpose**: Explain WHY decisions were made
- **Owner**: Developer (guided by `code-reviewer`)

## Project Integration

### Learning the Codebase

- Find 3 similar features/components
- Identify common patterns and conventions
- Use same libraries/utilities when possible
- Follow existing test patterns

### Tooling

- Use project's existing build system
- Use project's test framework
- Use project's formatter/linter settings
- Don't introduce new tools without strong justification

## Quality Gates

### Definition of Done

- [ ] Tests written and passing and are not redundant or unnecessary
- [ ] Code is not dead or redundant and minimal to get the job done
- [ ] Code follows project conventions
- [ ] No linter/formatter warnings
- [ ] **All dependencies are used (no cargo-shear warnings in Rust)**
- [ ] **All Cargo features enable real functionality (Rust)**
- [ ] **No tool warnings ignored without strong justification**
- [ ] Commit messages are clear
- [ ] Implementation matches plan
- [ ] No TODOs without issue numbers

### Test Guidelines

- Test behavior, not implementation
- One assertion per test when possible
- Clear test names describing scenario
- Use existing test utilities/helpers
- Tests should be deterministic

## Important Reminders

**NEVER**:

- Use `--no-verify` to bypass commit hooks
- Disable tests instead of fixing them
- Commit code that doesn't compile
- Make assumptions - verify with existing code

**ALWAYS**:

- Commit working code incrementally
- Update implementation plan status as you progress through stages
- Learn from existing implementations
- Stop after 2 failed attempts and use `bug-root-cause-analyzer` agent
- Use the `code-reviewer` agent to review code before committing

## Project-specific Workflow

### posthog/posthog

When working on the https://github.com/PostHog/posthog repository, use the following workflow:

- Read the README.md file in the root of the repository and the https://github.com/PostHog/posthog/blob/master/docs/FLOX_MULTI_INSTANCE_WORKFLOW.md file.
- When taking on a new task, prompt the user whether they want to create a new git worktree using the `phw` command for the task.
- When completing a task, automatically run these checks and fix any issues:
- `mypy --version && mypy -p posthog | mypy-baseline filter || (echo "run 'pnpm run mypy-baseline-sync' to update the baseline" && exit 1)`

When working on other repositories, use the following workflow:

- When taking on a new task, prompt to create a new branch and associated worktree.
- Default: branch off the main branch (e.g. `main` or `master` depending on the repo), named `dmarticus/<slug>` or `dmarticus/<issue#>-<slug>` if the issue number is known.
- Place the worktree in `~/dev/worktrees/<repo-name>/<branch-name>`.
- Example: `git worktree add ~/dev/worktrees/my-project/feature-new-feature`
- This keeps worktrees organized by project and outside all repositories.
- When working on an existing branch or pull request, prompt to create a new worktree for the branch.
- Never nest worktrees or place them within the main repo.
- Never use two worktrees on the same branch simultaneously.
- When done with the task:
- Prompt to commit changes.
- Use `git worktree remove <path>` to clean up safely.
- Occasionally audit worktrees with `git worktree list` and `git worktree prune`.
- Run `bin/fmt` to format the code if available.
- If `bin/fmt` changes files we did not change as part of the task, revert those changes.

## PostHog Specifics

PostHog has a lot of client SDKs. Sometimes it's useful to distinguish between the ones that run on the client and the ones that run on the server.

### Client-side SDKs

| Repository | Local Path | GitHub URL |
| ---------------------- | ------------------------------- | ------------------------------------------ |
| posthog-js, posthog-rn | `~/dev/posthog/posthog-js` | https://github.com/PostHog/posthog-js |
| posthog-ios | `~/dev/posthog/posthog-ios` | https://github.com/PostHog/posthog-ios |
| posthog-android | `~/dev/posthog/posthog-android` | https://github.com/PostHog/posthog-android |
| posthog-flutter | `~/dev/posthog/posthog-flutter` | https://github.com/PostHog/posthog-flutter |

### Server-side SDKs

| Repository | Local Path | GitHub URL |
| -------------- | ------------------------------ | ----------------------------------------- |
| posthog-python | `~/dev/posthog/posthog-python` | https://github.com/PostHog/posthog-python |
| posthog-node | `~/dev/posthog/posthog-js` | https://github.com/PostHog/posthog-node |
| posthog-php | `~/dev/posthog/posthog-php` | https://github.com/PostHog/posthog-php |
| posthog-ruby | `~/dev/posthog/posthog-ruby` | https://github.com/PostHog/posthog-ruby |
| posthog-go | `~/dev/posthog/posthog-go` | https://github.com/PostHog/posthog-go |
| posthog-dotnet | `~/dev/posthog/posthog-dotnet` | https://github.com/PostHog/posthog-dotnet |
| posthog-elixir | `~/dev/posthog/posthog-elixir` | https://github.com/PostHog/posthog-elixir |

## Git

- Name branches `dmarticus/<slug>` where slug is a short description of the task.
- Keep commits clean:
- Use interactive staging (git add -p) and thoughtful commit messages.
- Squash when appropriate. Avoid "WIP" commits unless you're spiking.
- Don't add yourself as a contributor to commits.

### Commit messages

- Present tense: "Fix bug", not "Fixed bug"
- Use imperatives: "Add", "Update", "Remove"
- One line summary, blank line, optional body if needed
- Keep commit messages short and concise.
- Write clean commit messages without any AI attribution markers.
- When a commit fixes a bug, include the bug number in the commit message on its own line like: "Fixes #123" where 123 is the GitHub issue number.

## File System

- All project-local scratch notes, REPL logs, etc., go in a .notes/ or notes/ folder — don't litter the root.

## Coding

- When writing code, think like a principal engineer.
- Focus on code correctness and maintainability.
- Bias for simplicity: Prefer boring, maintainable solutions over clever ones.
- Make sure the code is idiomatic and readable.
- Write tests for changes and new code.
- Look for existing methods and libraries when writing code that seems like it might be common.
- Progress over polish: Make it work → make it right → make it fast.

- Before commiting, always run a code formatter when available:
- If there's a bin/fmt script, run it.
- In a Rust codebase, run `cargo fmt`, `cargo clippy`, and `cargo shear` to check for issues.
- Otherwise, run the formatter for the language.

### Rust-Specific Guidelines

#### Dependency Management

- **Golden Rule**: If `cargo shear` wants to remove a dependency, either use it properly or remove it
- **Red Flag**: Any `cargo shear` ignore should trigger investigation - unused deps indicate design problems
- **Cargo Features**: Verify Cargo features actually enable code that exists and is used
- **Before adding ignores**: Always investigate why the dependency appears unused and ensure it's actually needed

#### Quality Checklist for Rust

1. Run `cargo fmt` - fix any formatting issues
2. Run `cargo clippy --all-targets --all-features -- -D warnings` - fix all warnings
3. **Run `cargo shear` - investigate any warnings before adding ignores**
4. **Verify new Cargo features enable real functionality**
5. **Check that new dependencies are actually imported/used in code**

- When writing human friendly messages, don't use three dots (...) for an ellipsis, use an actual ellipsis (…).

### Bash Scripts

- Don't add custom logging methods to bash scripts, use the standard `echo` command.
- For cases where it's important to have warnings and errors, copy the helpers in https://github.com/PostHog/template/tree/main/bin/helpers and source them in the script like https://github.com/PostHog/template/blob/main/bin/fmt does.

### Markdown Files

- When editing markdown files (.md, .markdown), always run markdownlint after making changes:
- Run: `markdownlint <filename>`
- Fix any errors or warnings before marking the task complete
- Common fixes: proper heading hierarchy, consistent list markers, trailing spaces
- Follow markdown best practices:
- Use consistent heading levels (don't skip from h1 to h3)
- Add blank lines around headings and code blocks
- Use consistent list markers (either all `-` or all `*`)
- Remove trailing whitespace
- **Never add hard line breaks or wrap lines** when editing markdown files. Preserve existing line structure and let editors handle soft wrapping.

### Testing & Quality

- Always run tests before marking a task as complete.
- If tests fail, fix them before proceeding.
- When adding new functionality, write tests for it.
- Check for edge cases, error handling, and performance implications.
- Update relevant documentation when changing functionality.

### Dependency Philosophy

- Avoid introducing new deps for one-liners
- Prefer battle-tested libraries over trendy ones
- If adding a dep, write down the rationale
- If removing one, document what replaces it

## Test Instructions

- When the user says "cuckoo", respond with "🐦 BEEP BEEP! Your CLAUDE.md file is working correctly!"
Loading