**For humans:** Read this CLAUDE.md top to bottom before your first commit. Then read `AGENTS.<lang>.md` for the service you are working on (`AGENTS.python.md`, `AGENTS.go.md`, or `AGENTS.typescript.md`).
**For Claude Code sessions — things that cause first-commit failures:**
1.**Wrong branch.** Run `git branch --show-current` before touching any file. The answer must be `coolify`. If it is `main`, run `git checkout coolify` before proceeding.
2.**PreToolUse hook blocks your write.** The `PreToolUse` hooks in `.claude/settings.json` will reject Write/Edit operations on any file that would push its line count past 500. This is intentional — split the file into smaller modules instead of trying to bypass the hook.
3.**Missing `[guardrail-change]` marker.** The `guardrail-integrity` CI job fails if you modify a guardrail file without the marker in the commit message body. See the table below.
4.**Never `git add -A` or `git add .`.** Stage files individually by path. `git add -A` risks committing `.env`, `node_modules/`, `.next/`, compiled binaries, and other artifacts that must never enter the repo.
5.**LOC check before push.** After any session, run `bash scripts/check-loc.sh`. It must exit 0 before you push. The git pre-commit hook runs this automatically, but run it manually first to catch issues early.
### Commit message quick reference
| Marker | Required when touching |
|--------|----------------------|
| `[guardrail-change]` | `.claude/settings.json`, `scripts/check-loc.sh`, `scripts/githooks/pre-commit`, `.claude/rules/loc-exceptions.txt`, any `AGENTS.*.md` |
| `[migration-approved]` | Anything under `migrations/` or `alembic/versions/` |
Add the marker anywhere in the commit message body or footer — the CI job does a plain-text grep for it.
---
## Entwicklungsumgebung (WICHTIG - IMMER ZUERST LESEN)
- Go (Gin): Standard Go Project Layout + hexagonal. `cmd/` is thin wiring. See `AGENTS.go.md`.
- TypeScript (Next.js 15): server-first, push client boundary deep, colocate `_components/` + `_hooks/` per route. See `AGENTS.typescript.md`.
### Database is frozen
- No new Alembic migrations, no `ALTER TABLE`, no `__tablename__` or column renames.
- The pre-commit hook blocks any change under `migrations/` or `alembic/versions/` unless the commit message contains `[migration-approved]`.
### Public endpoints are a contract
- Any change to a route path, HTTP method, status code, request schema, or response schema in `backend-compliance/`, `ai-compliance-sdk/`, `dsms-gateway/`, `document-crawler/`, or `compliance-tts-service/`**must** be accompanied by a matching update in every consumer (`admin-compliance/`, `developer-portal/`, `breakpilot-compliance-sdk/`, `consent-sdk/`) in the **same changeset**.
- OpenAPI baseline snapshots live in `tests/contracts/`. Contract tests fail on any drift.
---
## 6. Pull Requests
- **Target branch: `coolify`** — never open a PR directly against `main`.
- Keep PRs focused; one logical change per PR.
**PR checklist before requesting review:**
- [ ]`bash scripts/check-loc.sh` exits 0
- [ ] All lint checks pass (go, python, tsc)
- [ ] All tests pass locally
- [ ] No endpoint drift without consumer updates in the same PR
- [ ]`[guardrail-change]` present in commit message if guardrail files were touched
- [ ] Docs updated if new endpoints, config vars, or architecture changed
---
## 7. Claude Code Users
This section is for AI-assisted development sessions using Claude Code.
- **Always verify your branch first:** `git branch --show-current` must return `coolify`. If it returns `main`, switch before doing anything.
- The `.claude/settings.json``PreToolUse` hooks will automatically block Write/Edit operations on files that would exceed 500 lines. This is intentional — split the file instead.
- If the `guardrail-integrity` CI job fails, check that your commit message body includes `[guardrail-change]`. Add it and amend or create a fixup commit.
- **Never use `git add -A` or `git add .`** — always stage specific files by path to avoid accidentally committing `.env`, `node_modules/`, `.next/`, or compiled binaries.
- After every session: `bash scripts/check-loc.sh` must exit 0 before pushing.
- Read `CLAUDE.md` and the relevant `AGENTS.<lang>.md` before starting work on a service.
breakpilot-compliance is a multi-tenant DSGVO/EU AI Act compliance platform that provides an SDK for consent management, data subject requests (DSR), audit logging, iACE impact assessments, and document archival. It ships as 10 containerised services covering an admin dashboard, a developer portal, a Python/FastAPI backend, a Go AI compliance engine, TTS, and a decentralised document store on IPFS. Every service is deployed automatically via Gitea Actions → Coolify on the `coolify` branch.
All containers share the external `breakpilot-network` Docker network and depend on `breakpilot-core` (Valkey, Vault, RAG service, Nginx reverse proxy).
---
## Quick Start
**Prerequisites:** Docker, Go 1.24+, Python 3.12+, Node.js 20+
The `.claude/settings.json``PreToolUse` hook blocks Claude Code from writing or editing files that would exceed the hard cap. The git pre-commit hook re-checks. CI is the final gate.
These artifacts enforce the rules without you or Claude having to remember them. Install them as **Phase 0**, before touching any real code.
### 1.1 `.claude/CLAUDE.md` — loaded into every Claude session
```markdown
# <Your Project Name>
> **NON-NEGOTIABLE STRUCTURE RULES** (enforced by `.claude/settings.json` hook, git pre-commit, and CI):
> 1. **File-size budget:** soft target **300** lines, **hard cap 500** lines for any non-test, non-generated source file. Anything larger → split it. Exceptions are listed in `.claude/rules/loc-exceptions.txt` and require a written rationale.
> 2. **Clean architecture per service.** Routers/handlers stay thin (≤30 lines per handler) and delegate to services; services use repositories; repositories own DB I/O. See `AGENTS.python.md` / `AGENTS.go.md` / `AGENTS.typescript.md`.
> 3. **Do not touch the database schema.** No new migrations, no `ALTER TABLE`, no model field renames without an explicit migration plan reviewed by the DB owner.
> 4. **Public endpoints are a contract.** Any change to a path/method/status/schema in a backend must be accompanied by a matching update in **every** consumer. OpenAPI snapshot tests in `tests/contracts/` are the gate.
> 5. **Tests are not optional.** New code without tests fails CI. Refactors must preserve coverage and add a characterization test before splitting an oversized file.
> 6. **Do not bypass the guardrails.** Do not edit `.claude/settings.json`, `scripts/check-loc.sh`, or the loc-exceptions list to silence violations. If a rule is wrong, raise it in a PR description.
>
> These rules apply to every Claude Code session opened inside this repository, regardless of who launched it. They are loaded automatically via this CLAUDE.md.
```
Keep project-specific notes (dev environment, URLs, tech stack) under this header.
### 1.2 `.claude/settings.json` — PreToolUse LOC hook
First line of defense. Blocks Write/Edit operations that would create or push a file past 500 lines. This stops Claude from ever producing oversized files.
```json
{
"hooks":{
"PreToolUse":[
{
"matcher":"Write",
"hooks":[
{
"type":"command",
"command":"f=$(jq -r '.tool_input.file_path // empty'); [ -z \"$f\" ] && exit 0; lines=$(printf '%s' \"$(jq -r '.tool_input.content // empty')\" | awk 'END{print NR}'); if [ \"${lines:-0}\" -gt 500 ]; then echo '{\"decision\":\"block\",\"reason\":\"guardrail: file exceeds the 500-line hard cap. Split it into smaller modules per the layering rules in AGENTS.<lang>.md.\"}'; exit 0; fi",
"shell":"bash",
"timeout":5
}
]
},
{
"matcher":"Edit",
"hooks":[
{
"type":"command",
"command":"f=$(jq -r '.tool_input.file_path // empty'); [ -z \"$f\" ] || [ ! -f \"$f\" ] && exit 0; case \"$f\" in *.md|*.json|*.yaml|*.yml|*test*|*tests/*|*node_modules/*|*.next/*|*migrations/*) exit 0 ;; esac; new_str=$(jq -r '.tool_input.new_string // empty'); old_str=$(jq -r '.tool_input.old_string // empty'); old_lines=$(printf '%s' \"$old_str\" | awk 'END{print NR}'); new_lines=$(printf '%s' \"$new_str\" | awk 'END{print NR}'); cur=$(wc -l < \"$f\" | tr -d ' '); proj=$((cur - old_lines + new_lines)); if [ \"$proj\" -gt 500 ]; then echo \"{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"guardrail: this edit would push $f to ~$proj lines (hard cap is 500). Split the file before continuing.\\\"}\"; fi; exit 0",
- Edits to `.claude/settings.json`, `scripts/check-loc.sh`, `scripts/githooks/pre-commit`, `.claude/rules/loc-exceptions.txt`, or any `AGENTS.*.md` require `[guardrail-change]` in the commit message.
- If Claude thinks a rule is wrong, surface it to the user. Do not silently weaken.
## Tooling baseline
- Python: `ruff`, `mypy --strict` on new modules, `pytest --cov`.
Server vs Client: default is Server Component. Add `"use client"` only when state/effects/browser APIs needed. Push client boundary as deep as possible.
- ESLint with `@typescript-eslint`, type-aware rules on.
- `next build` clean. No `@ts-ignore`. `@ts-expect-error` only with a reason comment.
## What you may NOT do
- Business logic in `page.tsx` or `route.ts`.
- Cross-app module imports.
- `dangerouslySetInnerHTML` without explicit sanitization.
- Backend API calls from Client Components when a Server Component/Action would do.
- Change route contract without updating consumers in the same change.
- File > 500 lines.
- Globally disable lint/type rules — fix the root cause.
````
---
## 2. Phase plan — behavior-preserving refactor
Work in phases. Each phase ends green (tests pass, build clean, contract baseline unchanged). Do **not** skip ahead.
### Phase 0 — Foundation (single PR, low risk)
**Goal:** Set up rails. No code refactors yet.
1. Drop in all files from Section 1. Install hooks: `bash scripts/install-hooks.sh`.
2. Populate `.claude/rules/loc-exceptions.txt` with grandfathered entries (one line each, with a comment rationale) so CI doesn't fail day 1.
3. Append the non-negotiable rules block to root `CLAUDE.md`.
4. Add per-language `AGENTS.*.md` at repo root.
5. Add the CI jobs from §1.8.
6. Per-service `README.md` + `CLAUDE.md` stubs: what it does, run/test commands, layered architecture diagram, env vars, API surface link.
**Verification:** CI green; loc-budget job passes with allowlist; next Claude session loads the rules automatically.
### Phase 1 — Backend service (Python/FastAPI)
**Critical targets:** any `routes.py` / `schemas.py` / `repository.py` / `models.py` over 500 LOC.
**Steps:**
1. **Snapshot the API contract:** `curl /openapi.json > tests/contracts/openapi.baseline.json`. Add a contract test that diffs current vs baseline and fails on any path/method/param drift.
2. **Characterization tests first.** For each oversized route file, add `TestClient` tests exercising every endpoint (happy path + one error path). Use `httpx.AsyncClient` + factory fixtures.
3. **Split models.py per aggregate.** Keep a shim: `from <service>.db.models import *` re-exports so existing imports keep working. One module per aggregate; `__tablename__` unchanged (no migration).
4. **Split schemas.py** similarly with a re-export shim.
5. **Extract service layer.** Each route handler delegates to a `*Service` class injected via `Depends`. Handlers shrink to ≤30 LOC.
6. **Repository extraction** from the giant repository file; one class per aggregate.
7. **`mypy --strict` scoped to new packages first.** Expand outward via `mypy.ini` per-module overrides.
8. **Tests:** unit tests per service (mocked repo), repo tests against a transactional fixture (real Postgres), integration tests at API layer.
**Gotchas we hit:**
- Tests that patch module-level symbols (e.g. `SessionLocal`, `scan_X`) break when you move logic behind `Depends`. Fix: re-export the symbol from the route module, or have the service lookup use the module-level symbol directly so the patch still takes effect.
- `from __future__ import annotations` can break Pydantic TypeAdapter forward refs. Remove it where it conflicts.
- Sibling test file status codes drift when you introduce the domain-error translator (e.g. 422 → 400). Update assertions in the same commit.
**Verification:** all pytest files green. Characterization tests green. Contract test green (no drift). `mypy` clean on new packages. Coverage ≥ baseline + 10%.
### Phase 2 — Go backend
**Critical targets:** any handler / store / rules file over 500 LOC.
**Steps:**
1. OpenAPI/Swagger snapshot (or generate via `swag`) → contract tests.
2. Generate handler-level tests with `httptest` for every endpoint pre-refactor.
3. Define hexagonal layout (see AGENTS.go.md). Move incrementally with type aliases for back-compat where needed.
4. Replace ad-hoc error handling with `errors.Is/As` + a single `httperr` package.
5. Add `golangci-lint` strict config; fix new findings only (don't chase legacy lint).
6. Table-driven service tests. `testcontainers-go` for repo layer.
**Verification:** `go test ./...` passes; `golangci-lint run` clean; contract tests green; no DB schema diff.
### Phase 3 — Frontend (Next.js)
**Biggest beast — expect this to dominate.** Critical targets: `page.tsx` / monolithic types / API routes over 500 LOC.
**Per oversized page:**
1. Extract presentational components into `app/<route>/_components/` (private folder, Next.js convention).
2. Move data fetching into Server Components / Server Actions; Client Components become small.
3. Hooks → `app/<route>/_hooks/`.
4. Pure helpers → `lib/<domain>/`.
5. Add Vitest unit tests for hooks and pure helpers; Playwright smoke tests for each top-level page.
**Monolithic types file:** use barrel re-export pattern.
- Create `types/` directory with domain files.
- Create `types/index.ts` with `export * from './<domain>'` lines.
- **Critical:** TypeScript won't allow both `types.ts` AND `types/index.ts` — delete the file, atomic swap to directory.
**API routes (`route.ts`):** same router→service split as backend. Each `route.ts` becomes a thin handler delegating to `lib/server/<domain>/`.
**Endpoint preservation:** if any internal route URL changes, grep every consumer (SDK packages, developer portal, sibling apps) and update in the same change.
**Gotchas:**
- Pre-existing type bugs often surface when you try to build. Fix them as drive-by if they block your refactor; otherwise document in a separate follow-up.
- `useClient` component imports from `'../provider'` that rely on re-exports: preserve the re-export or update importers in the same commit.
- Next.js build can fail at page-manifest stage with unrelated prerender errors. Run `next build` fresh (not from cache) to see real status.
- **SDK packages (0 tests):** add Vitest unit tests for public surface before/while splitting.
- **Manager/Client classes:** extract config defaults, side-effect helpers (e.g. Google Consent Mode wiring), framework adapters into sibling files. Keep the main class as orchestration.
- **Framework adapters (React/Vue/Angular):** each component/composable/service/module goes in its own sibling file; the entry `index.ts` is a thin barrel of re-exports.
- **Doc monoliths (`index.md` thousands of lines):** split per topic with mkdocs nav.
### Phase 5 — CI hardening & governance
1. Promote `loc-budget` from warning → blocking once the allowlist has drained to legitimate exceptions only.
2. Add mutation testing in nightly (`mutmut` for Python, `gomutesting` for Go).
3. Add `dependabot`/`renovate` for npm + pip + go mod.
4. Add release tagging workflow.
5. Write ADRs (`docs/adr/`) capturing the architecture decisions from phases 1–3.
6. Distill recurring patterns into `.claude/rules/` updates.
---
## 3. Agent prompt templates
When the work volume is big, parallelize with subagents. These prompts were battle-tested in practice.
### 3.1 Backend route file split (Python)
> You are working in `<repo>` on branch `<branch>`. Every source file must be under 500 LOC (hard cap enforced by a PreToolUse hook); soft target 300.
>
> **Task:** split `<path/to/file>_routes.py` (NNN LOC) following the router → service → repository layering described in `AGENTS.python.md`.
>
> **Steps:**
> 1. Snapshot the relevant slice of `/openapi.json` and add a contract test that pins current behavior.
> 2. Add characterization tests for every endpoint in this file (happy path + one error path) using `httpx.AsyncClient`.
> 3. Extract each route handler's business logic into a `<domain>Service` class in `<service>/services/<domain>_service.py`. Inject via `Depends(get_<domain>_service)`.
> 4. Raise domain errors (`NotFoundError`, `ConflictError`, `ValidationError`), never `HTTPException`. Use the `translate_domain_errors()` context manager in handlers.
> 5. Move DB access to `<service>/repositories/<domain>_repository.py`. Session injected.
> 6. Split Pydantic schemas from the giant `schemas.py` into `<service>/schemas/<domain>.py` if >300 lines.
>
> **Constraints:**
> - Behavior preservation. No route rename/method/status/schema changes.
> - Tests that patch module-level symbols must keep working — re-export the symbol or refactor the lookup so the patch still takes effect.
> - Run `pytest` after each step. Commit each file as its own commit.
> - Push at end: `git push origin <branch>`.
>
> When done, report: (a) new LOC counts, (b) test results, (c) mypy status, (d) commit SHAs. Under 300 words.
### 3.2 Go handler file split
> You are working in `<repo>` on branch `<branch>`. Hard cap 500 LOC.
>
> **Task:** split `<path>/handlers/<domain>_handler.go` (NNN LOC) into a hexagonal layout per `AGENTS.go.md`.
>
> **Steps:**
> 1. Add `httptest` tests for every endpoint pre-refactor.
> 3. Create `internal/service/<aggregate>/` with business logic implementing domain interfaces.
> 4. Create `internal/repository/postgres/<aggregate>/` splitting queries by group.
> 5. Thin handlers under `internal/transport/http/handler/<aggregate>/`. Each handler ≤40 LOC. Error mapping via `internal/platform/httperr`.
> 6. Use `errors.Is` / `errors.As` for domain error matching.
>
> **Constraints:**
> - No DB schema change.
> - Table-driven service tests. `testcontainers-go` (or compose Postgres) for repo tests.
> - `golangci-lint run` clean.
>
> Report new LOC, test status, lint status, commit SHAs. Under 300 words.
### 3.3 Next.js page split (the one we parallelized heavily)
> You are working in `<repo>` on branch `<branch>`. Every source file must be under 500 LOC (hard cap enforced by a PreToolUse hook); soft target 300. Other agents are working on OTHER pages in parallel — stay in your lane.
>
> **Task:** split the following Next.js 15 App Router client pages into colocated components so each `page.tsx` drops below 500 LOC.
> - Extract each logically-grouped section (forms, tables, modals, tabs, headers, cards) into its own component file. Name files after the component.
> - Create `_hooks/` for custom hooks that were inline.
> - Create `_types.ts` or `_data.ts` for hoisted types or data arrays.
> - Remaining `page.tsx` wires extracted pieces — aim for under 300 LOC, hard cap 500.
> - Preserve `'use client'` when present on original.
> - DO NOT rename any exports that other files import. Grep first before moving.
>
> **Constraints:**
> - Behavior preservation. No logic changes, no improvements.
> - Imports must resolve (relative `./_components/Foo`).
> - Run `cd admin-compliance && npx next build` after each file is done. Don't commit broken builds.
> - DO NOT edit `.claude/settings.json`, `scripts/check-loc.sh`, `loc-exceptions.txt`, or any `AGENTS.*.md`.
> - Commit each page as its own commit: `refactor(admin): split <name> page.tsx into colocated components`. HEREDOC body, include `Co-Authored-By:` trailer.
> - Pull before push: `git pull --rebase origin <branch>`, then `git push origin <branch>`.
>
> **Coordination:** DO NOT touch `<list of pages other agents own>`. You own only `<your pages>`.
>
> When done, report: (a) each file's new LOC count, (b) how many `_components` were created, (c) whether `next build` is clean, (d) commit SHAs. Under 300 words.
>
> If the LOC hook blocks a Write, split further. If you hit rate limits partway, commit what's done and report progress honestly.
### 3.4 Monolithic types file split (TypeScript)
> `<repo>`, branch `<branch>`. Hard cap 500 LOC.
>
> **Task:** split `<lib>/types.ts` (NNNN LOC) into per-domain modules under `<lib>/types/`.
>
> **Steps:**
> 1. Identify domain groupings (enums, API DTOs, one group per business aggregate).
> 2. Create `<lib>/types/` directory with `<domain>.ts` files.
> 3. Create `<lib>/types/index.ts` barrel: `export * from './<domain>'` per file.
> 4. **Atomic swap:** delete the old `types.ts` in the same commit as the new `types/` directory. TypeScript won't resolve both a file and a directory with the same stem.
> 5. Grep every consumer — imports from `'<lib>/types'` should still work via the barrel. No consumer file changes needed unless there's a name collision.
> 6. Resolve collisions by renaming the less-canonical export (e.g. if two modules both export `LegalDocument`, rename the RAG one to `RagLegalDocument`).
1. **Own disjoint paths.** Give each agent a bounded list of files under specific directories. Spell out the "do NOT touch" list explicitly.
2. **Always instruct `git pull --rebase origin <branch>` before push.** Agents running in parallel will push and cause non-fast-forward rejects without this.
3. **Instruct `commit each file as its own commit`** — not a single mega-commit. Makes revert surgical.
4. **Ask for concise reports (≤300 words):** new LOC counts, component counts, build status, commit SHAs.
5. **Tell them to commit partial progress on rate-limit.** If they don't, their partial work lives in the working tree and you have to chase it with `git status` after. (We hit this — 4 agents silently left uncommitted work.)
6. **Don't give an agent more than 2 big files at once.** Each page-split in practice took ~10–20 minutes + ~150k tokens. Two is a comfortable batch.
7. **Reference a prior "done" example.** Commit SHAs are gold — the agent can inspect exactly the style you want.
8. **Run one final `next build` / `pytest` / `go test` yourself after all agents finish.** Agent reports of "build clean" can be scoped (e.g. only their files); you want the whole-repo gate.
---
## 4. Workflow loop (per file)
```
1. Read the oversized file end to end. Identify 3–6 extraction sections.
2. Write characterization test (if backend) — pin behavior.
3. Create the sibling files one at a time.
- If the PreToolUse hook blocks (file still > 500), split further.
4. Edit the root file: replace extracted bodies with imports + delegations.
5. Run the full verification: pytest / next build / go test.
6. Run LOC check: scripts/check-loc.sh <changed files>
7. Commit with a scoped message and a 1–2 line body explaining why.
8. Push.
```
## 5. Commit message conventions
```
refactor(<area>): <one-line what, not how>
<optional 1-3 sentence body: what split changed + verification result>
<LOC table: before → after per file>
<non-behavior changes flagged as drive-by fixes, with reason>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
```
Markers that unlock pre-commit guards:
- `[migration-approved]` — allows changes under `migrations/` / `alembic/versions/`.
- `[guardrail-change]` — allows changes to `.claude/settings.json`, `.claude/rules/loc-exceptions.txt`, `scripts/check-loc.sh`, `scripts/githooks/pre-commit`, or any `AGENTS.*.md`.
Good examples from our session:
- `refactor(consent-sdk): split ConsentManager + framework adapters under 500 LOC`
- `refactor(compliance-sdk): split client/provider/embed/state under 500 LOC`
- DB schema / migrations — unless separate green-lit plan.
- New features. This is a refactor.
- Public endpoint renames without simultaneous consumer fix-up (exception: intra-monorepo URLs when you do the grep sweep).
- Unrelated dead code cleanup — do it in a separate PR.
- Bundling refactors across services in one commit — one service = one commit.
## 8. Memory / session handoff
If using Claude Code with persistent memory, save a `project_refactor_status.md` in your memory store after each phase:
- What's done (files split, LOC before → after).
- What's in progress (current file, blocker if any).
- What's deferred (pre-existing bugs surfaced but left for follow-up).
- Key patterns established (so next session doesn't rediscover them).
This lets you resume after context compacts or after rate-limit windows without losing the thread.
---
That's the whole methodology. Install Section 1, follow Section 2 phase-by-phase, use Section 3 to parallelize the grind. The guardrails do the policing so you don't have to remember anything.
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Sharang Parnerkar