|
| 1 | +# Contributing with Claude AI Assistant |
| 2 | + |
| 3 | +This guide helps contributors use Claude (an AI assistant) effectively when working on OWASP Cornucopia, while maintaining code quality and adhering to [project standards](/.github/copilot-instructions.md). |
| 4 | + |
| 5 | +> This document is supposed to be the primary source of context for **all** AI tools. Context files of tools other than Claude should refer to [this `CLAUDE.md` file](CLAUDE.md) for detailed guidelines. This is already the case for: |
| 6 | +> * GitHub CoPilot ([`.github/copilot-instructions.md`](../.github/copilot-instructions.md)) |
| 7 | +
|
| 8 | +## Security Guidelines |
| 9 | + |
| 10 | +You are an AI programming assistant that helps developers write secure code in accordance with the OWASP Application Security Verification Standard (ASVS) 5.0. All code suggestions must adhere to these security standards (Link to [ASVS 5.0 requirements](/.github/chatmodes/asvs.md) when vulnerabilities are found, and suggestions are made). |
| 11 | +Take directions according to what is stated for the [OWASP Security Champion mode](/.github/chatmodes/owasp-security-champion.md) |
| 12 | + |
| 13 | +## ✅ Good Use Cases |
| 14 | + |
| 15 | +- **Code Analysis**: Understanding existing code structure and patterns |
| 16 | +- **Refactoring**: Improving code quality while maintaining functionality |
| 17 | +- **Test Writing**: Creating unit, integration, and e2e tests |
| 18 | +- **Bug Fixing**: Identifying and resolving issues |
| 19 | +- **Documentation**: Writing clear comments and documentation |
| 20 | + |
| 21 | +## ⚠️ Use with Caution |
| 22 | + |
| 23 | +- **Security Vulnerabilities**: Ensure AI-suggested vulnerabilities are intentional and appropriate for the project |
| 24 | +- **Dependencies**: Verify any suggested package updates for compatibility |
| 25 | +- **Architecture Changes**: Discuss major structural changes with maintainers first |
| 26 | + |
| 27 | +## Essential Guidelines |
| 28 | + |
| 29 | +### 1. Clean Up AI-Generated Noise |
| 30 | + |
| 31 | +**Required** per CONTRIBUTING.md rule #6: Remove unnecessary AI-generated content before submitting PRs. |
| 32 | + |
| 33 | +Remove: |
| 34 | + |
| 35 | +- Verbose comments explaining obvious code |
| 36 | +- Generic placeholder comments |
| 37 | +- Overly detailed docstrings for simple functions |
| 38 | +- Repetitive explanations |
| 39 | + |
| 40 | +Keep: |
| 41 | + |
| 42 | +- Meaningful comments for complex logic |
| 43 | +- Challenge hints and metadata |
| 44 | +- Security-relevant documentation |
| 45 | + |
| 46 | +### 2. Code Style Compliance |
| 47 | + |
| 48 | +Always run Black before committing Python code: |
| 49 | + |
| 50 | +```bash |
| 51 | +pipenv run black --line-length=120 --check . |
| 52 | +``` |
| 53 | + |
| 54 | +For Python code, Claude should suggest code following PEP 8 style guidelines and type hints (PEP 484) for function signatures, but always verify. |
| 55 | + |
| 56 | +### 3. Testing Requirements |
| 57 | + |
| 58 | +For any code changes, Claude helps with: |
| 59 | +- **Unit/Integration Tests**: New features and changes should have tests |
| 60 | +- **E2E Tests**: Required for new/modified code |
| 61 | + |
| 62 | +### 4. Commit Sign-off |
| 63 | + |
| 64 | +All commits must be signed off (DCO): |
| 65 | + |
| 66 | +```bash |
| 67 | +git commit -s -m "Your commit message" |
| 68 | +``` |
| 69 | + |
| 70 | +### 5. Branch and PR Strategy |
| 71 | + |
| 72 | +- Keep PRs focused on a single scope |
| 73 | +- Reference related issues in PR descriptions |
| 74 | + |
| 75 | +## Development Workflow with Claude |
| 76 | + |
| 77 | +### 1. Understanding the Codebase |
| 78 | + |
| 79 | +``` |
| 80 | +Ask Claude to: |
| 81 | +- Explain specific components or patterns |
| 82 | +- Identify where to implement new features |
| 83 | +- Trace code execution paths |
| 84 | +``` |
| 85 | + |
| 86 | +### 2. Implementation |
| 87 | + |
| 88 | +``` |
| 89 | +Ask Claude to: |
| 90 | +- Generate initial implementation |
| 91 | +- Suggest test cases |
| 92 | +- Review for security implications |
| 93 | +``` |
| 94 | + |
| 95 | +### 3. Quality Assurance |
| 96 | + |
| 97 | +``` |
| 98 | +Before committing: |
| 99 | +1. Remove AI-generated noise |
| 100 | +2. For Python code, run: pipenv run black --line-length=120 --check . |
| 101 | +3. Run relevant test suites |
| 102 | +4. Manually verify functionality |
| 103 | +5. Check for unintended changes |
| 104 | +6. Follow the [project standards](/.github/copilot-instructions.md) |
| 105 | +``` |
| 106 | + |
| 107 | +### 4. Documentation |
| 108 | + |
| 109 | +``` |
| 110 | +Ask Claude to: |
| 111 | +- Write clear commit messages |
| 112 | +- Draft PR descriptions |
| 113 | +- Document complex logic |
| 114 | +``` |
| 115 | + |
| 116 | +## Anti-Patterns to Avoid |
| 117 | + |
| 118 | +❌ **Don't**: Accept AI suggestions blindly without understanding them |
| 119 | +✅ **Do**: Review and understand all AI-generated code |
| 120 | + |
| 121 | +❌ **Don't**: Submit PRs with verbose AI-generated comments |
| 122 | +✅ **Do**: Clean up and keep only meaningful comments |
| 123 | + |
| 124 | +❌ **Don't**: Skip testing because AI "seems confident" |
| 125 | +✅ **Do**: Always run the full test suite |
| 126 | + |
| 127 | +❌ **Don't**: Use AI for contribution farming or trivial changes |
| 128 | +✅ **Do**: Make meaningful contributions that add value |
| 129 | + |
| 130 | +## Example: Fixing a Bug |
| 131 | + |
| 132 | +```bash |
| 133 | +# 1. Ask Claude to analyze the issue |
| 134 | +"Help me understand why the basket total calculation is incorrect" |
| 135 | + |
| 136 | +# 2. Locate the problematic code |
| 137 | +"Show me where basket totals are calculated" |
| 138 | + |
| 139 | +# 3. Implement the fix with Claude's help |
| 140 | +"Fix the calculation to properly handle discount edge cases" |
| 141 | + |
| 142 | +# 4. Generate tests |
| 143 | +"Create unit tests to cover the discount calculation edge cases" |
| 144 | + |
| 145 | +# 5. Quality checks |
| 146 | +npm run lint |
| 147 | +npm test |
| 148 | +npm run rsn # If the fix affects code used in a coding challenge |
| 149 | + |
| 150 | +# 6. Clean up and commit with sign-off |
| 151 | +git commit -s -m "Fix basket total calculation for discount edge cases" |
| 152 | +``` |
| 153 | + |
| 154 | +## Quality Checklist |
| 155 | + |
| 156 | +Before submitting a Claude-assisted PR: |
| 157 | + |
| 158 | +- [ ] Code follows the project coding standard and style |
| 159 | +- [ ] AI-generated noise removed |
| 160 | +- [ ] Tests added/updated and passing |
| 161 | +- [ ] Manual testing completed |
| 162 | +- [ ] Commits are signed off |
| 163 | +- [ ] Single, focused scope |
| 164 | +- [ ] All CI checks passing |
| 165 | + |
| 166 | +## Claude-Specific Context |
| 167 | + |
| 168 | +The following context is provided to help Claude better assist with contributions to this project: |
| 169 | + |
| 170 | +### Project Overview |
| 171 | + |
| 172 | +- **Project**: OWASP Cornucopia - The project contains 3 projects: |
| 173 | + - [/scripts](/scripts): Converter scripts to convert translations for editions of the Cornucopia game into IDML and PDF files that can be printed. |
| 174 | + - [/cornucopia.owasp.org](/cornucopia.owasp.org): The Website for OWASP Cornucopia written in Typescript. |
| 175 | + - [/copi.owasp.org](/copi.owasp.org): The Cornucopia game engine written in Elixir that can be hosted as an online game engine where it is possible to play Cornucopia and EoP-related games. |
| 176 | +- **Primary Languages**: Python, TypeScript and Elixir |
| 177 | +- **Key Technologies**: Node.js, Svelte, Phoenix |
| 178 | +- **Testing**: mix test (/copi.owasp.org), vitest (/cornucopia.owasp.org), Python unittest (/scripts) |
| 179 | +- **Code Style**: |
| 180 | + - For Python code, use PEP 8 style guidelines |
0 commit comments