A CLAUDE.md file gives Claude Code project context and working instructions. When it exists in the repository, it is loaded at the start of each session, so future sessions need less repeated orientation. section 5.12 section 5.4
Create guidance that helps a future session start work:
- Use /init to draft the file from an established codebase or project documentation; choose a project-level file when its instructions should benefit everyone working on the repository. section 5.4 section 5.5
- Include practical details such as the repository layout, local development and deployment workflows, open decisions, and conventions that are easy to get wrong. section 5.5
- Review questions and discrepancies raised during setup, and confirm which sources are authoritative. Claude can use tools and access files, so permissions—not a sandbox—provide protection; stricter modes can slow work. section 5.5 section 5.12
A project-specific /init prompt
/init — this repo will build out the whole app specced in the docs/design folder. We will use Docker to run the stack locally, and package with Helm for deployment to Kubernetes. section 5.5
Listing 5.1 The CLAUDE.md file — a guide for AI agents joining the project
# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## What this is CollabHub — team chat + collaborative canvas. Five Python backend services and a React SPA, specified in `docs/design/` and being built out from that spec. Run locally with Docker Compose; deploy to Kubernetes with Helm. **Read `docs/design/00-platform-conventions.md` before writing or changing any service code.** It is the authoritative cross-service contract (errors, pagination, auth, IDs, jobs, config, observability). Where a per-service doc disagrees with it, it wins. Per-service specs are `docs/design/01`–`06`.
A sample file shows how to combine a project description, workflow details, and an explicit instruction about which cross-service conventions to read first. section 5.5

