Skip to content

Instantly share code, notes, and snippets.

@coderberry

coderberry/.claude__01-non-negotiable.md

Last active June 17, 2025 17:02
Show Gist options
  • Save coderberry/f2f03ad4c9cc582af5e30849fa080db7 to your computer and use it in GitHub Desktop.
Save coderberry/f2f03ad4c9cc582af5e30849fa080db7 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
.claude__01-non-negotiable.md

About me

My name is Eric. I am an expert programmer, and your first resource to use when you do not know something or do not know where to look for something.

NON NEGOTIABLE RULES THAT YOU MUST FOLLOW

  • USE gh CLI TO INTERACT WITH GITHUB.
  • NEVER COMMIT, PUSH, WRITE CODE OR ISSUES OR PRS UNLESS I TELL YOU TO.
Raw
.claude__02-generating-code.md

Generating Code

Use list_generators to list available generators when available, otherwise mix help. If you have to run generator tasks, pass --yes. Always prefer to use generators as a basis for code generation, and then modify afterwards.

Tools

Use tidewave MCP tools when available, as they let you interrogate the running application in various useful ways.

Logs & Tests

When you're done executing code, try to compile the code, and check the logs or run any applicable tests to see what effect your changes have had.

Use Eval

Use the project_eval tool to execute code in the running instance of the application. Eval h Module.fun to get documentation for a module or function.

Ash First

Always use Ash concepts, almost never ecto concepts directly. Think hard about the "Ash way" to do things. If you don't know, often look for information in the rules & docs of Ash & associated packages.

Code Generation

Start with generators wherever possible. They provide a starting point for your code and can be modified if needed.

ALWAYS research, NEVER assume

Always use package_docs_search to find relevant documentation before beginning work.

Don't start or stop phoenix applications

Never attempt to start or stop a phoenix application. Your tidewave tools work by being connected to the running application, and starting or stopping it can cause issues.

Raw
.claude__03-feature-workflow.md

FEATURE IMPLEMENTATION WORKFLOW

THIS IS A MANDATORY WORKFLOW - NO STEPS CAN BE SKIPPED

PHASE 1: RESEARCH & PLANNING (MANDATORY)

Step 1.1: Initial Research

YOU MUST USE ALL AVAILABLE RESOURCES:

  • Check existing usage rules via get_usage_rules MCP tool or CLAUDE.md links
  • Use package_docs_search for ALL potentially relevant packages
  • Read the full documentation found
  • Search for similar features in the codebase using grep/glob
  • Check for existing patterns to follow
  • Use project_eval to explore modules if available
  • Review any applicable existing usage rules for packages you'll be working with

Step 1.2: Requirements Analysis

REQUIRED ACTIONS:

  1. List ALL requirements explicitly
  2. Identify edge cases and limitations
  3. Check for security implications
  4. Verify compatibility with Ash patterns
  5. Document assumptions that need validation

Step 1.3: Create Feature Plan Document

CREATE FILE: <project_root>/notes/features/<number>-<name>.md (inside the project directory)

MANDATORY STRUCTURE:

# Feature: <Feature Name>

## Summary

[1-2 sentences describing the feature]

## Requirements

- [ ] Requirement 1 (specific and measurable)
- [ ] Requirement 2
- [ ] etc.

## Research Summary

### Existing Usage Rules Checked

- Package X existing usage rules: [key rules that apply]
- Package Y existing usage rules: [key rules that apply]

### Documentation Reviewed

- Package X: [what you found]
- Package Y: [what you found]

### Existing Patterns Found

- Pattern 1: [file:line] description
- Pattern 2: [file:line] description

### Technical Approach

[Detailed explanation of HOW you will implement this]

## Risks & Mitigations

| Risk   | Impact       | Mitigation    |
| ------ | ------------ | ------------- |
| Risk 1 | High/Med/Low | How to handle |

## Implementation Checklist

- [ ] Task 1 (specific file/module to create/modify)
- [ ] Task 2
- [ ] Test implementation
- [ ] Verify no regressions

## Questions for Eric

1. [Any clarifications needed]

PHASE 2: APPROVAL CHECKPOINT (MANDATORY)

YOU MUST STOP HERE:

  1. Present the plan document
  2. Explicitly ask: "Please review this plan. Should I proceed with implementation?"
  3. WAIT for explicit approval
  4. Do NOT proceed without approval

PHASE 3: IMPLEMENTATION

Step 3.1: Set Up Tracking

REQUIRED:

  1. Use TodoWrite to create tasks from implementation checklist
  2. Update <project_root>/notes/features/<number>-<name>.md with a ## Log section
  3. Log EVERY significant decision or discovery

Step 3.2: Implementation Rules

MANDATORY SEQUENCE FOR EACH TASK:

  1. Check for relevant generator using list_generators
  2. Run generator with --yes if exists
  3. Research docs again for specific implementation details
  4. Implement using Ash patterns ONLY
  5. Compile and check for errors
  6. Run tests if applicable
  7. Update log with results

Step 3.3: Progress Reporting

AFTER EACH SUBTASK:

  1. Report what was done
  2. Show any errors/warnings
  3. Update todo status
  4. Ask if you should continue

PHASE 4: FINALIZATION

Step 4.1: Verification

REQUIRED CHECKS:

  1. All requirements met (check against original list)
  2. All tests passing
  3. No compilation warnings
  4. Code follows Ash patterns

Step 4.2: Documentation Update

UPDATE <project_root>/notes/features/<number>-<name>.md:

  1. Add ## Final Implementation section
  2. Document what was built
  3. Note any deviations from plan
  4. List any follow-up tasks needed

PHASE 5: COMPLETION CHECKPOINT

FINAL REQUIREMENTS:

  1. Present summary of implementation
  2. Show test results
  3. Ask: "Feature implementation complete. Any additional changes needed?"
  4. WAIT for confirmation before marking complete

REMEMBER

  • NO COMMITS unless explicitly told "commit this"
  • RESEARCH FIRST - always use package_docs_search
  • ASH PATTERNS ONLY - no direct Ecto
  • STOP AT CHECKPOINTS - wait for approval
  • LOG EVERYTHING - maintain feature notes file
Raw
.claude__04-task-workflow.md

GENERAL TASK WORKFLOW

PHASE 1: TASK ANALYSIS (MANDATORY)

Step 1.1: Understand the Request

YOU MUST:

  1. Parse what exactly is being asked
  2. Identify if this is a feature (use feature.md) or fix (use fix.md)
  3. If neither, continue with this workflow
  4. Break down into specific, measurable subtasks
  5. Identify what success looks like

Step 1.2: Research Requirements

REQUIRED RESEARCH - USE ALL AVAILABLE TOOLS:

  • Use package_docs_search for any packages involved
  • Check existing usage rules via get_usage_rules MCP tool or CLAUDE.md links
  • Check existing code patterns with grep/glob
  • Verify Ash-specific requirements
  • Look for similar implementations
  • Review any applicable existing usage rules for packages involved
  • Understand the full context

Step 1.3: Create Task Plan

YOU MUST:

  1. Use TodoWrite to create specific subtasks
  2. Order tasks by dependency
  3. Include verification steps
  4. Add "Ask Eric for confirmation" as final task

EXAMPLE TODO STRUCTURE:

1. Research [specific thing] in docs
2. Check existing [pattern] in codebase
3. Implement [specific change]
4. Test/verify [specific behavior]
5. Ask Eric for confirmation

PHASE 2: EXECUTION

Step 2.1: Follow the Plan

FOR EACH TODO ITEM:

  1. Mark as "in_progress" when starting
  2. Execute the specific task
  3. Verify it worked as expected
  4. Document any issues or discoveries
  5. Mark as "completed" when done
  6. Report status before moving to next

Step 2.2: Implementation Rules

ALWAYS:

  • Check for generators before writing code
  • Use project_eval to test code snippets
  • Follow existing patterns exactly
  • Use Ash concepts, not Ecto
  • Compile after changes
  • Run relevant tests

Step 2.3: Continuous Verification

AFTER EACH CHANGE:

  1. Check compilation status
  2. Look for warnings/errors
  3. Test the specific functionality
  4. Ensure no regressions
  5. Update user on progress

PHASE 3: COMPLETION

Step 3.1: Final Verification

REQUIRED CHECKS:

  • All todos completed
  • Code compiles cleanly
  • Tests pass (if applicable)
  • Functionality works as requested
  • No security issues introduced

Step 3.2: Summary Report

PRESENT TO USER:

Task completed. Here's what was done:
1. [Specific thing 1]
2. [Specific thing 2]
3. [etc.]

[Any issues or notes]

Should I make any adjustments?

SPECIAL TASK TYPES

Code Exploration Tasks

WHEN ASKED TO EXPLAIN/EXPLORE CODE:

  1. Use grep/glob to find relevant files
  2. Read files systematically
  3. Use project_eval to explore runtime behavior
  4. Explain findings clearly
  5. Reference specific files and line numbers

Refactoring Tasks

WHEN ASKED TO REFACTOR:

  1. Understand current implementation fully
  2. Research best practices in docs
  3. Create incremental refactoring plan
  4. Test after each change
  5. Ensure behavior unchanged

Documentation Tasks

WHEN ASKED TO DOCUMENT:

  1. Only create docs if EXPLICITLY requested
  2. Follow existing documentation patterns
  3. Focus on "why" not just "what"
  4. Include examples where helpful
  5. Keep concise and clear

Performance Tasks

WHEN ASKED TO OPTIMIZE:

  1. Measure current performance first
  2. Identify specific bottlenecks
  3. Research Ash-specific optimizations
  4. Apply minimal changes
  5. Measure improvement

CRITICAL RULES FOR ALL TASKS

  1. NO ASSUMPTIONS - Research everything
  2. NO COMMITS - Unless told "commit this"
  3. ASH FIRST - Always use Ash patterns
  4. TEST EVERYTHING - Verify all changes work
  5. ASK WHEN UNSURE - Better to clarify than guess
  6. REPORT PROGRESS - Keep user informed
  7. MINIMAL CHANGES - Don't over-engineer

WHEN TO ESCALATE

STOP AND ASK FOR HELP IF:

  • Task seems to require breaking the rules
  • You're unsure about security implications
  • The approach might affect system stability
  • You need to modify critical system files
  • The task specification is ambiguous
Raw
.claude__05-fix-workflow.md

BUG FIX WORKFLOW

THIS IS A MANDATORY WORKFLOW - ALL STEPS MUST BE COMPLETED IN ORDER

PHASE 1: UNDERSTANDING THE BUG (MANDATORY)

Step 1.1: Initial Investigation

REQUIRED ACTIONS:

  • Get exact error message/behavior description
  • Identify affected module/function using grep/glob
  • Use package_docs_search to understand intended behavior
  • Check existing usage rules via get_usage_rules MCP tool or CLAUDE.md links
  • Verify if bug violates any existing package usage rules
  • Check if this is an Ash-specific issue
  • Search for similar issues in codebase history

Step 1.2: Root Cause Analysis

YOU MUST:

  1. Read the failing code and surrounding context
  2. Trace the execution path
  3. Identify ALL places this bug might manifest
  4. Determine if it's a symptom of a larger issue
  5. Check for related bugs that might be hidden

Step 1.3: Reproduce the Bug

MANDATORY - NO EXCEPTIONS:

  1. Write a failing test that demonstrates the bug
  2. Ensure test fails for the RIGHT reason
  3. Verify test will pass once bug is fixed
  4. Place test in appropriate test file
  5. Run test and capture output

TEST TEMPLATE:

test "descriptive name of what should work" do
  # Arrange
  [setup code]

  # Act
  [code that triggers bug]

  # Assert
  [assertion that currently fails]
end

PHASE 2: PLANNING & APPROVAL (MANDATORY)

Step 2.1: Create Fix Plan Document

CREATE FILE: <project_root>/notes/fixes/<number>-<issue-description>.md (inside the project directory)

REQUIRED STRUCTURE:

# Fix: <Issue Description>

## Bug Summary

[1-2 sentences describing the bug and its impact]

## Root Cause

[Technical explanation of why this bug occurs]

## Existing Usage Rules Violations

[List any existing usage rules that were violated leading to this bug]

## Reproduction Test

```elixir
[paste the failing test here]
```

Test Output

[paste test failure output]

Proposed Solution

[Detailed explanation of the fix approach]

Changes Required

  1. File: [path] - [what changes]
  2. File: [path] - [what changes]

Potential Side Effects

  • Side effect 1: [description]
  • Side effect 2: [description]

Regression Prevention

[How we ensure this doesn't break again]

Questions for Eric

  1. [Any clarifications needed]

### Step 2.2: Approval Checkpoint
**YOU MUST STOP HERE**:
1. Present the fix plan with failing test
2. Ask: "I've reproduced the bug with a test. Should I proceed with this fix approach?"
3. WAIT for explicit approval
4. Do NOT implement without approval

## PHASE 3: IMPLEMENTATION

### Step 3.1: Set Up Tracking
**REQUIRED**:
1. Use TodoWrite to track fix tasks
2. Add `## Implementation Log` section to fix document
3. Document each change as you make it

### Step 3.2: Apply Fix
**MANDATORY SEQUENCE**:
1. Make MINIMAL changes to fix the bug
2. Do NOT refactor unrelated code
3. Follow existing code patterns exactly
4. Use Ash patterns if touching Ash code
5. Add comments ONLY if fixing complex logic

### Step 3.3: Verification
**REQUIRED CHECKS**:
1. Run the reproduction test - MUST pass
2. Run full test suite - NO new failures
3. Compile - NO new warnings
4. Check for performance impact
5. Verify no security issues introduced

### Step 3.4: Extended Testing
**YOU MUST**:
1. Test edge cases around the fix
2. Test related functionality
3. Verify the fix handles all identified manifestations
4. Run any integration tests

## PHASE 4: DOCUMENTATION & REVIEW

### Step 4.1: Update Fix Document
**ADD SECTIONS**:
```markdown
## Final Implementation
[What was actually changed]

## Test Results
- Reproduction test: [PASSING/FAILING]
- Full test suite: [X passed, Y failed]
- New tests added: [list them]

## Verification Checklist
- [ ] Bug is fixed
- [ ] No regressions introduced
- [ ] Tests cover the fix
- [ ] Code follows patterns

Step 4.2: Final Review

PRESENT TO USER:

  1. Show the passing test
  2. Summarize what was fixed
  3. List any concerns
  4. Ask: "Fix implemented and tested. Ready to finalize?"

PHASE 5: COMPLETION

Step 5.1: Cleanup

IF APPROVED:

  1. Ensure all tests are passing
  2. Remove any debug code
  3. Update fix document with final status
  4. Mark all todos as complete

Step 5.2: Prevention Follow-up

CONSIDER:

  1. Should similar code be checked?
  2. Is there a pattern to prevent this bug class?
  3. Should documentation be updated?
  4. Note any follow-up tasks needed

CRITICAL REMINDERS

  • TEST FIRST - No fix without failing test
  • MINIMAL CHANGES - Fix only what's broken
  • NO COMMITS - Unless explicitly told to commit
  • VERIFY EVERYTHING - All tests must pass
  • ASH PATTERNS - Use Ash ways for Ash code
  • WAIT FOR APPROVAL - At every checkpoint
Raw
.claude__config.json
{
"permissions": {
"allow": [
"Zsh(mix setup)",
"Zsh(mix phx.server)",
"Zsh(mix test)",
"Zsh(mix test path/to/test_file.exs:line_number)",
"Zsh(mix format)",
"Zsh(mix deps.get)",
"Zsh(mix ecto.setup)",
"Zsh(mix ecto.reset)",
"Read(~/.zshrc)",
"Read(.*)"
],
"deny": []
},
"env": {}
}
Raw
AGENTS.md

<-- usage-rules-start --> <-- ash_ai-start -->

ash_ai usage

ash_ai usage rules <-- ash_ai-end --> <-- ash_postgres-start -->

ash_postgres usage

ash_postgres usage rules <-- ash_postgres-end --> <-- ash_authentication-start -->

ash_authentication usage

ash_authentication usage rules <-- ash_authentication-end --> <-- ash_phoenix-start -->

ash_phoenix usage

ash_phoenix usage rules <-- ash_phoenix-end --> <-- ash-start -->

ash usage

ash usage rules <-- ash-end --> <-- ash_oban-start -->

ash_oban usage

ash_oban usage rules <-- ash_oban-end --> <-- ash_json_api-start -->

ash_json_api usage

ash_json_api usage rules <-- ash_json_api-end --> <-- igniter-start -->

igniter usage

igniter usage rules <-- igniter-end --> <-- usage-rules-end -->

Raw
CLAUDE.md

My Project

Short description of my project.

Build Commands

  • Setup: mix setup
  • Server: mix phx.server or iex -S mix phx.server
  • Tests: mix test
  • Single test: mix test path/to/test_file.exs:line_number
  • Format code: mix format
  • Dependencies: mix deps.get
  • DB setup: mix ecto.setup
  • DB reset: mix ecto.reset

Code Style

First and foremost, follow the project's guidelines for generating code:

  • Use Elixir 1.15+ conventions
  • Follow Phoenix 1.8+ patterns
  • Organize code by domain contexts under lib/my_project/
  • Web components under lib/my_project_web/
  • Use Ash Framework resources for domain models
  • Format with mix format before commits
  • Modules: PascalCase, Functions: snake_case
  • Attribute names: snake_case
  • Document public functions with @doc
  • Handle errors with proper pattern matching
  • Use pipelines (|>) for transforming data
  • Keep functions small and focused
  • Use Ash Framework authorization patterns

Ash Framework Requirements

  • ALWAYS use Ash concepts, almost NEVER Ecto concepts directly
  • Follow Ash resource patterns for domain models
  • Use Ash authentication patterns for user auth
  • Follow Ash authorization practices for security
  • Prefer Ash code generators when available
  • Check usage rules for all Ash extensions

Development Workflows

For New Features:

  1. Research thoroughly using package documentation
  2. Create detailed plan in /notes/features/
  3. Get approval before implementation
  4. Implement using generators when possible
  5. Test thoroughly after implementation
  6. Document in feature plan file

For Bug Fixes:

  1. Reproduce with a failing test
  2. Document fix plan in /notes/fixes/
  3. Get approval before implementing
  4. Make minimal changes to fix
  5. Verify all tests pass
  6. Document final implementation

For General Tasks:

  1. Break down into specific subtasks
  2. Research requirements thoroughly
  3. Follow existing patterns
  4. Test after each change
  5. Verify no regressions

Critical Rules

  1. NEVER commit changes unless explicitly instructed
  2. ALWAYS research before implementation
  3. Use Ash patterns exclusively
  4. Test everything thoroughly
  5. Ask for clarification when unsure
  6. Follow structured workflows for features and fixes
  7. Start with code generators whenever possible
  8. Use package_docs_search for documentation when available
  9. Stop at checkpoints and wait for approval

Project Structure

  • Domain logic in lib/my_project/
  • Web interface in lib/my_project_web/
  • Configurations in config/
  • Database migrations in priv/repo/migrations/
  • Tests in test/

Ash Extensions

This project uses several Ash Framework extensions:

  • ash_postgres: For database integration
  • ash_authentication: For user authentication
  • ash_phoenix: For Phoenix integration
  • ash_json_api: For API endpoints
  • ash_oban: For background jobs
  • ash_ai: For AI capabilities

Refer to AGENTS.md for extension-specific usage rules.

AI Toolbox Development Guides

  • @.claude/01-non-negotiable.md

Generating Code Guidelines

  • @.claude/02-generate-code.md

If asked to create a new feature, use the Feature Implementation Workflow

  • @.claude/03-feature-workflow.md

If asked to work on a task, use the General Task Workflow

  • @.claude/04-task-workflow.md

If asked to fix a bug, use the Bug Fix Workflow

  • @.claude/05-fix-workflow.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment