Policy

This document covers how we use Claude Code — what's allowed where, what security rules apply, which shared tools exist, and how to get good results day-to-day.

We're not restricting Claude Code for the sake of it. The point is to use it where it helps and be careful where mistakes are expensive to fix.

Move fast where we can afford to. Be deliberate where we can't.

Covered here:

• Where Claude Code can be used and how freely

• Security rules that apply everywhere

• The CLAUDE.md standard we use across projects

• Shared skills and agents everyone should use

• Practical workflow and prompting guidance

Not covered here:

• GDPR and data privacy obligations

• Other AI tools

We split usage into three zones. The zone tells you how much Claude Code autonomy is appropriate for that codebase.

Zone A — Free Zone: Frontends, CLIs, MCP Servers, Experiments

Applies to: Frontend apps (except our neuroflash app — see Zone B), CLIs, MCP servers, internal tools, prototypes, experiments built against our API.

Approach: Vibe coding is fine here. Let Claude scaffold, design, and implement freely. This is the zone where you move fast and iterate.

Examples:

• A React dashboard that calls our API

• A CLI tool for internal automation

• An MCP server that wraps our API for Claude Code agents

• A prototype to validate a feature idea

• A developer-facing internal tool

Authentication — required even in Zone A:
Any app that hits our API or exposes functionality to users must authenticate via our Zitadel Auth server. Zitadel supports OAuth2 and OIDC, and there are solid libraries for every stack we use — passport.js, next-auth, keycloak-js, oidc-client-ts for the frontend side, and equivalents for Python and Go on the backend. Claude Code is good at wiring up auth flows given a clear prompt, but always verify the token validation logic yourself. Do not ship an app that skips auth because it's a "quick prototype."

Rules that apply even in Zone A:

• All Zone A code going to production needs a security review skill run before deployment

• Vibe-coded production apps need a human-reviewed CLAUDE.md with security constraints

• Secrets and credentials never get hardcoded — put that rule in CLAUDE.md

• No copy-pasting real user data or production API responses into prompts

The spirit of Zone A:
Build fast. Let Claude scaffold things you wouldn't bother writing by hand. But own what you ship — "Claude wrote it" isn't a defence when something breaks.

Zone B — Supervised Zone: Backend Services & neuroflash app

Applies to: Backend services, APIs, business logic, data pipelines, anything that runs with elevated permissions or touches sensitive data — and our main neuroflash frontend app.

Why neuroflash app is Zone B: neuroflash app is our primary product interface. It has direct integration with our core API, handles real user data, and its quality directly affects customers. AI can still help here, but with the same oversight we apply to backend code.

Approach: Claude is your pair programmer, not the driver. You review every change. You're the engineer of record.

Examples:

• Any neuroflash app frontend component or page

• REST API endpoints

• Background jobs or workers

• Authentication and authorization logic

• Anything touching PII or financial data (for example Hubspot or Stripe integration)

• Terraform and infrastructure-as-code

Rules for Zone B:

• A CLAUDE.md MUST exist with explicit security constraints (see Section 4)

• No autonomous/headless mode on Zone B code without a human watching

• Every Claude-generated change gets human review before merge

• Security review skill is mandatory before any Zone B PR merges

• Architecture review skill required for new services, modules, or significant refactors

The spirit of Zone B:
Claude is fast but occasionally overconfident. Review everything. Especially the parts that look obviously correct.

Zone C — Restricted Zone: IAM, Security, Secrets

Applies to: IAM and permissions, secrets management, cryptography, core auth systems, anything that causes irreversible damage if wrong.

Approach: Claude can explain existing code, review for issues, and suggest changes. It cannot generate or modify Zone C code autonomously. You type the actual changes yourself.

Examples:

• IAM policies and role definitions

• Secret management scripts

• Production database schema migrations

• Cryptographic implementations

Rules for Zone C:

• Claude may suggest, never commit

• All suggestions get manually reviewed and hand-typed — no wholesale copy-paste

• No automated Claude Code pipelines on Zone C code, ever

• Security review mandatory before any Zone C merge

The spirit of Zone C:
The cost of a mistake here is too high. Use Claude to think, not to act.

Summary Decision Table

Not sure which zone applies? Try the Zone Radar to assess your project's risk profile interactively.

These apply in every zone, no exceptions.

3.1 Secrets & Credentials

MUST NOT: Hardcode API keys, passwords, tokens, or secrets anywhere
MUST NOT: Ask Claude to generate code with placeholder secrets like "YOUR_API_KEY"
MUST: Use environment variables or our secrets manager
MUST: Put this in every CLAUDE.md — "Never hardcode secrets, always use env vars"

3.2 Data Handling

MUST NOT: Share production data, real user data, or PII in prompts
MUST NOT: Paste database dumps or real API responses into sessions
MUST: Use anonymised or synthetic data when debugging
MUST: Treat the Claude Code session like a shared Slack channel — sanitise before posting

3.3 Third-Party Dependencies

MUST NOT: Accept Claude's package suggestions without checking:
  (a) Actively maintained
  (b) No known critical CVEs
  (c) Consistent with our existing dependency strategy
MUST: Run the dependency audit skill on anything Claude adds

3.4 Code Ownership

MUST: You own the code you merge — regardless of who or what wrote it
MUST NOT: Use "Claude wrote it" as a reason a bug or policy violation is not your problem
MUST: Review AI-generated code with the same eye you'd apply to a junior dev's PR

3.5 Confidentiality

MUST NOT: Share internal architecture diagrams, roadmaps, or unreleased product details in prompts
MUST NOT: Paste customer data, internal metrics, or pricing details into sessions

Every project that uses Claude Code needs a CLAUDE.md. It's the instruction file Claude reads at the start of every session. Without it, Claude guesses. With a good one, Claude works within your actual constraints.

4.1 Minimum Required Content

Every CLAUDE.md needs at least:

## Project
[One paragraph: what this service does and its role in the system]

## Stack
[Core tech: language, framework, database]

## Commands
- `[test command]` — run tests
- `[lint command]` — run linter
- `[build command]` — build the project

## Security Constraints
- MUST NOT hardcode secrets — use environment variables
- MUST NOT use `any` types in TypeScript
- MUST run tests before marking a task complete
- NEVER modify [list sensitive files or dirs] directly

## Structure
- [key directories and what lives in them]

## Conventions
- [coding style, naming, patterns to follow]

4.2 The Capability Level Standard

We use a maturity model for CLAUDE.md files. Aim for at least L3 within 30 days of starting Claude Code on any project.

Minimum by project type:

• Prototype / Experiment: L1 (L2 recommended)

• Active Zone A project: L2 (L3 recommended)

• Zone B backend or neuroflash app: L3 minimum

• Shared internal platform: L4 minimum

4.3 The backbone.yml Pattern (L5 and above)

For larger projects or monorepos, add a backbone.yml to give Claude a map of the codebase upfront. This eliminates what you might call the exploration tax — tokens wasted while Claude blindly searches directories to find the config it needs.

# backbone.yml
version: 1

structure:
  config: config/
  src: src/
  tests: tests/
  docs: docs/

conventions:
  test_pattern: "*.test.ts"
  config_format: yaml

boundaries:
  never_modify:
    - .env
    - migrations/
    - vendor/

Wire it into CLAUDE.md:

## Initialization
Read `backbone.yml` before searching or modifying anything.
BEFORE running `find`, `grep`, or `ls` — read `backbone.yml` first. All paths are already there.

4.4 CLAUDE.md Maintenance

• Treat CLAUDE.md as code — update it when the project structure changes

• A stale CLAUDE.md is worse than none. It gives Claude confident wrong information.

• Assign a CLAUDE.md owner per team (usually the tech lead)

• Review and update it as part of every sprint retro

Claude Code supports skills — reusable agent workflows stored in .claude/skills/ that anyone can invoke. The following are company-standard. They should be in every active repo.

All shared skills live in [your-org]/claude-skills. Below is the catalog.

5.1 Code Review Skill

Invocation: /code-review
Purpose: Performs a thorough automated code review before human review.
What it checks:

• Logic correctness and edge cases

• Code style and consistency with project conventions

• Duplication and opportunities for abstraction

• Readability and maintainability

• Obvious performance issues

• Missing error handling

When to use: Before opening any PR. Treat it as a first-pass review that catches the obvious before a human looks.

Example output format:

## Code Review — src/auth/service.ts

### Critical Issues
- Line 47: Missing null check before accessing `user.profile`

### Suggestions
- Line 23-31: This logic is duplicated in `billing/service.ts` — consider extracting

### Style
- Line 15: Variable name `d` is not descriptive — suggest `expiryDate`

5.2 Security Review Skill

Invocation: /security-review
Purpose: Scans for common security vulnerabilities and policy violations.
What it checks:

• Hardcoded secrets or credentials (even in tests)

• SQL injection, XSS, CSRF exposure

• Insecure dependencies (known CVEs)

• Authentication and authorization gaps

• Insecure defaults (e.g., CORS wildcard, debug mode in production)

• Data exposure risks (logging PII, error messages with stack traces)

• Input validation gaps

When to use: Mandatory for all Zone B and Zone C PRs. Strongly recommended for all Zone A production deployments.

Important: This skill surfaces risks — it does not guarantee security. A passing skill result is not a substitute for a human security review on sensitive code.

5.3 Architecture Review Skill

Invocation: /architecture-review
Purpose: Evaluates whether new code fits the existing architecture and flags drift.
What it checks:

• Layer violations (e.g., business logic leaking into controllers)

• Circular dependencies

• Consistency with established patterns

• API contract hygiene

• Module boundary violations

• Over-engineering or under-engineering relative to requirements

When to use: New services, new modules, significant refactors, or when introducing a new pattern.

5.4 QA / Test Generation Skill

Invocation: /generate-tests
Purpose: Identifies missing test coverage and generates test cases.
What it produces:

• List of untested paths and edge cases

• Suggested test cases in the project's test framework

• Coverage gap analysis

When to use: After implementing a feature. Before marking a ticket done.

5.5 Documentation Skill

Invocation: /generate-docs
Purpose: Generates or updates inline documentation, README sections, and API docs.
What it produces:

• JSDoc / docstring annotations for undocumented functions

• README updates for new features

• Changelog entries

• API endpoint documentation

When to use: Before merging features. As part of sprint cleanup.

5.6 Refactor / Simplify Skill

Invocation: /simplify
Purpose: Reviews your diff for unnecessary complexity, duplication, and readability issues. Applies fixes directly.
What it checks:

• Reuse opportunities (extracted functions, shared utilities)

• Naming inconsistencies

• Structural problems

• Redundant operations and overly verbose logic

Note: /simplify is a built-in Claude Code command since version 2.1.63. It analyses your current diff and applies edits directly — not just suggestions.

When to use: After completing a feature, before requesting review.

5.7 Dependency Audit Skill

Invocation: /audit-dependencies
Purpose: Reviews any new dependencies added in a branch.
What it checks:

• Maintenance status (last release, open issues)

• Known vulnerabilities (CVEs)

• License compatibility

• Bundle size impact (for frontend)

• Whether an existing internal library already covers the use case

When to use: Any time Claude Code adds or updates a dependency.

Skill Location Convention

All company-wide skills are maintained at:

.claude/
└── skills/
    ├── code-review/
    │   └── SKILL.md
    ├── security-review/
    │   └── SKILL.md
    ├── architecture-review/
    │   └── SKILL.md
    ├── generate-tests/
    │   └── SKILL.md
    ├── generate-docs/
    │   └── SKILL.md
    ├── simplify/
    │   └── SKILL.md
    └── audit-dependencies/
        └── SKILL.md

Link from project CLAUDE.md:

## Skills
See `.claude/skills/` for available agent workflows.
Run `/code-review`, `/security-review`, or `/generate-tests` before submitting PRs.

6.1 Mandatory Pre-PR Checklist

Before opening any PR that includes Claude Code-assisted changes:

□ /simplify has been run on the diff
□ /code-review has been run and critical issues resolved
□ /security-review has been run (mandatory for Zone B and C)
□ Tests pass locally
□ CLAUDE.md is up to date if project structure changed
□ No secrets or sensitive data in commit history
□ Claude-suggested dependencies have been audited

6.2 Human Review Is Not Optional

The skills above are automation, not a substitute for a colleague's eyes.

When reviewing Claude-assisted code, specifically look for:

• Business logic that looks right but isn't — Claude is good at syntax, not always at domain nuance

• Over-engineering — Claude defaults to comprehensive; sometimes simpler is the right call

• Subtle security issues that pattern matching misses

• Conventions that aren't in CLAUDE.md and therefore aren't in the output

6.3 CI/CD Integration

Security review and test skills should run in CI for Zone B services. See Section 14 for GitHub Actions patterns.