|
| 1 | +# CLAUDE.md — Repository guidelines for AI-assisted edits |
| 2 | + |
| 3 | +This file documents repository-level expectations and instructions intended to guide contributors and AI-assisted editing tools (like Claude Code) when making changes in this project. |
| 4 | + |
| 5 | +## High-level rules |
| 6 | + |
| 7 | +1. Any changes must be reviewed and approved before being merged, pushed to protected branches (e.g. main), or considered final. |
| 8 | +2. When introducing changes or adding features, create automated tests that cover the new behavior and run relevant test suites locally and in CI to avoid regressions. |
| 9 | + |
| 10 | +## Branching & commits |
| 11 | + |
| 12 | +- Use feature branches (feature/..., fix/..., chore/...) for all work. Do not commit directly to protected branches. |
| 13 | +- Keep commits small and focused. Each commit should represent a single logical change and have a descriptive message explaining why the change was made. |
| 14 | +- Annotate AI-assisted changes in the commit message, e.g. include: "Co-Authored-By: Claude <noreply@anthropic.com>" or a short note like "AI-assisted edit". |
| 15 | + |
| 16 | +## Pull requests & code review |
| 17 | + |
| 18 | +- Open a Pull Request (PR) for any non-trivial change. PRs must include: |
| 19 | + - A short summary of the change |
| 20 | + - Test plan and evidence that tests were run |
| 21 | + - Any relevant screenshots or logs for UI/behavior changes |
| 22 | +- At least one human reviewer must approve the PR before merging. Enable branch protection rules to require approvals. |
| 23 | +- Use a PR template where useful to ensure consistent information is provided. |
| 24 | + |
| 25 | +## Tests & CI |
| 26 | + |
| 27 | +- New features and bug fixes must include tests (unit/integration/end-to-end as appropriate). |
| 28 | +- Run the full project test suite locally before opening a PR. Fix flakiness or annotate tests that are inherently flaky with a TODO and create a follow-up issue. |
| 29 | +- CI must run linting, type checks, and the test suite. CI failures are blocking — do not merge until CI is green. |
| 30 | + |
| 31 | +## Quality & safety checks |
| 32 | + |
| 33 | +- Run linters and formatters (pre-commit hooks) locally. Add or update pre-commit configuration as necessary. |
| 34 | +- Do not commit secrets, credentials, or private keys. Use a secrets manager for sensitive configuration. |
| 35 | +- Keep third-party dependencies up to date and run dependency scanning tools in CI. |
| 36 | +- Add security checks (SAST/DAST) in CI where feasible. |
| 37 | + |
| 38 | +## Using AI editor tools (vibe coding) — suggestions and precautions |
| 39 | + |
| 40 | +When using AI-assisted editing ("vibe coding") in this repository, follow these extra precautions to keep the codebase healthy and maintainable: |
| 41 | + |
| 42 | +- Trust, but verify: Treat AI edits as a helpful draft. Always review the generated changes line-by-line before committing. |
| 43 | +- Limit scope per edit: Ask the AI/editor to make small, focused edits rather than large sweeping refactors in a single change. |
| 44 | +- Run tests and linters after every AI-assisted change. If a change touches behavior, add or update tests to cover it. |
| 45 | +- Prefer explicit guidance: When asking the AI to edit code, provide the exact files, functions, and desired behavior to avoid unintended edits. |
| 46 | +- Annotate AI-generated code: Add a short comment near non-trivial generated logic explaining intent and that it was AI-assisted. This makes reviews easier. |
| 47 | +- Keep humans in the loop: Require a human approval step before push/merge; do not allow automated approvals of AI-only changes. |
| 48 | +- Add TODOs for follow-ups: If an AI change is exploratory, mark it with clear TODOs and create follow-up issues for human cleanup or optimization. |
| 49 | + |
| 50 | +## Developer workflow checklist (what to do before merging) |
| 51 | + |
| 52 | +1. Confirm the change is on a feature branch and limited in scope. |
| 53 | +2. Run linters, type-checkers, and the full test suite locally. |
| 54 | +3. Push the branch and open a PR with a clear description and test plan. |
| 55 | +4. Request reviewers and wait for human approval. Address review comments. |
| 56 | +5. Ensure CI passes all jobs (lint, test, security checks). |
| 57 | +6. Merge only after approvals and CI green. Squash or rebase commits as agreed by the team. |
| 58 | + |
| 59 | +## Repository housekeeping and automation ideas |
| 60 | + |
| 61 | +- Add a CODEOWNERS file to route reviews to the right maintainers. |
| 62 | +- Configure branch protection rules (require PRs, require CI, require approval, prevent force pushes). |
| 63 | +- Add pre-commit hooks to enforce linting/formatting and basic static checks. |
| 64 | +- Add CI jobs for test coverage, dependency scanning, and security scanning. |
| 65 | +- Encourage small, frequent PRs to reduce review fatigue and make AI-assisted changes easier to audit. |
| 66 | + |
| 67 | +## Communication & documentation |
| 68 | + |
| 69 | +- Update README and any relevant docs when adding features or changing APIs. |
| 70 | +- Use changelogs for user-facing changes and notable internal refactors. |
| 71 | +- Document any non-obvious design decisions in code comments or design notes. |
| 72 | + |
| 73 | +--- |
| 74 | + |
| 75 | +If you are an AI-assisted tool editing this repository, treat this file as the authoritative guideline for how to structure edits, tests, commit messages, and PRs. Human verification and tests are required before any change is considered final. |
0 commit comments