Configuring Claude Code for Team Development

The project-root CLAUDE.md — committed to version control. This is Level 2 in the hierarchy and is shared by every team member who clones the repo. Contains universal coding standards (Python 3.11+, type annotations, Google docstrings, naming conventions, async guidelines, commit format) plus planning mode decision guidance.

• Uses @path syntax to import 3 rules files: @./.claude/rules/api-conventions.md, @./.claude/rules/testing.md, @./.claude/rules/security.md
• @ must be immediately adjacent to the path (no space) or it is treated as literal text
• Maximum nesting depth for @path imports is 5 levels
• Planning mode section: large refactors (3+ files), architectural decisions, unfamiliar code, debugging, security changes → use planning mode. Typo fixes, single tests → direct execution

Path-specific rule file loaded only when editing files under src/api/**/*. The YAML frontmatter paths: key triggers conditional loading. Without this file, a developer editing a CSS file would still load API rules — wasting context window tokens on irrelevant content.

# YAML frontmatter — triggers conditional loading
---
paths: ["src/api/**/*"]
---

• Async/await required for all route handlers (no synchronous handlers)
• Standard response wrapper: {"success": bool, "data": any, "error": str|null}
• Pydantic validation on all inputs — never accept raw dict
• Specific exceptions only — never bare except Exception
• HTTP status codes: 200/201/422/404/401/403/503
• Rate limiting decorator required on all public endpoints

Testing rule file with a multi-glob paths pattern. Test files can live anywhere in the project tree; this file targets them by naming convention rather than directory, ensuring the testing rules apply regardless of where the test is located.

---
paths: ["**/*.test.py", "**/test_*.py", "**/*_test.py"]
---

• GIVEN / WHEN / THEN docstring required on every test function
• Factory functions for all test data — no hardcoded inline data
• Real database required — no DB mocking (mocking hides integration bugs)
• Class-based test grouping (one class per endpoint/function)
• Minimum 80% line coverage enforced in CI
• Fixture scope guidance: function-scope DB sessions, module-scope clients, session-scope schema creation

Security rule file that loads for both API and auth directories — multi-path frontmatter. Security rules apply wherever inputs enter the system and wherever tokens/credentials are handled.

---
paths: ["src/api/**/*", "src/auth/**/*"]
---

• Never log sensitive data (passwords, tokens, PII)
• Parameterized queries only — no string-formatted SQL (SQL injection prevention)
• Auth dependency on every protected route: Depends(get_current_user)
• Sanitize all external inputs via Pydantic first
• Secret management: ${ENV_VAR} syntax only — real values in .env
• CORS: never allow_origins=["*"] in production

The code-review skill invoked via /code-review src/api/. Uses context: fork to run in an isolated subagent — all intermediate work (reading files, running grep) happens in that subagent's context. Only the final report returns to the main session.

---
context: fork
allowed-tools: ["Read", "Grep", "Glob"]
argument-hint: "Path to file or directory to review"
---

• context: fork — isolated subagent; intermediate work discarded after completion; main session gets only the report (~300 tokens)
• allowed-tools: ["Read","Grep","Glob"] — read-only; no Write, no Bash; principle of least privilege
• Reviews 4 categories: SECURITY → PERFORMANCE → STYLE → TESTING (always in this order)
• Output format: severity level (CRITICAL/HIGH/MEDIUM/LOW) + code snippet + fix recommendation
• SUMMARY section: total findings by severity + files reviewed

The test-gen skill invoked via /test-gen src/api/users.py. Demonstrates why the allowed-tools list differs from code-review: test generation must create files, so Write is added. But Bash is still excluded — the skill writes tests but does not run them.

---
context: fork
allowed-tools: ["Read", "Grep", "Glob", "Write"]
argument-hint: "Path to source file to generate tests for"
---

• Adds Write vs. code-review — must create test file
• Still no Bash — does not need to execute tests
• Still no Edit — Write is sufficient for new file creation
• Process: Read source → Grep existing tests → Read testing.md rules → Write complete test file

Team-shared MCP server configuration. Committed to version control. Every developer who clones the repo gets these 3 servers automatically: GitHub (code search, PRs), PostgreSQL (team dev DB), Slack (notifications). Real credentials use ${ENV_VAR} placeholders — actual values in each developer's local .env file.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

• ${ENV_VAR} is mandatory — real tokens in .mcp.json are permanently embedded in Git history
• Compromised token procedure: rotate immediately → git filter-branch or BFG to remove from history → audit access logs

Template for the personal ~/.claude.json override file. Committed to VCS as a template so developers know what to set up, but the actual ~/.claude.json with real credentials is never committed.

• For personal local dev database (different URL from team shared DB)
• For personal tools not ready to propose to the team
• For experimental MCP integrations being evaluated before team adoption
• Developer copies to ~/.claude.json and fills in real values locally

The compliant API file. Every element traces to a specific rule. Used to demonstrate what Claude Code should produce when all rules files are active.

The intentional violations file. Run /code-review src/api/orders.py to see what the code-review skill catches. Contains 8+ violations across 3 endpoints.

Compliant test file demonstrating all testing conventions: GIVEN/WHEN/THEN docstrings, factory functions, real DB fixture (no mocking), class-based grouping.

• make_user_payload(**overrides) factory — schema changes require updating ONE place
• db_session fixture uses real TestAsyncSession + rollback for clean state
• Two test classes: TestUserCreation, TestUserRetrieval
• Tests cover: valid payload, duplicate email, missing field, non-admin forbidden, existing user, unknown ID, unauthenticated request