Welcome to the CDS Handbook¶

This is the public knowledge base for CDS. Here you'll find information about how we work, the tools and technologies we use, and what life is like as a consultant at CDS.

Who is this for?¶

Potential employees — get a transparent look at what working at CDS is really like, our values, and how we approach delivery.
Clients and partners — understand our expertise, our ways of working, and the standards we hold ourselves to.
CDS consultants — a shared reference for our practices, tools, and approaches.

Explore¶

About CDS¶

Learn about life at CDS and the values that guide us.

Life at CDS Our Values Our Behaviours

Ways of Working¶

Our delivery approach, agile practices, and how we run projects.

Agile Practices · Delivery Approach · Test Approach

Tools & Technologies¶

The tools and technologies we use and recommend as best practice.

Claude Code · Azure DevOps

Contributing¶

This handbook is maintained by CDS staff. If you work at CDS and want to contribute, see the Contributing Guide.

About CDS

About CDS¶

CDS is a consultancy where people genuinely enjoy the work they do and the people they work with. This section covers who we are, what we believe in, and what it's like to be part of the team.

Life at CDS — What to expect as a CDS consultant, how we learn and grow, and how we work together.

Our Values — The principles that guide how we deliver, collaborate, and make decisions.

Our Behaviours — The behavioural expectations we have of ourselves and our people.

Life at CDS¶

What to expect¶

CDS is a consultancy where people genuinely enjoy the work they do and the people they work with. We believe in creating an environment where consultants can do their best work, grow their skills, and have a real impact on the projects they deliver.

Learning and development¶

We invest in our people. Whether it's conference attendance, certifications, internal knowledge sharing sessions, or time to experiment with new technologies, we create space for continuous learning.

How we work together¶

We're a collaborative team. We share knowledge openly, support each other on projects, and make time for the social side of work too. This handbook is a great example of that — built and maintained by the whole team.

Want to know more?

If you're considering joining CDS, we'd love to hear from you. Reach out to our recruitment team to find out more about current opportunities.

Our Values¶

CDS has five core values. They are not aspirational — they describe how we actually work and how we expect every person at CDS to show up, regardless of role or seniority.

Tenacity¶

We are determined and diligent. It's natural to face obstacles and difficulties every day. We never flinch from them, never look for the path of least resistance. We take responsibility for all our actions and take pride in all our achievements.

Togetherness¶

We're united in our common purpose. A group of talented, like-minded individuals working collectively to transform our clients' organisations for the better.

Integrity¶

We always do what we say we will. When we talk to each other or to our clients, we are honest, open and accurate. Without exception. No excuses.

Curiosity¶

We are never afraid to ask, what if? or why? or how?. We are naturally and unashamedly inquisitive and intrigued to learn or discover a better way.

Challenging¶

We challenge the status quo. We positively and proactively challenge, looking for ways to improve, innovate and inspire.

All five values are expressed through specific behaviours at every level of the business. See Our Behaviours for the full framework.

Our Behaviours¶

At CDS, our values are brought to life through specific behaviours. This framework sets out what those behaviours look like at each seniority level — so that expectations are clear and career progression is transparent.

Seniority levels¶

Level	Brief description	Scope
Senior Leadership	Accountability for organisation-wide strategy, outcomes, and direction	Organisation
Principal	Highly experienced, V-shaped professionals providing leadership and deep expertise, with significant organisational accountability	Organisation
Lead	Experienced practitioners who are adaptable and flexible, with roles which contribute beyond the day-to-day to growing CDS	Department
Mid	Broad level covering skilled practitioners across the majority of "doing" roles in the business	Team
Associate	Entry level roles across disciplines and departments	Self

Tenacity¶

We are determined and diligent. We never look for the path of least resistance, and we take pride in all our achievements.

AssociateMidLeadPrincipalSenior Leadership

Practitioner Excellence

Demonstrates strong performance with core skill set and shows a desire to expand skills in other areas. Seeks opportunities to learn new techniques and approaches, building a solid foundation of capability.

Proactivity and Drive

Brings enthusiasm to their work and resilience when facing challenges, maintaining a constructive attitude that energises those around them. Approaches obstacles with determination and a problem-solving mindset.

Practitioner Excellence

Demonstrates strong performance with core skill set and actively looks to expand skills in other areas. Champions their core skill set within CDS, sharing expertise with colleagues and contributing to capability discussions.

Proactivity and Drive

Brings proactive energy to driving work forward, approaching obstacles as opportunities and maintaining team morale through difficult periods. Takes initiative to overcome challenges and inspires others through their determination.

Practitioner Excellence

Displays excellence with core skill set and is capable of taking on varied responsibilities. Champions their core skill set within CDS, serving as a go-to expert and mentor for others developing their capabilities.

Proactivity and Drive

Brings infectious optimism combined with determined execution, inspiring teams to push boundaries whilst keeping spirits high in complex situations. Creates momentum through their energy and maintains focus on ambitious goals.

Practitioner Excellence

Displays excellence with core skill set and is strong at taking on varied responsibilities. Champions their core skill set within CDS as a go-to person for others, setting standards for Practitioner Excellence and mentoring future experts.

Proactivity and Drive

Brings visionary drive that motivates the organisation, balancing ambitious goals with sustainable energy and fostering a culture where positivity fuels performance. Creates organisational momentum that inspires people to achieve exceptional results.

Practitioner Excellence

Sets the vision, ambition and direction for CDS including associated technical credibility across all disciplines — operations, commercial, client service, delivery, technology and strategy. Cultivates environments where expertise thrives, ensures standards are forward-looking and robust, and makes strategic decisions grounded in a deep understanding of our people, culture, technology, risk and client outcomes.

Proactivity and Drive

Brings constructive ambition and a calm resolve. Steadies the organisation through uncertainty, energises people with clarity and removes the noise. Maintains focus on long-term value even when faced with short-term pressures. Creates organisational momentum, not dependency.

Togetherness¶

We're united in our common purpose, working collectively to transform our clients' organisations for the better.

AssociateMidLeadPrincipalSenior Leadership

People-First Mindset

Willingly helps teammates, shares knowledge openly, and prioritises team success over personal recognition. Contributes positively to team dynamics and actively supports colleagues in achieving shared goals.

Commercial and Business Acumen

Shows awareness of how their work contributes to client value and business outcomes, asking questions to understand the commercial context of decisions. Demonstrates interest in the broader business impact of their activities.

People-First Mindset

Actively collaborates across teams and disciplines, breaking down silos and ensuring collective success over individual achievement. Builds bridges between different groups and fosters a culture of mutual support and shared ownership.

Commercial and Business Acumen

Understands project budgets and client commercial drivers, making decisions that balance delivery quality with cost-effectiveness. Contributes to commercial discussions and identifies opportunities to maximise client value within constraints.

People-First Mindset

Leads in a way that empowers teams and encourages working together, building collaborative cultures and recognising team contributions above individual wins. Creates environments where diverse perspectives are valued and collective success is celebrated.

Commercial and Business Acumen

Exercises strong commercial judgement across projects, identifying opportunities for value creation, managing complex budgets, and contributing to commercial discussions with confidence. Balances client needs with business sustainability and growth.

People-First Mindset

Thinks at an organisational level to eliminate hero culture, creating systems and environments where diverse teams achieve exceptional results together. Shapes how CDS operates to ensure collaborative success becomes embedded in everything we do.

Commercial and Business Acumen

Thinks strategically about commercial matters that shape client relationships and business direction, influencing major commercial decisions and identifying new market opportunities. Positions CDS for sustainable growth whilst maintaining client value focus.

People-First Mindset

Unifies the organisation. Dissolves internal barriers, removes friction, role-models collaboration across disciplines, and creates systems where individuals and teams succeed collectively rather than through isolated heroics. Understands that their behaviour, actions and decisions shape culture — and acts accordingly.

Commercial and Business Acumen

Thinks and acts like custodians of the business. Evaluates decisions through the lens of long-term sustainability, client value, risk and return. Ensures CDS remains financially resilient, strategically positioned, and commercially well-judged.

Integrity¶

We always do what we say we will. We are honest, open and accurate — without exception.

AssociateMidLeadPrincipalSenior Leadership

Integrity and Honesty

Acts with honesty in all interactions, speaking up when something doesn't feel right and admitting when they don't know something. Builds trust through transparent communication and ethical conduct in all situations.

Open Communication

Communicates clearly and proactively with teammates and clients, providing timely updates on progress and challenges. Receives feedback with openness and willingness to learn, asking clarifying questions to understand how to improve.

Integrity and Honesty

Acts with integrity in decision-making and client interactions, having difficult conversations when needed and building trust through transparency. Demonstrates ethical leadership in challenging situations and role-models honest communication.

Open Communication

Maintains transparent, frequent communication with clients and colleagues, proactively managing expectations and addressing issues before they escalate. Provides timely, specific feedback to colleagues that focuses on actions and outcomes, helping others improve whilst also seeking feedback on their own performance.

Integrity and Honesty

Maintains strong integrity in complex situations, role-modelling honest communication with colleagues and clients even under pressure, and creating psychologically safe environments. Sets the tone for teams and ensures standards are upheld consistently.

Open Communication

Sets the standard for clear, honest client and team communication, ensuring stakeholders are aligned and informed throughout engagements. Delivers challenging feedback with care and clarity, creating dialogue that drives improvement and regularly coaching others on how to give and receive feedback effectively.

Integrity and Honesty

Provides ethical leadership that sets the standard for the organisation, ensuring integrity is embedded in everything CDS does. Creates the conditions for ethical decision-making and transparent conduct across all levels of the business.

Open Communication

Establishes communication excellence as an organisational standard, ensuring transparency in all client and internal interactions. Models exceptional feedback practices across the organisation, fostering a culture where constructive challenge is expected and valued.

Integrity and Honesty

Upholds uncompromising ethical standards. Acts with independence of judgement, even when decisions are uncomfortable, complex or scrutinised. Creates an environment where truth can be spoken, concerns can be raised without fear, and transparency is the default, not an aspiration.

Open Communication

Creates organisational norms for transparent, courageous communication at all levels — with clients, across teams, and throughout leadership. Sets the behavioural standards and psychological safety that enables challenge, and ensures both communication and feedback flow vertically and horizontally as habitual practice.

Curiosity¶

We are never afraid to ask, what if? or why? or how?. We are inquisitive and intrigued to learn or discover a better way.

AssociateMidLeadPrincipalSenior Leadership

Adaptability

Remains flexible when priorities shift or approaches change, staying open to feedback and new ways of working. Embraces change as an opportunity to learn and demonstrates willingness to step outside their comfort zone.

Continuous Improvement

Displays curiosity about better ways of working, actively seeking feedback and learning from experiences to develop their skills. Shows initiative in identifying opportunities for personal development and skill enhancement.

Adaptability

Responds with agility to changing client needs and project dynamics, helping teams navigate uncertainty whilst maintaining momentum. Shows strong desire to take on responsibilities outside their comfort zone, embracing new challenges.

Continuous Improvement

Commits to improving processes and practices, experimenting with new approaches and sharing learnings with others. Identifies inefficiencies and takes action to address them, contributing to the evolution of team practices.

Adaptability

Shows resilience in complex, ambiguous situations, pivoting strategies when needed and helping others embrace change constructively. Comfortable operating outside their comfort zone and demonstrates versatility across varied responsibilities.

Continuous Improvement

Leads improvement initiatives, identifying systemic issues and implementing changes that benefit multiple teams or projects. Champions innovation and creates frameworks for sustainable improvement across the organisation.

Adaptability

Excels in navigating organisational change and market shifts, setting the tone for how CDS responds to uncertainty and evolves its approaches. Demonstrates strategic flexibility and is comfortable making decisions with imperfect information.

Continuous Improvement

Holds strategic vision for organisational improvement, championing innovation and establishing practices that elevate CDS's delivery excellence. Creates frameworks and systems that enable continuous evolution of capabilities and approaches.

Adaptability

Anticipates change rather than reacts to it. Adjusts strategies thoughtfully and brings people with them through uncertainty. Helps the organisation stay agile and match fit rather than defensive or reactive.

Continuous Improvement

Changes how the organisation works — not just how their part of it works. Identifies patterns, root causes and structural constraints, and addresses them. Stewards innovation by creating a safe space for experimentation, learning and organisational evolution. Improvement becomes cultural, not sporadic.

Challenging¶

We challenge the status quo. We positively and proactively look for ways to improve, innovate and inspire.

AssociateMidLeadPrincipalSenior Leadership

Leadership

Takes ownership of their own tasks and commitments, looking for opportunities to support others and contribute beyond their immediate responsibilities. Demonstrates accountability and seeks ways to add value to the team.

Client Obsessed

Shows awareness of customer needs and how their work impacts the end user or customer experience. Asks questions to understand client objectives and considers the customer perspective in their daily work.

Leadership

Leads initiatives and individuals, driving work forward and inspiring others through their actions and approach. Takes accountability for outcomes and empowers team members to take ownership of their contributions.

Client Obsessed

Maintains consistent focus on outcomes, making decisions that prioritise client success and advocating for customer needs. Builds strong working relationships with clients and anticipates their needs proactively. All decisions made have our clients at the centre.

Leadership

Leads teams and complex initiatives, taking accountability, creating environments where people thrive and delivering outcomes through others. Develops leadership capability in team members and shapes how work is approached and executed.

Client Obsessed

Possesses deep understanding of client and customer challenges, shaping approaches around value and building lasting client partnerships. Acts as a trusted adviser who anticipates client needs and delivers strategic insight. All decisions made have our clients at the centre.

Leadership

Leads across the organisation, taking strong accountability, influencing culture and direction, mentoring leaders, and shaping how CDS operates. Develops leadership capability at scale and ensures the organisation has the leadership strength needed for future success.

Client Obsessed

Maintains strategic focus that influences CDS's direction, ensuring client success remains central to how we grow and evolve. Shapes organisational strategy around deep understanding of client needs and market dynamics. All decisions made have our clients at the centre.

Leadership

Shapes direction, culture and consequence. Challenges organisational assumptions, invites challenge to their own thinking, and treats curiosity, challenge and opposing views as a sign of health, not disruption. Holds themselves and others to account for the long-term success of the company — even when it requires difficult decisions.

Client Obsessed

Maintains a strategic understanding of the markets and communities we serve, acting as trusted advisers rather than passive suppliers. Engages clients with courage and empathy — challenging assumptions, offering alternative perspectives, and guiding decisions that lead to better outcomes. Recognises that in the mission-critical environments we support, failure is not merely inconvenient but consequential.

Ways of Working

Ways of Working¶

How we deliver projects, run teams, and maintain quality. This section covers the practices and approaches that define how CDS operates on the ground.

Agile Practices — How we apply agile methodologies in practice, not just in theory.

Delivery Approach — Our end-to-end approach to delivering projects for clients.

Test Approach — Our automation-first testing strategy, tools, and quality practices.

Agile Practices¶

At CDS, we follow agile principles pragmatically. We don't enforce a rigid framework — we adapt our approach to fit the context of each engagement while maintaining consistency in the practices that matter.

Our approach¶

We typically work in two-week sprints, though we adjust cadence based on client needs and project context. The important thing is a regular rhythm of planning, delivery, and reflection.

Ceremonies we value¶

Sprint planning¶

We plan collaboratively with the whole team. Everyone has input into what we commit to and how we break down the work.

Daily standups¶

Short, focused check-ins to surface blockers and keep the team aligned. We keep these to 15 minutes or less.

Retrospectives¶

Every sprint ends with a retro. We use a variety of formats to keep them fresh, but the goal is always the same: what can we do better next time?

Show and tell¶

We demo working software to stakeholders regularly. It builds trust, surfaces feedback early, and keeps everyone aligned on progress.

Estimation¶

We use story points for relative sizing, not as a measure of time. We find this encourages better conversations about complexity and risk.

Flexibility is key

These are our defaults, not rules. We adapt to fit the client's existing processes where it makes sense, and we're always open to trying new approaches.

Delivery Approach¶

Our delivery approach is designed to be lightweight, effective, and adaptable. We focus on delivering value early and often, with strong communication throughout.

Engagement lifecycle¶

Discovery¶

Before we write any code, we invest time in understanding the problem. This typically involves stakeholder interviews, technical assessment, and defining clear success criteria.

Delivery¶

We deliver iteratively, with working software demonstrated regularly. We prioritise ruthlessly and focus on the highest-value items first.

Transition¶

We don't just build and leave. We ensure proper knowledge transfer, documentation, and support planning so that our clients can maintain and extend what we've built.

Documentation standards¶

We believe in documentation that is useful, not documentation for its own sake. At a minimum, every project should have:

A clear README with setup instructions
Architecture decision records (ADRs) for significant technical decisions
Runbooks for any operational processes
Up-to-date API documentation where applicable

Quality¶

Quality is built in, not bolted on. We practice code review, automated testing, and continuous integration as standard. We define a clear "definition of done" at the start of each engagement and hold ourselves to it.

Test Approach¶

Testing is fundamental to how we deliver at CDS. We take an automation-first approach, building quality in from the start rather than inspecting it in at the end. Our testing practices are modern, pragmatic, and shaped by real delivery experience.

The purpose of testing at CDS is to ensure faster feedback loops, earlier defect detection, and seamless support for CI/CD. Everything we do in testing is oriented around helping agile delivery squads build clear, maintainable, and scalable test automation.

Core principles¶

Automation first¶

We automate everything where possible. Automated tests run faster, catch regressions earlier, and free up people to focus on the exploratory and creative testing that machines can't do. If a test can be automated, it should be.

Automation is the default approach. Manual testing applies where automation is not feasible, or where it enhances coverage through methods such as exploratory testing. We define automation as part of the Definition of Done for each story and prioritise testability as a design requirement from story grooming onwards.

Shift left¶

We push testing as far left as we can. Developers write tests alongside their code, not after the fact. Testers are embedded early in the requirements and design stage, and we foster developer-tester collaboration for early feedback. Unit, API, and integration tests form the foundation of our automation — following the test pyramid model, where the base is broad and fast, and the peak is narrow and targeted.

Fail fast¶

We integrate tests into CI/CD pipelines to catch issues as early as possible. Builds fail on critical regression or non-functional test failures. Code doesn't progress until the issue is resolved — this is non-negotiable.

Keep it simple, reuse often¶

Test code should be consistent, scalable, and readable. The same coding standards and quality rules that apply to production code apply to test code. We build and maintain common automation libraries — shared utilities, logging and reporting wrappers, standard test data generators — so that teams aren't reinventing the wheel on every engagement. These shared resources are open to contributions from all teams.

The right tool for the situation¶

We don't mandate a fixed toolset across every engagement. Different clients, tech stacks, and project constraints call for different tools. We're experienced across a broad range of testing frameworks and choose the one that fits the situation, rather than forcing a one-size-fits-all approach.

Coverage as a risk indicator, not a gate¶

We track test coverage statistics because they're valuable for highlighting areas of risk — untested code paths, overlooked edge cases, and modules that have grown without corresponding test investment. But we deliberately don't enforce strict coverage gates. Hard thresholds encourage the wrong behaviour: teams write low-value tests to hit a number rather than meaningful tests that catch real defects. We'd rather have 70% coverage of well-written, targeted tests than 95% coverage of tests that assert nothing useful.

Scope of testing¶

Automation¶

The scope of our automation includes unit, component, API, integration, regression, smoke, security, accessibility, and performance tests, as well as automated acceptance tests tied to user stories. We prioritise business-critical, repetitive, and high-risk scenarios for automation first.

Test validation¶

Test validation focuses on where human judgement adds the most value: exploratory testing, UX/UI validation, accessibility auditing, and ad-hoc testing. High-value one-off scenarios that don't justify the cost of automation are also handled using appropriate testing techniques.

Types of testing¶

We apply multiple layers of testing to build confidence at every level of the system, following the test pyramid model.

Unit testing forms the foundation. Fast, isolated, and cheap to run, unit tests verify that individual components behave as expected. We use the appropriate framework for the language — xUnit and NUnit for .NET, Jest for JavaScript and TypeScript, pytest for Python, and equivalents elsewhere. Unit tests run on every commit and are expected to pass before code is merged.

API and integration testing verifies that components work together correctly. This is where we catch issues with data flows, service boundaries, and external dependencies. We use tools like Postman and Newman extensively for API-level testing, validating contracts, response structures, and error handling across service boundaries.

End-to-end testing validates complete user journeys through the system. We use Playwright as our primary tool for browser-based E2E testing — it's fast, reliable, and supports multiple browsers out of the box. E2E tests are powerful but expensive to maintain, so we focus them on critical user paths rather than trying to cover every permutation.

Performance testing ensures the system can handle expected (and unexpected) traffic. We baseline early in the sprint cycle, run load and stress tests post-merge on staging environments, and set performance SLAs for response times, throughput, and latency. Performance testing is built into the delivery lifecycle rather than left as a last-minute activity.

Security testing is integrated throughout the pipeline. We run static analysis (SAST) on commit and pull request, and dynamic testing (DAST) as part of nightly or full pipeline runs. Teams are educated on common vulnerabilities, with the OWASP Top 10 as a baseline.

Accessibility testing combines automated checks integrated into the UI pipeline with manual audits on high-traffic flows before release. Accessibility is not an afterthought — it's part of our standard testing scope.

Testing in the delivery lifecycle¶

Testing isn't a phase — it's woven into every stage of our agile delivery process.

Backlog grooming includes test scenarios and a testability review. How will we test this? What does "done" look like? What are the riskiest areas that need the most coverage? These questions shape the technical approach from the outset.

Sprint planning defines test automation tasks per story on the project board, split into test design and automation tasks so they're visible and estimated alongside development work.

During the sprint, we automate during development, not after. Developers write tests alongside their code. Tests run locally before pushing, and the CI pipeline validates them on every commit and pull request. Code reviews include reviewing the quality and coverage of tests, not just the production code. Teams build and use shared components where applicable.

Definition of Done includes unit, API, UI automation, and non-functional coverage. A story isn't done until it's tested.

Sprint review includes a demo of test coverage, giving the team and stakeholders visibility of quality alongside functionality.

Exploratory testing complements the automated suite throughout. Skilled testers think creatively about how the system might fail, test edge cases that automated tests wouldn't cover, and bring a user's perspective that pure automation misses. Automation handles the repetitive checks; people handle the thinking.

Continuous testing in the pipeline¶

Our CI/CD pipelines enforce quality automatically. A typical pipeline runs tests at multiple trigger points:

Trigger	What runs
Code commit	Unit tests
Pull request	API and UI tests
Nightly / scheduled	Full regression, non-functional tests (performance, security, accessibility)
Deployment	Smoke tests to verify the deployment is healthy

If tests fail, the pipeline fails. This is the automation-first mindset in practice — trust the pipeline and keep it green.

Governance and standardisation¶

We maintain consistency across projects without stifling flexibility.

Centralised frameworks and libraries enable faster onboarding, easier knowledge transfer, and reduced maintenance. Common utilities, logging wrappers, reporting tools, and test data generators are shared across teams and open to contribution.

Coding standards for test code are enforced consistently. Test code is production code — it should be clean, readable, and maintainable.

Documentation standards include a test strategy per project (aligned to our organisation-wide strategy), versioned test cases with traceability to requirements, and clear READMEs. Tests themselves are treated as live documentation — they should be readable enough that a new team member can understand the system's behaviour from the test suite.

Dashboards provide visibility of automation job status, test coverage trends, and quality metrics across projects.

Metrics and reporting¶

We track and report on metrics that drive meaningful improvement:

Test coverage — as a risk indicator, not a target (see our principles above)
Automation pass/fail rates — to monitor test suite health and catch flaky tests
Defects caught pre vs post production — the clearest measure of whether shift-left is working
Non-functional benchmarks — performance baselines, response time trends, throughput
Security vulnerability trends — tracking resolution rates and patterns over time

Tools we use¶

We select tools based on the client's tech stack, team capability, and project needs. Tools we have deep experience with include:

Purpose	Tools
Unit testing	xUnit, NUnit, Jest, pytest, and language-appropriate equivalents
API testing	Postman, Newman
E2E / browser testing	Playwright
Performance testing	k6, JMeter, Locust
Security testing	SAST and DAST tooling integrated into pipelines
Accessibility testing	Automated checks in UI pipelines, manual audits
CI/CD integration	Azure DevOps Pipelines, GitHub Actions

This isn't an exhaustive list — if a project needs something different, we'll adopt it. The principle is always to use the best tool for the job, not the most familiar one.

AI-assisted testing¶

We use AI tools to enhance our testing and development workflows. Tools like Claude Code and GitHub Copilot help us with both technical tasks — scaffolding test frameworks, generating test cases, writing automation code — and non-technical tasks like documentation and test planning.

AI is an accelerator, not a replacement. Everything AI-assisted goes through human review. We use these tools safely and responsibly, with a human always in the loop to validate output, catch errors, and apply the engineering judgement that AI can't.

We continue to explore how AI can add value in areas like visual testing, coverage analysis, and identifying patterns in test failures, adopting new capabilities where they prove genuinely useful.

Automation-first doesn't mean automation-only

Our strongest test strategies combine a robust automated suite with targeted exploratory testing. Automation catches the known risks; skilled testers find the unknown ones.

Tools & Technologies

Tools & Technologies¶

The tools and technologies we use and recommend. We pick the right tool for the situation rather than enforcing a fixed stack, but these are the ones we have deep experience with and use most frequently.

Claude Code — How we use AI-assisted development to work faster without sacrificing quality.

Azure DevOps — Our primary platform for source control, CI/CD, and project management.

Claude Code¶

Claude Code is a command-line tool from Anthropic that allows developers to delegate coding tasks to Claude directly from their terminal. At CDS, we use Claude Code as a core part of our development workflow.

Why we use it¶

Claude Code allows us to work faster without sacrificing quality. It's particularly effective for:

Scaffolding projects — generating boilerplate, configuration files, and folder structures
Writing and editing content — such as the Markdown pages in this very handbook
Code generation and refactoring — writing implementations from requirements, modernising legacy code
Debugging — explaining errors, suggesting fixes, and working through complex issues
Documentation — generating READMEs, ADRs, and inline documentation

Best practices¶

Be specific with your prompts¶

The more context you give Claude Code, the better the output. Include details about the tech stack, coding standards, and the specific outcome you want.

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 — tech stack, conventions, folder structure, and any specific instructions. This saves time and improves consistency across the team.

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 — it needs the same scrutiny.

Iterate¶

Don't expect perfection on the first pass. Use Claude Code iteratively: generate, review, refine. This mirrors how we work as engineers anyway.

Getting started

If you're new to Claude Code, install it via npm: npm install -g @anthropic-ai/claude-code. You'll need a valid API key or Anthropic account to authenticate.

Azure DevOps¶

Azure DevOps (ADO) is our primary platform for source control, CI/CD pipelines, work item tracking, and project management. We use it across the majority of our engagements.

What we use it for¶

Git repositories¶

All our source code lives in ADO Git repositories. We follow a trunk-based development model with short-lived feature branches and pull requests.

Pipelines¶

We use ADO Pipelines for continuous integration and continuous deployment. Pipelines are defined as YAML files checked into the repository, keeping our build and deployment configuration version-controlled alongside the code.

Boards¶

For work item tracking, we use ADO Boards with a lightweight process. We avoid over-complicating the workflow — typically we use a simple Backlog → In Progress → In Review → Done flow.

Branching strategy¶

We follow trunk-based development:

main is the primary branch and is always deployable
Feature branches are short-lived (ideally merged within a day or two)
Pull requests require at least one approval before merging
Branch policies enforce build validation on PRs

Pipeline standards¶

Every project should have, at minimum:

A build pipeline that runs on every PR (compile, test, lint)
A release pipeline that deploys to the target environment on merge to main
Pipeline definitions stored as YAML in the repo, not configured through the UI

Flexibility

While ADO is our default, we're not dogmatic about it. Some engagements may use GitHub, GitLab, or other platforms depending on the client's existing tooling. The principles above apply regardless of the platform.

Contributing to the CDS Handbook¶

The CDS Handbook is a shared resource, maintained collaboratively across the company. If you spot something out of date, want to add a new page, or improve existing content, this guide explains how to do it.

All changes go through a pull request (PR) review before appearing on the live site. This keeps the quality and consistency of the handbook high.

Before you start¶

You need:

An Azure DevOps (ADO) account — everyone at CDS has one
Access to the repository: CDS External Handbook on ADO

If you cannot access the repository, speak to your line manager.

Branch naming convention¶

Whether you edit via the browser or locally, your branch name must follow this pattern:

contrib/<your-name>/<brief-description>

Keep the description short (2–4 words, hyphen-separated) and descriptive of your change.

Examples:

Who	Change	Branch name
Sarah Jones	Adding a security tools page	`contrib/sarah-jones/add-security-tools-page`
James Smith	Updating the delivery approach	`contrib/james-smith/update-delivery-approach`
Alex Taylor	Fixing typos on the values page	`contrib/alex-taylor/fix-typos-values-page`

Making changes via the browser¶

The simplest way to contribute — no software to install.

Editing an existing page¶

Open the repository in ADO.
Click Files in the left-hand sidebar, then navigate to the docs/ folder and find the file you want to edit.

Tip

Each handbook page corresponds to a .md file in docs/. For example, the Life at CDS page is docs/about/life-at-cds.md.
Click the file name to open it, then click the Edit (pencil) icon in the top-right corner.
Make your changes in the editor. Refer to the Markdown guide below if you need help with formatting.
When you are done, click Commit in the top-right corner.
In the commit dialog:
- Write a short Comment describing your change (e.g. "Update agile practices — add retrospective section")
- Change the Branch name field from main to your new branch name, following the naming convention above
- Tick Create a pull request
- Click Commit
This opens the New Pull Request screen. ADO pre-fills the title and description from your commit comment — update them to be clear and descriptive:
- Title — a concise summary of your change (e.g. "Update agile practices — add retrospective section")
- Description — one or two sentences on what you changed and why
- Click Create

Your PR will be reviewed. You will be notified when it has been approved and the changes are live.

Creating a new page¶

Creating a new page requires one additional step — adding it to the site navigation — which the reviewer will handle before merging. You do not need to worry about this.

Open the repository and navigate to the relevant subfolder inside docs/:
- docs/about/ — life at CDS, culture, values
- docs/ways-of-working/ — agile, delivery, methodologies
- docs/tools-and-tech/ — tools and technologies
Click + New at the top-right of the file list, then select File.
Name your file using lowercase words separated by hyphens, ending in .md — for example, my-new-page.md.
Start the file with a front matter block (see Front matter and tags below), then add your content.
Commit to a new branch and raise a PR as described in steps 5–7 above.
In your PR description, mention that you have created a new page so the reviewer knows to add it to the navigation.

Adding images via the browser¶

Images must be uploaded to the repository before you can reference them in a page.

Navigate to docs/assets/images/ in the ADO file browser.
Click the ⋮ three-dot menu at the top-right of the file list, then select Upload file(s).
In the commit dialog, commit to the same branch you are using for your content changes — not to main.
Reference the image in your Markdown file (see Images in the Markdown guide below).

Making changes locally (for developers)¶

If you are comfortable with Git, you can clone the repository, make changes locally, preview the site, and push a branch.

Prerequisites¶

Git
Python 3.10 or later and pip

Workflow¶

# Clone the repository (first time only)
git clone https://cdsdigital.visualstudio.com/_git/CDS%20External%20Handbook
cd "CDS External Handbook"

# Install dependencies
pip install -r requirements.txt

# Create a branch following the naming convention
git checkout -b contrib/your-name/brief-description

# Preview the site locally as you work (auto-reloads on save)
make serve

# When ready, stage and commit your changes
git add docs/your-file.md
git commit -m "Brief description of your change"

# Push your branch to ADO
git push origin contrib/your-name/brief-description

Then open ADO and raise a pull request against main.

Tip

Run make build before pushing to catch any broken links or formatting issues. The pipeline runs with --strict mode, so any warnings will fail the build.

Writing in Markdown¶

Handbook pages are written in Markdown — a simple formatting language that renders as styled HTML. Here is everything you need.

Headings¶

# Page title — use once, at the top of the page

## Major section

### Subsection

Warning

Every page should have exactly one # (H1) heading at the top. Do not skip heading levels.

Text formatting¶

**bold text**

*italic text*

`inline code`

Lists¶

- Bullet point
- Another bullet point
    - Indented sub-point

1. Numbered list
2. Second item
3. Third item

Links¶

[Link to an external site](https://example.com)

[Link to another handbook page](../about/our-values.md)

Use relative paths (starting with ../) to link between pages in the handbook. Do not hardcode the live site URL.

Images¶

Images must be saved in docs/assets/images/ before you can reference them. See Adding images via the browser above for how to upload them.

Once uploaded, reference an image in your Markdown like this:

![A description of the image](../assets/images/your-image.png)

The number of ../ steps depends on where your page sits:

Page location	Image path prefix
`docs/your-page.md`	`assets/images/`
`docs/subfolder/your-page.md`	`../assets/images/`

Always write a meaningful description in the alt text — this matters for accessibility and is displayed if the image fails to load.

Tables¶

| Column A | Column B | Column C |
|----------|----------|----------|
| Row 1    | Value    | Value    |
| Row 2    | Value    | Value    |

Code blocks¶

Surround code with triple backticks and specify the language for syntax highlighting:

```python
def greet(name):
    return f"Hello, {name}!"
```

```bash
make serve
```

Callout boxes¶

Use admonitions sparingly — only for things the reader genuinely needs to notice.

!!! tip
    A helpful suggestion.

!!! note
    Something worth knowing.

!!! warning
    Something the reader must be aware of before proceeding.

Front matter and tags¶

Every page must begin with a front matter block that lists relevant tags. This powers the Tags index.

---
tags:
  - ways-of-working
  - agile
---

Use existing tags where possible. Common tags are: about, culture, values, ways-of-working, agile, delivery, tools, devops, azure, ai, contributing.

What makes a good pull request¶

One change per PR — keep it focused. A PR that fixes a typo and rewrites a whole section is harder to review.
Clear title — describe what changed, not just "update page".
Brief description — one or two sentences on what you changed and why.
Check your formatting — preview your Markdown if you can, and double-check image paths and internal links.
New page? — mention in the description that the nav entry needs to be added.

Tags¶

Browse all handbook content by tag.