# Claude Code development environment

> Four parts of a repository that an AI assistant works in well. Every node is a step with a prompt you can hand to Claude Code itself.

Turn a repository into a place where Claude Code is productive and safe: project memory it can read, commands and hooks that automate the routine, tools it can reach and the guardrails that keep every session verifiable.

A talent tree on Gradus (https://gradus.kazet.blog). Every step below links to its page as Markdown, with what the step means and the prompt to hand an AI assistant. The map is at https://gradus.kazet.blog/tree/claude-dev-environment and a step's page is at https://gradus.kazet.blog/tree/claude-dev-environment/step/<step id>.

## Start

- [Start here](https://gradus.kazet.blog/tree/claude-dev-environment/step/start-here.md): A repository where Claude Code is installed, signed in and has been run once.

## Project memory: CLAUDE.md, docs, conventions

- [Project CLAUDE.md](https://gradus.kazet.blog/tree/claude-dev-environment/step/project-claude-md.md): Write a CLAUDE.md at the repository root: what the project is, the conventions that are not obvious from the code and how to build and test it.
- [Global preferences](https://gradus.kazet.blog/tree/claude-dev-environment/step/global-preferences.md): Keep personal preferences that apply to every project (commit style, language, prose rules) in the user-level CLAUDE.md, not in the repository.
- [Knowledge base in docs](https://gradus.kazet.blog/tree/claude-dev-environment/step/knowledge-base.md): Keep decisions, gotchas and data models in a docs directory with an index, so the assistant reads reasons and not just code.
- [Decision records](https://gradus.kazet.blog/tree/claude-dev-environment/step/decision-records.md): Record each non-obvious decision as a short dated note with the alternatives rejected, so later sessions do not relitigate it.

## Commands & hooks: Slash commands, hooks, skills, agents

- [Slash commands](https://gradus.kazet.blog/tree/claude-dev-environment/step/slash-commands.md): Turn the repeated prompts of this project into slash commands in .claude/commands so every session runs them the same way.
- [Hooks on tool calls](https://gradus.kazet.blog/tree/claude-dev-environment/step/hooks.md): Run formatters and checks automatically after the assistant edits a file, so formatting never depends on it remembering.
- [Custom skills](https://gradus.kazet.blog/tree/claude-dev-environment/step/custom-skills.md): Package multi-step procedures (deploying, cutting a release, onboarding a module) as skills with their own instructions and scripts.
- [Subagents](https://gradus.kazet.blog/tree/claude-dev-environment/step/subagents.md): Define focused subagents (reviewer, test writer, explorer) with narrow tool access for work that should run in parallel or in isolation.

## Tools & reach: MCP, IDE, headless runs

- [MCP servers](https://gradus.kazet.blog/tree/claude-dev-environment/step/mcp-servers.md): Connect the external systems this project depends on (issue tracker, database, docs) through MCP servers configured in the repository.
- [IDE integration](https://gradus.kazet.blog/tree/claude-dev-environment/step/ide-integration.md): Install the editor extension so diffs, diagnostics and selections flow between the editor and the assistant.
- [Headless and CI runs](https://gradus.kazet.blog/tree/claude-dev-environment/step/headless-runs.md): Run the assistant non-interactively from scripts and CI, with a fixed prompt, a fixed set of allowed tools and JSON output.

## Guardrails: Permissions, verify, review

- [Permission rules](https://gradus.kazet.blog/tree/claude-dev-environment/step/permission-rules.md): Allow the routine commands (tests, lint, git status) without prompts and deny the dangerous ones (force push, rm -rf, secrets) in the shared settings.
- [A single verify command](https://gradus.kazet.blog/tree/claude-dev-environment/step/verify-command.md): Provide one command that runs lint, type checks and tests so the assistant can prove its work is done.
- [Pre-commit verification](https://gradus.kazet.blog/tree/claude-dev-environment/step/pre-commit-verification.md): Run the verify command from a pre-commit hook so a broken commit cannot be made, by a person or an assistant.
- [Pull request review loop](https://gradus.kazet.blog/tree/claude-dev-environment/step/review-loop.md): Have every assistant-written change land through a pull request that a reviewer subagent and CI check before a person merges it.
- [Parallel sessions in worktrees](https://gradus.kazet.blog/tree/claude-dev-environment/step/parallel-worktrees.md): Run independent tasks in separate git worktrees so parallel sessions never edit the same checkout.