Practical checklist

Claude Code setup checklist for a repeatable repository

A useful setup is more than a long CLAUDE.md. Separate durable instructions, permission boundaries, deterministic automation, and workflows that still require judgment.

1. Give Claude accurate project instructions

• Keep a project-level CLAUDE.md in version control. Include facts that cannot reliably be inferred from filenames.
• Name the real commands. Record the exact install, development, lint, type-check, test, build, and migration commands that apply.
• Explain important boundaries. Identify generated files, ownership boundaries, irreversible operations, and unusual directories.
• Define done. State which checks must pass and which changed behavior must be exercised before handoff.
• Remove generic advice. “Write clean code” adds little. “Run npm run typecheck after changing API types” is testable.

Keep always-loaded guidance concise. Move occasional procedures and long reference material into focused skills or linked documentation.

2. Choose permissions for the environment

• Start with the least authority that still permits the task.
• Use different policies for interactive local work, unattended work, and CI.
• Keep credentials out of committed configuration; reference environment variable names instead of values.
• Review network, publishing, deployment, database, and destructive Git operations separately from routine development commands.
• Treat permission allowlists as one layer, not a complete security boundary.

A permissive profile may be reasonable in a disposable repository and unreasonable in a production checkout. The repository and task determine the boundary.

3. Use hooks for deterministic checks

Use a hook when an action should run on a lifecycle event without asking the model to remember it: formatting an edited file, rejecting selected command patterns, scanning staged changes, or running a fast test before stopping.

• Read every hook before enabling it.
• Document the event and matcher that cause it to run.
• Test both the allowed path and the blocked or failing path.
• Decide what happens when a dependency is missing or the hook itself fails.
• Keep stop-time checks fast enough that people will leave them enabled.

4. Package repeated work at the right layer

If a procedure keeps making CLAUDE.md longer, it is probably a skill. If a rule must be enforced rather than remembered, it needs a hook, permission rule, sandbox, or existing repository control.

5. Verify the setup before trusting it

1. Open a disposable branch or test repository.
2. Confirm Claude sees the intended project instructions.
3. Exercise every installed skill and subagent with a small representative task.
4. Trigger each hook deliberately and inspect the result.
5. Confirm denied actions are denied and ordinary development commands still work.
6. Run normal repository checks outside the agent as a control.
7. Record version-sensitive behavior and the documentation used to verify it.

Configuration that merely parses is not yet verified. An acceptance test must exercise the behavior you expect to rely on.

6. Make the setup reproducible for the team

• Commit shared project configuration and review it through normal pull requests.
• Keep personal credentials and machine-specific overrides outside the repository.
• Document required local tools and failure behavior.
• Assign an owner for configuration drift and version updates.
• Re-run trigger tests after material tooling or configuration changes.

A small definition of ready

A new contributor can clone the repository, identify the active agent configuration, run its documented checks, and explain which actions still require approval. Unknowns remain explicit instead of being replaced with optimistic defaults.

Setup FAQ