Claude Code¶
Claude Code is a command-line tool from Anthropic that allows developers to delegate coding tasks to Claude directly from their terminal. It can read and change files, run commands and work through a task with you, rather than just chat about it. At CDS, we use Claude Code as a core part of our development workflow.
We don't run it straight out of the box. Everyone at CDS uses Claude Code through CDS Claude Code, our own shared setup, which adds the safeguards our clients' work needs and the skills our teams have built up. The general guidance on this page applies to anyone using Claude Code. The sections on CDS Claude Code describe how we run it here.
Why we use it¶
Claude Code allows us to work faster without sacrificing quality. It's particularly effective for:
- Scaffolding new projects, including boilerplate, configuration files and folder structures
- Writing and editing content, such as the Markdown pages in this handbook
- Writing new code from requirements, and refactoring or modernising legacy code
- Debugging, by explaining errors, suggesting fixes and working through complex issues
- Writing documentation such as READMEs, ADRs and inline comments
- Testing, by writing test suites and test cases and running them to verify changes
- Prototyping, to prove out a technical approach quickly before we commit to it
CDS Claude Code¶
CDS Claude Code is a toolkit our own people build and maintain. It installs Claude Code with settings we've agreed as a firm, connects it to the systems we work in every day, and carries the skills, agents and working practices our teams have found worth sharing. When someone works out how to do something well, they contribute it back, and everyone's setup picks it up automatically. Nobody has to solve the same problem twice.
What it adds¶
The toolkit adds plugins for the work we do most often. There are skills for reviewing pull requests to CDS standards, building estimates, triaging service desk tickets and drafting client status reports, and an onboarding companion for new joiners that draws on this handbook. Integration guides cover connecting Claude to the systems we use, including Azure DevOps, Azure, GitHub, Cloudflare and our service desk. There are also starter CLAUDE.md templates for the stacks we build on most.
It also sets sensible defaults. New users start on the most capable model available to them, because a weaker default model is behind most disappointing first experiences of Claude Code. A shared permission baseline lets everyday commands run without constant approval prompts, while anything destructive still stops and asks.
How it keeps client work safe¶
Our clients trust us with critical services and sensitive data, so we run Claude Code with several layers of protection, each catching what the one before it misses:
- Shared guidance tells Claude how we work and what it must not do, and it's refreshed at the start of every session.
- A permission baseline lets routine commands through, asks before anything destructive and refuses a short list of actions outright.
- Guard hooks read each whole command before it runs and step in where a simple rule can't, for example to stop a command printing credentials, or to stop AI attribution appearing in a commit message.
- An encrypted credential store, built on the open-source sops and age tools, keeps API tokens out of conversations entirely. Claude is given a token's name, never its value.
- The toolkit itself goes through automated checks and required review before any change reaches anyone's laptop, because a change to it runs on every machine at CDS.
None of this replaces the engineer. The controls make mistakes much less likely and much easier to spot, but the person running the session stays accountable for what it does.
The rules we don't bend¶
A few things are firm requirements under our Claude Acceptable Use Policy rather than preferences.
We start every session with claude-secure, the toolkit's launcher, and not with a plain claude. The launcher makes our stored credentials available to that session only, so a token never has to be typed, pasted or saved in a file Claude can read.
We never switch off the approval prompts. Claude Code has a mode that bypasses them, and it isn't permitted for CDS work. If the prompts get in the way, we improve the shared baseline so everyone benefits.
Some things never go into a conversation, a prompt or a folder we point Claude at. That covers personal data, client material that's classified, confidential or restricted, credentials of any kind, unpublished technical or security designs for client systems, and internal commercial information such as pricing.
A person reviews anything before it reaches a client, and that person owns it. Our commits, pull requests and documents don't carry "generated with" lines or AI credits, because the work is ours and we stand behind it. That's about owning the work, not hiding the tool. We're open about using AI, as this page shows.
Getting set up¶
CDS staff: don't install Claude Code yourself
Install Claude Code through the CDS setup, not by following Anthropic's instructions or using npm. A standard install has none of the safeguards described above, and it isn't an approved way to run Claude Code on CDS work.
For CDS staff, setting up takes about 15 minutes:
- Get a Claude Code licence. Licences aren't assigned automatically, so ask your line manager to arrange one, ideally before your first day.
- Follow the setup guide on the CDS Claude Code wiki, which you can reach with your normal CDS sign-in. A single setup script installs Claude Code and the CDS toolkit and applies our settings.
- Start Claude Code once with
claudeand run/cds:secretsto create your encrypted credential store. This first session is the only one that should start with a plainclaude. - From then on, start every session with
claude-secure.
Once you're running, /cds:onboard introduces you to how CDS works and /cds:help shows what the toolkit can do. If something isn't working, /cds:doctor checks your setup and tells you what to fix, and the CDS Claude Code channel is there if you get stuck.
If you're not at CDS, Anthropic's Claude Code documentation covers a standard installation. The rest of this page applies whichever way you run it.
Setting up a project for success¶
Use CLAUDE.md files¶
Every repository should include a CLAUDE.md file at the root. This gives Claude Code the context it needs about the project, such as its tech stack, conventions, folder structure, build commands and any specific instructions.
A good CLAUDE.md file includes:
- An overview of what the project is, what it does and who it's for
- The tech stack, including languages, frameworks and key dependencies
- The repository structure, showing where things live and why
- Build and test commands, so the agent knows how to install, build, run and test the project
- Conventions for naming, branching, coding standards and pull requests
- Things to avoid, such as common mistakes, restricted features and known pitfalls
This handbook's own CLAUDE.md is a working example of the approach. It saves time on every session because the agent starts with full context instead of having to discover it. At CDS, you don't need to start from a blank page, because the toolkit's templates give a tested starting point for our most common stacks.
As your project evolves, keep the CLAUDE.md file current. Outdated instructions are worse than none, because they steer the agent in the wrong direction.
First run the tests¶
Any time you start a new session against an existing project, begin with:
Run the tests
These three words serve several purposes:
- The agent finds the test suite and learns how to run it, which makes it almost certain to run the tests again later to check its own work.
- Test harnesses report how many tests exist, which gives the agent a sense of the project's size and complexity.
- Having run the tests, the agent tends to write and extend tests for its own changes.
This is a small habit with outsized impact. It sets the tone for the entire session.
Working effectively with Claude Code¶
Be specific with your prompts¶
The more context you give, the better the output. Include details about the tech stack, coding standards, and the specific outcome you want. A vague prompt produces vague code.
Instead of:
Add a search feature
Try:
Add full-text search to the products API endpoint using the existing ElasticSearch service. Follow the same patterns used in the orders search endpoint. Include unit tests.
Use red/green TDD¶
Test-driven development is a natural fit for coding agents. The pattern is simple:
- Describe the behaviour you want and have the agent write the tests first.
- Run them and confirm they fail (red), which proves they're testing something new.
- Have the agent write the code that makes them pass (green), iterating until they do.
This approach protects against two common agent mistakes: writing code that doesn't work, and writing code that's unnecessary. It also builds a regression suite that catches future breakages.
Every good model understands "use red/green TDD" as shorthand for this entire discipline. It's a powerful four-word instruction.
Have the agent test its own work¶
Automated tests aren't the only form of verification. Have the agent manually exercise the code it's written:
- For an API, have it make
curlrequests against the running service - For a library, have it write and run small scripts that import and use the code
- For a web UI, have it use a browser automation tool such as Playwright to interact with the interface
Issues found through manual testing should then be fixed using red/green TDD, so they end up covered by the permanent test suite.
Iterate¶
Don't expect perfection on the first pass. Use Claude Code iteratively: generate, review, refine. This mirrors how we work as engineers anyway. If something isn't right, describe what's wrong and let the agent correct it.
Keep changes small¶
Agents can produce a lot of code quickly. Resist the temptation to let a single session grow into a massive changeset. Smaller, focused changes are easier to review, easier to test, and easier to revert if something goes wrong.
If a task is large, break it into stages. Have the agent work through them one at a time, verifying each step before moving on.
Keep one project per session¶
Start Claude Code from inside the project you're working on, never from a parent folder that holds several projects. Claude works in whatever folder it starts in, so a session launched above several clients' repositories can read, and act on, the wrong one. When you switch to a different client's work, switch folders and start a fresh session.
Review everything¶
Claude Code is a tool, not a replacement for engineering judgement. Always review generated code before committing. Treat it like a pull request from a colleague and give it the same scrutiny.
Watch for:
- Hallucinated APIs or methods, where the agent references functions or libraries that don't exist
- Subtle logic errors in code that looks plausible but doesn't handle edge cases correctly
- Security issues such as injection vulnerabilities, exposed secrets or overly permissive configuration
- Over-engineering, such as unnecessary abstractions, unused code or features you didn't ask for
- Style drift, where code doesn't match the project's existing conventions
The agent produces code quickly. Use the time you've saved to review it thoroughly.