A Singapore Government Agency Website

Claude Code best practices

The following practices are recommended by Anthropic for teams using Claude Code in collaborative or enterprise development environments. They were shared during the SHIP-HATS Claude Code Office Hours and reflect Anthropic’s current guidance, which may evolve as the product develops.

Teams may consider adopting these practices to help control costs, maintain code quality, and work consistently across developers.

Manage context and cost effectively

A larger context window increases both cost and the likelihood of the model losing focus. The following practices help manage context efficiently.

  • Start narrow. Let Claude pull in what it needs via file reads and subagents rather than front-loading everything.
  • Compact regularly to prevent context rot. Use /compact or enable auto-compact. A good practice is to keep the context window at around 40% usage. Check your current usage by typing /context.
  • Checkpoint long multi-stage work. Save state to a scratch file (CLAUDE.md or progress.md) and start fresh sessions against it. This reduces token usage and improves reasoning quality.

Choose the right level of autonomy

Consider matching the level of autonomy to the potential impact of the task, rather than its size.

  • Autonomous workflows are suitable when work is sandboxed — for example, a scratch branch, throwaway prototype, or container with easy rollback.
  • Supervised workflows are appropriate when the agent interacts with shared infrastructure, production configurations, or migrations where reversal is costly.
  • A middle ground is to use plan mode (Shift+Tab), where Claude Code proposes a plan for review before execution. This allows you to review intent once rather than reviewing every change individually.
  • Automated checks can serve as a safety net. A PostToolUse hook can run your linter, tests, or credential scanner automatically after each tool action.

SHIP-HATS note: Auto-approval is disabled in SHIP-HATS environments — Claude Code will prompt for confirmation on file operations and terminal commands. One option is to use plan mode (Shift+Tab) to review the proposed approach before stepping through execution.

👉 For details, see Hooks docs.

Maintain consistency across developers

Claude Code is only as consistent as the context it is given. Codify your team’s conventions in files that Claude reads automatically so that every developer’s agent works from the same baseline.

  • Check a root CLAUDE.md into the repo. Capture architecture rules, naming conventions, test patterns, and constraints (for example, “changes to X require updating Y”).
  • Layer per-directory CLAUDE.md files for subsystem-specific rules.
  • Pin shared slash commands and skills in .claude/ in the repo (not per-user) so that shared operations such as “generate a service” behave consistently across developers.
  • Maintain existing review processes. PR review, CI, and CODEOWNERS continue to apply. Claude-authored code should go through the same gates as human-written code.
  • Ensure traceability. Claude Code automatically adds a Co-Authored-By tag to commits. Ensure your team also configures commit signing per your organisation’s requirements so that agent-generated commits are auditable. See Agentic user responsibilities.

Review large codebase

Rather than manually feeding source files into the context, run Claude Code from the repository root and let it explore the codebase incrementally.

  • Start with architecture discovery. Ask Claude Code to explore the codebase, summarise the architecture, list the main modules and how they communicate, and write the output to an ARCHITECTURE.md file. This summary serves as durable context for subsequent questions and for onboarding new developers.

  • Review module-by-module using subagents. Spawn one subagent per service or module, have each report on security, performance, and dead-code findings, then synthesise the results. Subagents keep each context window focused and cost-efficient; the orchestrator only processes summaries.

  • Use extended thinking (think hard) on the synthesis step, where cross-cutting analysis adds the most value, rather than on routine per-module scans.

    👉 For details, see Common workflows.

Select right subagent model

Use lighter models for parallel scans and reserve more capable models for synthesis. Set model: in the subagent’s frontmatter to control this.

  • Use Haiku for parallel scans to reduce cost; use Sonnet or Opus for the orchestrator and synthesis steps.

  • If unspecified, subagents inherit the parent session’s model.

    👉 For details, see Subagents docs.

Support

PREVIOUS
AI Impact Dashboard
NEXT
Set up Cursor
Chat with me!
Bot Launcher