├── README.md ├── hugo-CLAUDE.md ├── python-CLAUDE.md ├── python2-CLAUDE.md └── terraform-CLAUDE.md /README.md: -------------------------------------------------------------------------------- 1 | Some sample CLAUDE.md files for use with Claude Code 2 | 3 | Edited/merged from other examples including 4 | 5 | * https://github.com/modelcontextprotocol/python-sdk/blob/main/CLAUDE.md 6 | * https://github.com/p33m5t3r/vibecoding/blob/main/conway/CLAUDE.md 7 | * https://github.com/saaspegasus/pegasus-docs/blob/main/CLAUDE.md 8 | -------------------------------------------------------------------------------- /hugo-CLAUDE.md: -------------------------------------------------------------------------------- 1 | # clune.org blog 2 | 3 | ## Architecture 4 | 5 | This project is a Hugo personal blog, follwing the standard Hugo conventions 6 | Posts go in `content/posts` 7 | 8 | ## Build Commands 9 | - Serve locally with auto-rebuild: `hugo server -D` 10 | - View docs at: http://localhost:1313 11 | 12 | ## Project Structure 13 | - Documentation source files in `.md` (Markdown) and `.rst` (reStructuredText) 14 | - Configuration in `conf.py` 15 | - Built docs go to `_build/` directory (not committed to repo) 16 | 17 | ## Style Guidelines 18 | - Use Markdown (`.md`) for new content when possible 19 | - Follow existing heading structure (# for top-level, ## for sections) 20 | - NEVER include a top level header on a content page. Use the title instead 21 | - ALWAYS create new blog posts with `draft: true` in the header 22 | - Include alt text for images 23 | - Use relative links for internal references 24 | - Keep line length reasonable for text readability 25 | - Code blocks use triple backticks with language specified 26 | 27 | ## Deployment 28 | - Automatically deployed via Cloudflare Pages from main branch 29 | -------------------------------------------------------------------------------- /python-CLAUDE.md: -------------------------------------------------------------------------------- 1 | # Development Guidelines 2 | 3 | This document contains critical information about working with this codebase. Follow these guidelines precisely. 4 | 5 | ## Core Development Rules 6 | 7 | 1. Package Management 8 | - ONLY use uv, NEVER pip 9 | - Installation: `uv add package` 10 | - Running tools: `uv run tool` 11 | - Upgrading: `uv add --dev package --upgrade-package package` 12 | - FORBIDDEN: `uv pip install`, `@latest` syntax 13 | 14 | 2. Code Quality 15 | - Type hints required for all code 16 | - Public APIs must have docstrings 17 | - Functions must be focused and small 18 | - Follow existing patterns exactly 19 | - Line length: 88 chars maximum 20 | 21 | 3. Testing Requirements 22 | - Framework: `uv run pytest` 23 | - Async testing: use anyio, not asyncio 24 | - Coverage: test edge cases and errors 25 | - New features require tests 26 | - Bug fixes require regression tests 27 | 28 | 4. Code Style 29 | - PEP 8 naming (snake_case for functions/variables) 30 | - Class names in PascalCase 31 | - Constants in UPPER_SNAKE_CASE 32 | - Document with docstrings 33 | - Use f-strings for formatting 34 | 35 | - For commits fixing bugs or adding features based on user reports add: 36 | ```bash 37 | git commit --trailer "Reported-by:" 38 | ``` 39 | Where `` is the name of the user. 40 | 41 | - For commits related to a Github issue, add 42 | ```bash 43 | git commit --trailer "Github-Issue:#" 44 | ``` 45 | - NEVER ever mention a `co-authored-by` or similar aspects. In particular, never 46 | mention the tool used to create the commit message or PR. 47 | 48 | ## Development Philosophy 49 | 50 | - **Simplicity**: Write simple, straightforward code 51 | - **Readability**: Make code easy to understand 52 | - **Performance**: Consider performance without sacrificing readability 53 | - **Maintainability**: Write code that's easy to update 54 | - **Testability**: Ensure code is testable 55 | - **Reusability**: Create reusable components and functions 56 | - **Less Code = Less Debt**: Minimize code footprint 57 | 58 | ## Coding Best Practices 59 | 60 | - **Early Returns**: Use to avoid nested conditions 61 | - **Descriptive Names**: Use clear variable/function names (prefix handlers with "handle") 62 | - **Constants Over Functions**: Use constants where possible 63 | - **DRY Code**: Don't repeat yourself 64 | - **Functional Style**: Prefer functional, immutable approaches when not verbose 65 | - **Minimal Changes**: Only modify code related to the task at hand 66 | - **Function Ordering**: Define composing functions before their components 67 | - **TODO Comments**: Mark issues in existing code with "TODO:" prefix 68 | - **Simplicity**: Prioritize simplicity and readability over clever solutions 69 | - **Build Iteratively** Start with minimal functionality and verify it works before adding complexity 70 | - **Run Tests**: Test your code frequently with realistic inputs and validate outputs 71 | - **Build Test Environments**: Create testing environments for components that are difficult to validate directly 72 | - **Functional Code**: Use functional and stateless approaches where they improve clarity 73 | - **Clean logic**: Keep core logic clean and push implementation details to the edges 74 | - **File Organsiation**: Balance file organization with simplicity - use an appropriate number of files for the project scale 75 | 76 | ## System Architecture 77 | 78 | [fill in here] 79 | 80 | ## Core Components 81 | 82 | - `config.py`: Configuration management 83 | - `daemon.py`: Main daemon 84 | [etc... fill in here] 85 | 86 | ## Pull Requests 87 | 88 | - Create a detailed message of what changed. Focus on the high level description of 89 | the problem it tries to solve, and how it is solved. Don't go into the specifics of the 90 | code unless it adds clarity. 91 | 92 | - Always add `ArthurClune` as reviewer. 93 | 94 | - NEVER ever mention a `co-authored-by` or similar aspects. In particular, never 95 | mention the tool used to create the commit message or PR. 96 | 97 | ## Python Tools 98 | 99 | ## Code Formatting 100 | 101 | 1. Ruff 102 | - Format: `uv run ruff format .` 103 | - Check: `uv run ruff check .` 104 | - Fix: `uv run ruff check . --fix` 105 | - Critical issues: 106 | - Line length (88 chars) 107 | - Import sorting (I001) 108 | - Unused imports 109 | - Line wrapping: 110 | - Strings: use parentheses 111 | - Function calls: multi-line with proper indent 112 | - Imports: split into multiple lines 113 | 114 | 2. Type Checking 115 | - Tool: `uv run pyright` 116 | - Requirements: 117 | - Explicit None checks for Optional 118 | - Type narrowing for strings 119 | - Version warnings can be ignored if checks pass 120 | 121 | 3. Pre-commit 122 | - Config: `.pre-commit-config.yaml` 123 | - Runs: on git commit 124 | - Tools: Prettier (YAML/JSON), Ruff (Python) 125 | - Ruff updates: 126 | - Check PyPI versions 127 | - Update config rev 128 | - Commit config first 129 | 130 | ## Error Resolution 131 | 132 | 1. CI Failures 133 | - Fix order: 134 | 1. Formatting 135 | 2. Type errors 136 | 3. Linting 137 | - Type errors: 138 | - Get full line context 139 | - Check Optional types 140 | - Add type narrowing 141 | - Verify function signatures 142 | 143 | 2. Common Issues 144 | - Line length: 145 | - Break strings with parentheses 146 | - Multi-line function calls 147 | - Split imports 148 | - Types: 149 | - Add None checks 150 | - Narrow string types 151 | - Match existing patterns 152 | 153 | 3. Best Practices 154 | - Check git status before commits 155 | - Run formatters before type checks 156 | - Keep changes minimal 157 | - Follow existing patterns 158 | - Document public APIs 159 | - Test thoroughly 160 | -------------------------------------------------------------------------------- /python2-CLAUDE.md: -------------------------------------------------------------------------------- 1 | # Development Guidelines 2 | 3 | This document contains critical information about working with this codebase. Follow these guidelines precisely. 4 | 5 | ## Core Development Rules 6 | 7 | 1. Package Management 8 | - ONLY use uv, NEVER pip 9 | - Installation: `uv add package` 10 | - Running tools: `uv run tool` 11 | - Upgrading: `uv add --dev package --upgrade-package package` 12 | - FORBIDDEN: `uv pip install`, `@latest` syntax 13 | 14 | 2. Code Quality 15 | - Type hints required for all code 16 | - use pyrefly for type checking 17 | - run `pyrefly init` to start 18 | - run `pyrefly check` after every change and fix resultings errors 19 | - Public APIs must have docstrings 20 | - Functions must be focused and small 21 | - Follow existing patterns exactly 22 | - Line length: 88 chars maximum 23 | 24 | 3. Testing Requirements 25 | - Framework: `uv run pytest` 26 | - Async testing: use anyio, not asyncio 27 | - Coverage: test edge cases and errors 28 | - New features require tests 29 | - Bug fixes require regression tests 30 | 31 | 4. Code Style 32 | - PEP 8 naming (snake_case for functions/variables) 33 | - Class names in PascalCase 34 | - Constants in UPPER_SNAKE_CASE 35 | - Document with docstrings 36 | - Use f-strings for formatting 37 | 38 | ## Development Philosophy 39 | 40 | - **Simplicity**: Write simple, straightforward code 41 | - **Readability**: Make code easy to understand 42 | - **Performance**: Consider performance without sacrificing readability 43 | - **Maintainability**: Write code that's easy to update 44 | - **Testability**: Ensure code is testable 45 | - **Reusability**: Create reusable components and functions 46 | - **Less Code = Less Debt**: Minimize code footprint 47 | 48 | ## Coding Best Practices 49 | 50 | - **Early Returns**: Use to avoid nested conditions 51 | - **Descriptive Names**: Use clear variable/function names (prefix handlers with "handle") 52 | - **Constants Over Functions**: Use constants where possible 53 | - **DRY Code**: Don't repeat yourself 54 | - **Functional Style**: Prefer functional, immutable approaches when not verbose 55 | - **Minimal Changes**: Only modify code related to the task at hand 56 | - **Function Ordering**: Define composing functions before their components 57 | - **TODO Comments**: Mark issues in existing code with "TODO:" prefix 58 | - **Simplicity**: Prioritize simplicity and readability over clever solutions 59 | - **Build Iteratively** Start with minimal functionality and verify it works before adding complexity 60 | - **Run Tests**: Test your code frequently with realistic inputs and validate outputs 61 | - **Build Test Environments**: Create testing environments for components that are difficult to validate directly 62 | - **Functional Code**: Use functional and stateless approaches where they improve clarity 63 | - **Clean logic**: Keep core logic clean and push implementation details to the edges 64 | - **File Organsiation**: Balance file organization with simplicity - use an appropriate number of files for the project scale 65 | 66 | ## System Architecture 67 | 68 | - use pydantic and langchain 69 | - this project is a very simple chatbot. Keep files to a minimum 70 | 71 | 72 | 73 | ## Pull Requests 74 | 75 | - Create a detailed message of what changed. Focus on the high level description of 76 | the problem it tries to solve, and how it is solved. Don't go into the specifics of the 77 | code unless it adds clarity. 78 | 79 | ## Git Workflow 80 | 81 | - Always use feature branches; do not commit directly to `main` 82 | - Name branches descriptively: `fix/auth-timeout`, `feat/api-pagination`, `chore/ruff-fixes` 83 | - Keep one logical change per branch to simplify review and rollback 84 | - Create pull requests for all changes 85 | - Open a draft PR early for visibility; convert to ready when complete 86 | - Ensure tests pass locally before marking ready for review 87 | - Use PRs to trigger CI/CD and enable async reviews 88 | - Link issues 89 | - Before starting, reference an existing issue or create one 90 | - Use commit/PR messages like `Fixes #123` for auto-linking and closure 91 | - Commit practices 92 | - Make atomic commits (one logical change per commit) 93 | - Prefer conventional commit style: `type(scope): short description` 94 | - Examples: `feat(eval): group OBS logs per test`, `fix(cli): handle missing API key` 95 | - Squash only when merging to `main`; keep granular history on the feature branch 96 | - Practical workflow 97 | 1. Create or reference an issue 98 | 2. `git checkout -b feat/issue-123-description` 99 | 3. Commit in small, logical increments 100 | 4. `git push` and open a draft PR early 101 | 5. Convert to ready PR when functionally complete and tests pass 102 | 6. Merge after reviews and checks pass 103 | 104 | ## Python Tools 105 | 106 | - use context7 mcp to check details of libraries 107 | 108 | ## Code Formatting 109 | 110 | 1. Ruff 111 | - Format: `uv run ruff format .` 112 | - Check: `uv run ruff check .` 113 | - Fix: `uv run ruff check . --fix` 114 | - Critical issues: 115 | - Line length (88 chars) 116 | - Import sorting (I001) 117 | - Unused imports 118 | - Line wrapping: 119 | - Strings: use parentheses 120 | - Function calls: multi-line with proper indent 121 | - Imports: split into multiple lines 122 | 123 | 2. Type Checking 124 | - run `pyrefly init` to start 125 | - run `pyrefly check` after every change and fix resultings errors 126 | - Requirements: 127 | - Explicit None checks for Optional 128 | - Type narrowing for strings 129 | - Version warnings can be ignored if checks pass 130 | 131 | 132 | ## Error Resolution 133 | 134 | 1. CI Failures 135 | - Fix order: 136 | 1. Formatting 137 | 2. Type errors 138 | 3. Linting 139 | - Type errors: 140 | - Get full line context 141 | - Check Optional types 142 | - Add type narrowing 143 | - Verify function signatures 144 | 145 | 2. Common Issues 146 | - Line length: 147 | - Break strings with parentheses 148 | - Multi-line function calls 149 | - Split imports 150 | - Types: 151 | - Add None checks 152 | - Narrow string types 153 | - Match existing patterns 154 | 155 | 3. Best Practices 156 | - Check git status before commits 157 | - Run formatters before type checks 158 | - Keep changes minimal 159 | - Follow existing patterns 160 | - Document public APIs 161 | - Test thoroughly 162 | -------------------------------------------------------------------------------- /terraform-CLAUDE.md: -------------------------------------------------------------------------------- 1 | # Terraform Development Instructions for Claude Code 2 | 3 | ## Overview 4 | This guide defines how to work with Terraform code, emphasising multi-file coordination, linting with tflint, and security scanning with checkov. 5 | 6 | ## Critical Rules 7 | 8 | ### 1. Multi-File Awareness 9 | - **Always scan the entire module directory** before making changes 10 | - Check for dependencies across files: variables, outputs, data sources, and resources may be referenced anywhere 11 | - When modifying a resource, search for all references to it across `.tf` files 12 | - Consider module boundaries and inter-module dependencies 13 | 14 | ### 2. File Organisation 15 | Follow standard Terraform conventions: 16 | - `main.tf` - Primary resources 17 | - `variables.tf` - Variable declarations 18 | - `outputs.tf` - Output definitions 19 | - `providers.tf` - Provider configurations 20 | - `versions.tf` - Terraform and provider version constraints 21 | - `data.tf` - Data sources (if numerous) 22 | - `locals.tf` - Local values (if numerous) 23 | 24 | ### 3. Change Coordination 25 | When making changes: 26 | 1. **Identify scope**: List all files that might be affected 27 | 2. **Search references**: Use grep/search for resource names, variable names, output names 28 | 3. **Update systematically**: Make changes in dependency order 29 | 4. **Verify completeness**: Re-check all references after changes 30 | 31 | ## Linting with tflint 32 | 33 | ### Setup Check 34 | ```bash 35 | # Verify tflint is installed 36 | which tflint || echo "tflint not installed" 37 | 38 | # Check for .tflint.hcl configuration 39 | ls -la .tflint.hcl 40 | ``` 41 | 42 | ### Standard Linting Process 43 | ```bash 44 | # Initialise tflint (first time or when plugins change) 45 | tflint --init 46 | 47 | # Run linting on current directory 48 | tflint 49 | 50 | # Run with more detailed output 51 | tflint --format compact 52 | 53 | # Run recursively on all modules 54 | tflint --recursive 55 | ``` 56 | 57 | ### Common tflint Issues to Fix 58 | - Deprecated syntax or arguments 59 | - Invalid instance types 60 | - Hardcoded credentials 61 | - Missing required providers 62 | - Unused declarations 63 | 64 | ## Security Scanning with checkov 65 | 66 | ### Setup Check 67 | ```bash 68 | # Verify checkov is installed 69 | which checkov || echo "checkov not installed" 70 | 71 | # Check Python version (needs 3.7+) 72 | python3 --version 73 | ``` 74 | 75 | ### Standard Security Scan 76 | ```bash 77 | # Scan current directory 78 | checkov -d . 79 | 80 | # Scan with specific framework 81 | checkov -d . --framework terraform 82 | 83 | # Output results in JSON for parsing 84 | checkov -d . -o json 85 | 86 | # Skip specific checks 87 | checkov -d . --skip-check CKV_AWS_20,CKV_AWS_23 88 | 89 | # Run only specific checks 90 | checkov -d . --check CKV_AWS_* 91 | ``` 92 | 93 | ### Critical Security Checks 94 | Focus on these high-priority items: 95 | - Encryption at rest enabled 96 | - Encryption in transit enabled 97 | - Public access restrictions 98 | - IAM least privilege 99 | - Logging enabled 100 | - Backup configured 101 | - No hardcoded secrets 102 | 103 | ## Development Workflow 104 | 105 | ### 1. Before Starting Changes 106 | ```bash 107 | # Check current state 108 | terraform init 109 | terraform validate 110 | tflint 111 | checkov -d . 112 | 113 | # Review existing structure 114 | find . -name "*.tf" -type f | head -20 115 | grep -r "resource\|module\|data" --include="*.tf" | head -20 116 | ``` 117 | 118 | ### 2. Making Changes 119 | 1. **Plan the change**: Identify all affected files 120 | 2. **Search for dependencies**: 121 | ```bash 122 | # Example: changing a security group 123 | grep -r "aws_security_group\.example" --include="*.tf" 124 | grep -r "security_group_id" --include="*.tf" 125 | ``` 126 | 3. **Update systematically**: Start with variables, then resources, then outputs 127 | 4. **Maintain consistency**: Keep naming conventions and patterns 128 | 129 | ### 3. After Changes 130 | ```bash 131 | # Validate syntax 132 | terraform fmt -recursive 133 | terraform validate 134 | 135 | # Check for issues 136 | tflint --recursive 137 | checkov -d . 138 | 139 | # Plan to verify 140 | terraform plan -out=plan.out 141 | ``` 142 | 143 | ## Common Patterns 144 | 145 | ### Resource Naming 146 | ```hcl 147 | # Use consistent prefixes and suffixes 148 | resource "aws_instance" "web_server" { 149 | # Not: resource "aws_instance" "my-instance" 150 | } 151 | 152 | # Include environment in names 153 | resource "aws_s3_bucket" "data_${var.environment}" { 154 | bucket = "${var.project}-data-${var.environment}" 155 | } 156 | ``` 157 | 158 | ### Variable Usage 159 | ```hcl 160 | # Always declare variables with: 161 | variable "instance_type" { 162 | description = "EC2 instance type" 163 | type = string 164 | default = "t3.micro" 165 | 166 | validation { 167 | condition = contains(["t3.micro", "t3.small", "t3.medium"], var.instance_type) 168 | error_message = "Instance type must be t3.micro, t3.small, or t3.medium." 169 | } 170 | } 171 | ``` 172 | 173 | ### Output References 174 | ```hcl 175 | # When adding outputs, check if they're used in: 176 | # - Parent modules 177 | # - Remote state data sources 178 | # - External scripts 179 | output "vpc_id" { 180 | description = "ID of the VPC" 181 | value = aws_vpc.main.id 182 | } 183 | ``` 184 | 185 | ## Multi-File Change Examples 186 | 187 | ### Example 1: Adding a New Variable 188 | 1. Add to `variables.tf`: 189 | ```hcl 190 | variable "enable_monitoring" { 191 | description = "Enable detailed monitoring" 192 | type = bool 193 | default = false 194 | } 195 | ``` 196 | 197 | 2. Search for where to use it: 198 | ```bash 199 | grep -r "monitoring\|instance" --include="*.tf" 200 | ``` 201 | 202 | 3. Update `main.tf`: 203 | ```hcl 204 | resource "aws_instance" "web" { 205 | # ... 206 | monitoring = var.enable_monitoring 207 | } 208 | ``` 209 | 210 | ### Example 2: Refactoring Security Groups 211 | 1. Identify all references: 212 | ```bash 213 | grep -r "security_group" --include="*.tf" 214 | grep -r "ingress\|egress" --include="*.tf" 215 | ``` 216 | 217 | 2. Create new security group in `security.tf` 218 | 3. Update all resources using the old security group 219 | 4. Add outputs if needed 220 | 5. Remove old security group only after confirming no references 221 | 222 | ## Testing Checklist 223 | 224 | Before considering any Terraform change complete: 225 | 226 | - [ ] `terraform fmt -recursive` passes 227 | - [ ] `terraform validate` passes 228 | - [ ] `tflint --recursive` shows no errors 229 | - [ ] `checkov -d .` critical issues resolved 230 | - [ ] All variable references resolved 231 | - [ ] All output consumers checked 232 | - [ ] Module interfaces maintained 233 | - [ ] Documentation updated 234 | - [ ] Change tested with `terraform plan` 235 | 236 | ## Module Development 237 | 238 | When working with modules: 239 | 1. Check `modules/*/variables.tf` for interface changes 240 | 2. Verify `modules/*/outputs.tf` for breaking changes 241 | 3. Search parent directories for module calls 242 | 4. Update module version constraints if needed 243 | 244 | ## Common Pitfalls 245 | 246 | 1. **Partial Updates**: Changing a resource name but not its references 247 | 2. **Missing Dependencies**: Not adding `depends_on` when needed 248 | 3. **Security Group Loops**: Circular references between security groups 249 | 4. **Count/For_each Changes**: These cause resource recreation 250 | 5. **Provider Aliases**: Forgetting to pass providers to modules 251 | 252 | ## Emergency Procedures 253 | 254 | If terraform plan shows unexpected destruction: 255 | 1. **STOP** - Don't apply 256 | 2. Check for: 257 | - Changed resource names 258 | - Modified count/for_each expressions 259 | - Moved resources without using `moved` blocks 260 | 3. Use `terraform state mv` if needed 261 | 4. Consider using `-target` for partial applies 262 | 263 | ## Integration with CI/CD 264 | 265 | Include these checks in automated pipelines: 266 | ```bash 267 | #!/bin/bash 268 | set -e 269 | 270 | terraform fmt -check -recursive 271 | terraform init -backend=false 272 | terraform validate 273 | tflint --recursive 274 | checkov -d . --quiet --compact 275 | ``` 276 | 277 | ## Remember 278 | 279 | 1. **Read before writing**: Understand the existing structure 280 | 2. **Search before changing**: Find all dependencies 281 | 3. **Lint before committing**: Run tflint and checkov 282 | 4. **Plan before applying**: Always review terraform plan output 283 | 5. **Document complex logic**: Add comments for non-obvious p 284 | 285 | # Live changes 286 | 287 | Claude MUST NOT ever make changes to systems (terraform apply) 288 | ***LINT and CHECK ONLY*** 289 | --------------------------------------------------------------------------------