DEV Community: Stuart Dobson

Build Transformative AI Assistants with Claude Code Workspaces

Stuart Dobson — Tue, 18 Aug 2026 08:50:16 +0000

I’ve been using Claude Code workspaces for about 6 months. They are one of the reasons I’m positive about AI. They’re like auxiliary brains, opening so many doors of opportunity.

I built a workspace for preparing for job interviews. It had MCP tools which researched the interviewer’s LinkedIn, company website, and the role description, and then synthesized the information. It had commands that generated practice questions based on the interviewers’ roles and the position. I used my resume and the job application as grounding references. I had a skill which gave me ideas for what to say for my intro - tailored to the company’s needs.

I’ve never found a good website for homework questions for my son. They’re always full of ads and often inappropriate content. So I built a workspace for it. It knows his interests and customises learning projects based on them and his level. It generates a set of questions on various subjects when requested. Over time I have tweaked it to improve the questions. When the question is complex, we’re able to ask in-depth follow up questions.

I built a workspace for managing my study for a Microsoft exam. It researches the current literature on Microsoft Learn and creates a weekly learning schedule.

I’ve built workspaces for brainstorming, deep research, planning, code generation, code evaluation and more. The opportunities workspaces present are endless. The output they create has been a game changer.

Building a Claude Code Workspace That Actually Works

The problem with basic chat is that it often gets things wrong, but one of the best ways to improve this is to give it grounded information as a baseline. A collection of hardwired instructions, consistent context, and a limited working space.

A workspace is a structured environment that gives Claude persistent context, repeatable skills it executes consistently, hooks that enforce rules it can’t override, and a clear design for what gets loaded when. Once you’ve built one, going back to ad-hoc prompts feels like going back to using a search engine. Oh the horror!

This post walks you through the pattern using a consulting operations workspace as the concrete example: client intake, proposals, status reports. The structure applies to anything repeatable: content pipelines, research workflows, team operations.

First: Get Claude Code Running

Before any of the workspace stuff matters, you need Claude Code installed and running. Here’s how.

Step 1: Install Claude Code

The easiest option is the desktop app. Download it from code.claude.com/docs/en/desktop and run the installer. The desktop app installs everything including the claude terminal command, so Steps 3 and 4 below will work straight after.

If you’re a developer and prefer the CLI directly:

npm install -g @anthropic-ai/claude-code

You’ll need Node.js installed first if you go that route.

Step 2: Open your workspace folder in VS Code

Create a folder somewhere sensible (e.g. my-workspace), then open it in VS Code. File > Open Folder.

Step 3: Open the terminal in VS Code

Press Ctrl+` (backtick, the key above Tab) or go to Terminal > New Terminal. A terminal panel opens at the bottom of the screen. My recommendation - grab the top border and make it take up at least half the screen. :)

Step 4: Run Claude

Type claude and press Enter. Claude Code starts in your terminal, reads your workspace folder, and you can start talking to it.

Everything you build in the workspace - the CLAUDE.md, the context files, the skills - is picked up automatically. Claude reads the folder it was opened in.

One more thing: VS Code also has a Claude Code extension in the marketplace. Same result, slightly friendlier interface. Either works.

The Folder Structure

my-workspace/
├── CLAUDE.md                     # Session constitution, keep it lean
├── .claude/
│   ├── commands/                 # Simple slash commands
│   ├── skills/                   # Rich workflows with bundled assets
│   │   ├── new-client/
│   │   │   └── SKILL.md
│   │   ├── proposal/
│   │   │   ├── SKILL.md
│   │   │   └── proposal-template.md
│   │   └── status-report/
│   │       └── SKILL.md
│   ├── agents/                   # Specialist subagents
│   │   └── research-agent.md
│   └── settings.json             # Hooks
├── context/                      # Always-loaded session context
│   ├── personal-info.md
│   ├── strategy.md
│   └── current-data.md
├── reference/                    # On-demand only, loaded by skills
│   └── client-templates/
└── outputs/
    ├── clients/
    ├── proposals/
    └── reports/

Two things drive every design decision here: the context window and the session lifecycle.

The Design Decision That Matters Most

Every file Claude reads at session start consumes context window permanently for that session. Blow your context budget upfront and you have a sluggish, forgetful Claude by the time you’re halfway through a real task.

The fix is a hard split between what gets loaded every session and what gets loaded on demand:

Always-loaded (CLAUDE.md + context/): who you are, what you’re optimising for, operational rules. Lean. If removing a line wouldn’t cause Claude to make a mistake, cut it.
On-demand (reference/, skill assets): style guides, client templates, source link libraries. Loaded only when a specific command needs them.

A 200-line style guide loaded every session costs you context whether you’re drafting or just asking a quick question. Loaded only when /draft-post fires, it costs nothing on sessions where it’s not required.

Most workspace guides tell you to put everything in CLAUDE.md. That is completely wrong. The loaded-vs-on-demand split is the design decision that separates a working harness from one that slowly stops working as your workspace grows.

CLAUDE.md: Should be Lean

CLAUDE.md is auto-loaded every session. Treat it like a constitution, not a knowledge base.

What belongs here:

Rules that apply to every task (“always respond in British English”, “never commit without running tests”, “never use em dashes”)
Workspace structure: what the folders are for and how to navigate them
@context/personal-info.md style imports that pull in context files without embedding them
Commands available and what they do

What doesn’t:

Detailed style guides (they go in reference/, loaded by skills)
Anything that only applies to one type of task
Information Claude can infer by reading the files

Anthropic’s test is blunt: “Would removing this line cause Claude to make a mistake?” If no, cut it. A bloated CLAUDE.md causes Claude to gradually deprioritise your rules as the session progresses. Not because it ignores them. Because they get buried under more recent context. The rules don’t disappear. They just lose.

Keep CLAUDE.md under 200 lines. Use @path/to/file imports to pull in section-level context rather than embedding everything directly.

Memory: What Claude Learns Automatically

CLAUDE.md is what you write deliberately, upfront. Memory is what Claude writes as it works with you.

Claude’s auto memory system lives outside the repo in its config directory. As sessions progress, it captures things you’d otherwise repeat across sessions: preferences you’ve stated, corrections you’ve made, project context it has learned. Next session, those facts are already there.

What belongs in memory:

Preferences learned through use (“prefers bullet lists over tables: pushed back on this in post 7”)
Corrections and feedback (“never use em dashes: corrected twice, now a standing rule”)
Project context that isn’t in the code (“AI-103 exam target is early June 2026”)

What doesn’t:

Rules you’ve decided upfront - those go in CLAUDE.md
Anything that needs to be shared with teammates or version-controlled - memory is private to your Claude config, not in the repo

The distinction: CLAUDE.md is designed. Memory is learned.

One gotcha: memory entries go stale. If a project priority shifts or a preference changes, Claude may still act on an old memory. Audit memories periodically the same way you audit CLAUDE.md.

Context: What Claude Always Knows

The context/ folder is small by design. Three files, not thirty. Claude reads them at the start of every session: who you are, what you’re currently working toward, and the live numbers that inform decisions. Keep them small!

A typical setup - your situation may vary:

personal-info.md: role, background, relevant expertise
strategy.md: current priorities and what success looks like
current-data.md: live numbers, updated weekly

Everything here pays a context window tax on every session. If a piece of information only matters for one type of task, it belongs in reference/, not here.

References and On-Demand RAG

Nothing in reference/ loads unless a skill requests it. That’s the rule.

It’s effectively RAG (Retrieval Augmented Generation - “a technique used to improve the accuracy of Large Language Models (LLMs) like ChatGPT or Gemini by fetching facts from an external, trusted database before generating a response, rather than relying solely on the AI’s internal training memory.”) for your workspace. An exam guide, sample homework questions, your client proposal template, your list of research sources: none of it costs context window unless it’s actually needed. A skill that creates a client proposal loads reference/client-templates/. A skill that researches a topic loads reference/brainstorm/. A plain coding question loads nothing from reference/ at all.

If you’re tempted to put a file in context/ because “Claude might need it,” ask whether it’s needed every session or just on specific tasks. If specific tasks, it belongs in reference/.

Outputs: Where the Work Lives

The outputs/ folder is where Claude writes its deliverables. Structure it by workflow type, not file type:

outputs/
├── casestudies/
│   ├── drafts/
│   └── research/
├── clients/
├── proposals/
└── reports/

In some scenarios, you might need Claude to read items from these folders as inputs to another. This is why separating them logically is important.

Skills: Repeatable Workflows with Bundled Assets

A skill is a markdown file in .claude/skills/<name>/SKILL.md that defines a repeatable workflow. Invoke it explicitly with /skill-name, or let Claude auto-trigger it when it judges the description matches your task.

Anthropic created skills. Read their guide before working with them.

Here’s the client intake skill for the consulting workspace:

---
name: new-client
description: "Create a new client project brief from intake information."
             Invoke when setting up a new client or project.
disable-model-invocation: true
---

Parse the following client intake and create a project brief
in `outputs/clients/{client-name}/brief.md`.

Extract:
1. Client name and contact
2. Problem statement
3. Scope and deliverables
4. Timeline and budget constraints
5. Success criteria

Confirm the brief was created and ask whether to draft a proposal.

Input: $ARGUMENTS

disable-model-invocation: true prevents auto-triggering. Use it on any skill that creates files or has side effects. You want explicit invocation for anything with consequences. Leave it off for knowledge skills Claude should apply automatically, like coding conventions or tone guidelines.

The description matters more than people expect. It’s how Claude decides whether to auto-load the skill. Vague descriptions cause wrong skills to fire. “Handles client work” will trigger on things you didn’t intend. “Create a new client project brief from intake information” will not. Be specific about the exact scenario.

Skills can carry sibling files (templates, reference docs, examples, tools) that load alongside the instructions. The proposal skill carries proposal-template.md. The logic lives in SKILL.md; the reference material sits next to it. Nothing leaks into CLAUDE.md.

Commands: Lightweight Slash Shortcuts

Commands are markdown files in .claude/commands/. You invoke them with /command-name and they run immediately. No sibling assets, no auto-trigger logic. Simple, explicit shortcuts for bounded tasks.

# Image Prompt

Generate a sumi-e style blog header image prompt for post $ARGUMENTS.
Read the brief or draft, identify the central concept and key metaphors,
then output a ready-to-paste prompt for DALL-E, Midjourney, or similar.
Style rules are in `reference/image-style.md`.

Use commands for things you trigger manually on demand: /prime to initialise a session, /research "topic" to kick off an investigation.

/create-plan is worth calling out separately. Before any multi-file change or new feature, it writes a structured implementation plan and waits for your sign-off before touching anything. Claude confirms the right approach first, rather than confidently building the wrong thing. Add it to every workspace that involves code or complex deliverables.

Skills are the right choice when a workflow needs sibling assets, when the logic is long enough to warrant structure, or when you want auto-trigger behaviour. For everything else, a command is faster to write and easier to maintain.

Hooks: Rules Claude Can’t Override

CLAUDE.md instructions are advisory. Claude reads them, weighs them against everything else in context, and may deprioritise them in a long session. Hooks are different. They’re shell commands that run deterministically at specific lifecycle events. Claude can’t reason its way around them. If you don’t know how to script, simply ask Claude to write it.

Configure them in .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date): modified $FILE_PATH\" >> outputs/ledger.md"
          }
        ]
      }
    ]
  }
}

This logs every file write to an audit ledger automatically. No prompting required. Claude can’t skip it.

Use hooks for things that must happen every time with zero exceptions: formatting after file edits, blocking writes to protected directories, logging outputs, running lint before a commit. If it’s important enough that “Claude forgetting” is unacceptable, it belongs in a hook, not CLAUDE.md.

One gotcha: don’t let hooks block mid-edit. Hooks that interrupt Claude while it’s reasoning through a multi-file change break the reasoning chain. Block at the end of a task, not mid-stream.

MCP Servers: External Tool Integration

Model Context Protocol connects Claude to external services: file systems, GitHub, Google Drive, Slack, databases, web search. Each MCP server exposes a set of tools Claude can call directly within a session.

Configure them in .claude/settings.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

With this in place, Claude can read and create PRs, check CI status, and search your repository without you copying anything into the chat. Add web search and Claude can pull current documentation. Add a database MCP and Claude can query your schema directly.

MCP servers run as local processes. Each one consumes resources. Don’t add servers you won’t use. Vet community servers before depending on them: check the last commit date and the issue tracker. Official integrations (GitHub, Google Drive, Slack) are stable. Community servers vary significantly and can be dangerous.

Sub Agents: Specialist Workers

The .claude/agents/ folder holds specialist agent definitions. Each is a markdown file describing a narrow-purpose assistant Claude can spin up for specific tasks.

---
name: research-agent
description: Research agent for web searches and source collection.
             Invoke for background research that shouldn't consume main session context.
---

You are a focused research assistant. Given a topic, search for:
1. Official documentation and release notes
2. Community tutorials and real-world usage examples
3. Known issues or limitations

Return a structured summary with links. Research only: no code, no recommendations.

The main value is context isolation. Hand a task to a sub agent and it runs in its own context window. A research sweep that reads twenty web pages stays in the agent’s context, not yours. Your main session stays clean.

Use sub agents for tasks that are parallel, independent, or context-heavy: background research, specialist review, parallel file analysis. Don’t use them for tasks that need your session’s context. The agent starts fresh. It won’t know what you’ve been doing.

The /prime Session Initialisation Pattern

Every session should start with explicit initialisation. Don’t trust Claude to figure out context from the project root. Depending on what you ask first, it may or may not read the right files.

A /prime skill handles this:

---
name: prime
description: Initialise a new session with full context.
             Run at the start of every session.
---

1. Read CLAUDE.md and context/personal-info.md, context/strategy.md,
   context/current-data.md
2. Summarise your understanding: who I am, what this workspace is for,
   current priorities
3. Confirm readiness to assist

Type /prime. Claude reads the files, summarises back, and you can verify immediately if anything’s missing. Thirty seconds max. Prevents the most common workspace failure: a session where Claude lacks context and you don’t notice until you’ve wasted twenty minutes on outputs that miss the point.

Workspaces vs Claude Cowork

Claude Cowork is Anthropic’s other desktop product, and it’s worth understanding the difference before you commit to building a workspace.

Cowork is designed for autonomous, goal-driven tasks. You give it an outcome (“prepare a briefing document from these three reports”) and it handles the steps: opening files, synthesising information, producing the deliverable. No programming required. It’s aimed at researchers, analysts, and knowledge workers who need Claude to operate on their local files without any setup.

A Claude Code workspace is the opposite philosophy. You define the structure, the context, the rules, and the repeatable workflows. Claude follows them consistently across every session.

Claude Cowork is the right choice when:

The task is one-off or hard to predict in advance
The user isn’t technical and won’t be configuring anything
You want autonomous execution with minimal setup

A Claude Code workspace is the right choice when:

You run the same workflows repeatedly and want consistent results
You need hooks that enforce rules Claude can’t reason around
You want context that persists and compounds across sessions
You’re a developer who wants programmatic control over how Claude operates

Most technical people will end up using both. Cowork for ad-hoc heavy lifting. A workspace for the repeatable stuff that needs to work the same way every time.

Gotchas

CLAUDE.md bloat kills rule adherence. Past ~200 lines, rules start getting quietly ignored. Claude doesn’t warn you. Audit your CLAUDE.md periodically and prune anything that doesn’t pass the mistake test. If you’ve added something since day one that Claude was already doing correctly, delete it.

Skill descriptions consume context on every tool call: roughly 2% of your context window per skill, even if the skill isn’t active. Keep descriptions to 2-3 lines. Don’t write essays in the frontmatter; you’re paying for that space in every session.

The on-demand split requires discipline. The moment you put detailed reference material in context/ instead of reference/, you’ve broken the pattern. Strict rule: if a piece of information only matters for one type of task, it doesn’t go in context/.

Session context drifts in long sessions. /clear between unrelated tasks is not optional. It’s how you maintain output quality. Mixing research, drafting, and code review in one session produces mediocre results across all three. The instructions are still there. The signal-to-noise ratio isn’t.

MCP server quality varies significantly. Before depending on a community MCP server, check the last commit date. The ecosystem has a long tail of abandoned projects. Official integrations (Google Drive, GitHub, Slack) are stable; community servers need vetting before you build workflows on top of them.

What to Build First

Start small. Don’t wire up MCP on day one or write six skills before you’ve tested one.

Create the folder structure: directories only, no content yet
Write CLAUDE.md: twenty lines maximum, workspace structure and core rules
Add context/personal-info.md: who you are and what this workspace is for
Write one skill: pick the task you do most often, document its steps
Add a /prime skill: one invocation that confirms Claude has context
Add one hook: start with an output ledger, low-risk and immediately useful

The workspace pattern compounds. A working harness with three skills beats an over-engineered one with twelve half-tested ones.

You’ll find that the demands grow as you use your workspace. You’ll consistently create new commands, plugins and skills for various things as they come up. But start with a basic workflow.

Tell Claude to Improve Its Own Workspace

Here’s something I’ve found really useful: ask Claude to modify the workspace itself.

If you find yourself typing the same instruction at the start of every session, tell Claude to add it to CLAUDE.md. If a task you do repeatedly doesn’t have a command yet, ask Claude to build one. The workspace doesn’t have to be designed upfront. It can grow from usage.

Some examples of what this looks like in practice:

“I keep having to tell you to check the briefs file before drafting. Add that as a rule in CLAUDE.md.”
“Build me a command called /weekly-review that reads context/current-data.md and outputs a summary of progress against my targets.”
“I want a skill that generates LinkedIn posts from a blog draft. Look at how /draft-post works and create something similar.”

Claude writes the markdown, creates the file, and confirms what it did. You review it, ask for tweaks, and move on. No separate design session required.

The best workspaces I’ve built weren’t architected in one sitting. They accumulated through use. Every time friction showed up, I turned it into a command or a rule.

Optimising Your Workspace

A workspace that worked well at week one will have friction by week eight if you don’t maintain it. Three areas to audit regularly.

CLAUDE.md: Run the mistake test on every line. “If I removed this, would Claude make a mistake?” Anything that doesn’t survive the test is noise. Also check for rules Claude was already following correctly before you wrote them down. You’re paying context window for instructions you don’t need.

Skills and commands: Vague descriptions cause wrong skills to fire. If a skill is auto-triggering on tasks you didn’t intend, tighten the description. If you have skills you haven’t used in a month, archive them. Description overhead accumulates even for idle skills.

Hooks: Review what’s actually firing. The audit ledger is your ground truth. If a hook isn’t appearing when it should, the matcher is wrong. If it’s appearing on tasks where it’s irrelevant, the matcher is too broad.

Beyond maintenance, the fastest way to level up a workspace is to use a skill like claude-code-mastery. Add it to your skills folder and call it with /claude-code-mastery and it will assess your workspace. The last time I ran this it found a few optimisations that dropped my initial context from 10000 to 100 tokens. For real! Highly recommended.

The other signal is your own session transcripts. If you’re repeatedly typing the same instructions at the start of a session, that’s missing context file info or missing MEMORY. If you’re correcting Claude on the same point every few sessions, that’s a hook or rule that needs to be written. Let your friction tell you what to build next.

The Pattern Scales

The same structure works whether you’re running a content pipeline, a learning workspace, an interview preparation tool, a team operation, or a solo research workflow. The skills change. The context files change. The design decisions don’t.

CLAUDE.md is the constitution.

context/ is the always-loaded minimum.

reference/ is the on-demand library.

Skills are repeatable procedures.

Hooks are non-negotiable rules.

/prime is the session handshake.

Build it once. Adjust the skills for your domain. Spin it up for each project or client as a template.

Now you’re using AI properly.

Thanks for reading. You can find more of my work at stuartdobson.net

Story Points are Utter Nonsense

Stuart Dobson — Fri, 27 Feb 2026 02:55:05 +0000

For over a decade, I've lived a lie.

I made myself believe that Agile Story points made sense.

I rationalised it like we all did.

"They map to complexity, not time".

Yet we spend hours on Sprint Planning meetings deciding how many jobs we can fit into a Sprint - a unit of time. Also - doesn't complexity relate to time?

"They're a rough guide, they're not supposed to be accurate."

How on Earth did we end up with a unit of measure that is "not supposed to be accurate"?

"It depends on experience of the person doing the job."

This is like saying the length of a centimeter depends on the tape measure you're using.

"They're a measure of relative complexity."

Relative to what? Another story you did which didn't have an accurate estimate?

"We use shirt sizes/Fibonacci/animals/fruit."

Is this supposed to make it easier to understand? Why can't I give a task 4 points?

"We have to agree on size before we can move on."

Yes, let's ensure the contractor watering the plants gets a say on this.

"Planning poker helps us find a consensus."

I guess it does, once everyone is worn down enough to just agree.

A recent discussion highlighted the absurdity. I asked people to define what story points were, and just like the multiple meetings I've had over many years, it was clear that nobody could agree.

I got the usual selection of contradictions and confusion.

Story points have no unit of value
Story points are a non standard unit of value(?)
They're team specific, so they don't map to anything
They don't map to time, but they do map to a sprint, which is time
They map to complexity, but how much depends on the experience of who is doing the job, and the maturity of the team, which changes over time.
They're only supposed to be used for Epics, and Stories are estimated in time
A Story point is like a chicken

Yes, that was a legitimate answer from someone attempting to explain what a story point was.

It's like a chicken.

This is a real thing a human said:

"I once had a Scrum consultant working with our team who said a story point can be a chicken if you wanted. Find a story that the team can say is a very simple piece of work and call that your chicken. This chicken is then 1 story point. A story that would be twice as difficult or complex would be a two-chicken story (or 2 story points). It's over-simplified, but perhaps you get the point."

Not sure I do..

Agile is a cult. This is evident in the explanations which pervade this space that are often repeated ad nauseam. One of these explanations becomes our rationalistion: "It's Agile. It's flexible - you can do it how you want."

It's time we admit that it doesn't work and it's really just a cocktail of nonsense, designed to put a framework around what is, in the end, an impossibly hard thing to plan.

I'm going to invent a new system of organising workloads. You have planning meetings once every 13 days unless there's a full moon. In those meetings you can play Snakes and Ladders to determine the "relative complexity" of a ticket. Then you throw that number out, and just do the job anyway. Every 15 minutes someone has to stand up and shout "Bingo". Then someone else picks up the ball.

Actually, this makes as much sense as our Agile rituals, so it'll probably take off.

I apologise to the workers of 2040.

Why should I care about Quality? I'm a developer!

Stuart Dobson — Sun, 15 Dec 2024 06:47:21 +0000

Quality is something QA do, right?

OK, so no developer wants to create bad quality code. But for most developers, quality is seen as something separate from development, something that is checked after the work has been done. It is something that QA do, after you throw your code over the fence. Thinking about quality at during development is a burden, slowing down the creation of functionality, holding up new features. Thinking about quality before development? That's just crazy talk.

Old Habits Die Hard

In the Agile world, Quality should be baked into the development process and there is more interaction between development and QA during the development phase. At least, that's the theory. In practice, we often slip back into bad habits of throwing code over the fence.

The reason we keep falling back into bad habits is because the attitude around quality is the same as it always was. It is still seen as something separate from development, separate from design, separate from planning. This causes it to be seen as a burden - extra work that just has to be done.

Quality as the Glue

If instead, we change our perspective, and try to see Quality as an integral part of the entire development process, it can change the way we all work, from developers to product owners. Instead of a burden, quality should be a thread that runs throughout the process, and actually defines how all work is done from the ground up. If this is done, it can actually simplify and speed up development.

Baking quality into your process shifts the responsibility to everyone, rather than just QA. Having the whole team (including product owners) take responsibility for quality sets the focus around Acceptance Criteria. This "requirements-centric" approach gets everyone thinking about quality right from the refinement meeting. When the entire team comes together and builds good Acceptance Criteria, quality becomes a natural, and welcome, part of the development process.

Several things then happen. First, the whole team are forced to agree on the details of the requirements before development starts. Before any technical decisions or implementation planning, the exact requirements are clarified. Only by making this an imperative part of the process (usually the refinement meeting) can this happen effectively.

Good Acceptance Criteria Drives Good Development

With clear Acceptance Criteria, development is simplified. Development knows exactly what they need to implement, and when they know this, the process of writing automated tests is no longer abstract and difficult. Test Driven Development is a tricky thing to do, in practice. However, with clear goals, a developer can start with "pseudo tests" - tests which are just code comments - but which outline the business logic before coding begins. These will be a granular list of Prerequisite/Action/Assertions - Unit tests, essentially - outlining the required logic. Then, development becomes a process of implementing that logic.

Breaking the logic down before development begins is a very effective way of ensuring that clean code practices, especially the Single Responsibility Principle, are followed. It becomes natural to keep the logic simple, concise, and separated from other concerns, such as infrastructure. It encourages clean Object Orientated design.

Good Acceptance Criteria Drives Good QA

Also QA know exactly what they will be getting. They know what parts of the job will be automated, so they can design better integration, acceptance, and End to End tests, as well as an effective exploratory strategy.

Without this clarity, QA are left with waiting until a job is done and not knowing what they're going to get - which is a recipe for annoying manual regression testing, and no doubt, bugs.

Agile Demands Quality, Quality Brings Clarity

Agile is about iterating fast. You cannot do this when QA are held back by a requirement to constantly manually regression test, or worse still, you avoid regression testing and hope new development doesn't break anything.

With good Acceptance Criteria baked into the process, everyone has clarity. As a developer, this makes your life so much easier. You know what needs to be developed before you start, which allows you to concentrate on technical implementation details. With clear requirements, the code is cleaner, so development and maintenance is easier. This allows the team to iterate fast, able to add new features quickly.

Early automated testing becomes a something that fits into the process, and with this automation in place, QA can focus on exploration. With automation, we are able to develop with confidence, and innovate freely.

Quality no longer slows down the development process, but guides it.

That's why developers should care about quality.

How to name Unit Tests

Stuart Dobson — Mon, 02 Dec 2024 23:59:11 +0000

How should you name your Unit Tests? What standards should you have in place for their names?

Who cares.

I'm not going to tell you the exact structure and format you need to use. That's up to you, your company, your Technical Lead, or whoever thinks this is important.

What I'm here to tell you is there are certain things you should always do when naming Unit tests and that it is quite important that these things are done.

So what are these important things that you need to do when naming Unit tests?

They need to be named in a way that tells you what scenario they are testing and what the outcome should be. Seems obvious but there's a bit of an art to this, and it's very easy to do wrong.

Why is it important for unit tests to tell you what they do? It's because coding is a team sport. Code needs to be read and maintained. Unit Tests are code and they also serve as documentation of your functionality. More so sometimes, than the code itself.

Other people (including future you) need to be able to look at the names of the test and know what specifically is being tested. Not just the what, but the when. When does the thing that you're testing happen? What is specific to this particular scenario that makes it special?

An example of naming being done badly would be Verify_Process. What does verify actually mean, and what is the Process?

Oh, the method you're testing is called "SomethingProcess()"? Well that's a problem right there. Rename it to explain what exactly the "process" is doing!

Also, verify doesn't tell me anything. What are you verifying? What makes the thing you're testing “verified”? How is someone who looks at this code in 18 months going to know that by looking at this name? If they can't determine its purpose from the name they'll end up having to look through the code of the test, which is a considerably slower process.

Telling us just what the test does is also not enough. AddNewCustomerTest is not enough. What scenario are you testing? That a new customer can be added is not a scenario but an action. What about testing when a customer is not added successfully, for some reason, or when they are added but already exist?

Also, when are they being added? For example, you might name the test: WhenCustomerHasFullName_CustomerAddedSuccessfully. Here is a test which tests the scenario of when the customer's full name is included in the post. The name includes the scenario "When the Customer's full name is entered" and the expectation: "Customer Added Successfully".

Including the scenario is the critical part of your test name. It explains the conditions of the action you’re performing. "When I do this". "When this data is included". "When I try to access this as an administrator".

The expectation is your expected result. The outcome of the test. This is as critically important as the scenario. Together they form a combination explaining the reason the test exists. "When this happens, this should happen".

Some of you may be aware of the pattern "SystemUnderTest_When_Then" for naming tests. This is fine, and I would recommend this structure, but only because it includes the scenario and the expectation. System under test, or the thing that you're testing, is descriptive and useful of course, but it can be easily inferred by looking at the code (unlike the scenario; and expectations can usually be easily gleaned from the Assertions), and also, you could include this in the class name, tags, or some other descriptor.

It's the scenario and expectation that anyone looking at the tests wants to know. These are the critical parts of a test's name.

Getting this right not only means that your tests are easy to follow and understand, but it encourages you to think up more combinations. You can write these combinations of scenario/expectation out before you even complete the bodies of the tests. If you were to name a test "GetTimeZoneTest", or "FileProcessorTest" how would you do this?

It's worth noting too, that you can include everything I talk about here in Description Attributes, or Tests Cases, if that's preferred, over the Test name. The point is that it's clear what the tests are doing.

By including the scenario and the expectation in your test names/descriptions, it will encourage you to think like a tester. You will become concerned with why you are writing the tests, and learn to link scenarios with expectations.

It will also make your tests easy to read and forms helpful documentation for future maintainers.

Don't Chase Unit Test Coverage

Stuart Dobson — Sun, 13 Nov 2022 09:57:18 +0000

In the long running battle between management chasing metrics and developers just trying to get the job done, (hi boss!) I wanted to provide some less obvious examples of why chasing code coverage is a damaging process.

Why Unit Test Code Coverage targets are bad

Code Coverage can be gamed, incentivising low quality tests

If the coverage percentage is all that matters, there are many ways to increase that number without actually improving the quality and reliability of the code. Having a test doesn’t mean no bugs - it just means the code is being run by a test, that the pathways through the code are exercised by another piece of code.

There’s not really any link in these tests to importance of functionality, or even any consideration of code doing the right thing, just that it’s being exercised.

Tests add a maintenance burden

In the writing of low value tests written only to satisfy KPIs, developers are actually making more work for themselves in the future.

All code adds a maintenance burden. Tests are code so adding tests adds to this burden. If they’re not valuable, they’re detrimental.

Chasing coverage leads to more brittle tests

The more coverage you have, the more brittle your tests actually become. By covering every internal path of a method, you are tightly coupling the tests with the implementation details.

This goes against the spirit of testing. You should be testing the functionality of the code - the inputs, outputs, and decisions it makes, and the edge cases.You don’t need to be too concerned with how it makes those decisions.

This in turn makes you write tests the right way - thinking about the desired functionality instead of the coverage.

Give a false impression of robust code

It should be obvious but it’s often overlooked. High coverage, which as discussed leads to low quality tests which often don’t test the right things, gives a false sense of security. You may have 80% coverage but if the last 20% is all the business critical functionality, or vital areas of the code, this could be hiding big problems.

Chasing metrics hides opportunities to improve the code quality

Let’s remember why we write tests in the first place. It’s to have confidence that our code is meeting the requirements, can handle edge cases, and is free of bugs. By focusing on coverage, you are missing the opportunity to write tests which do this - tests which actually lead to better quality code.

Thinking about what scenarios you need to cover when writing code, encourages you to write the code in a testable way. If you write it in a testable way, you’ll be more likely to write tests - valuable tests. Better still, you’ll be more inclined to write the tests, or at least stubs of them, first (Test Driven Development).

If you write code and then add tests as an afterthought, you’ll probably focus on coverage instead of functionality, because you’ll be thinking about “adding tests” and increasing coverage - rather than thinking about the original intentions of the code.

Why Code Coverage is good

Despite all these issues, Code coverage has a place in software development and there are some benefits to monitoring it, as opposed to incentivising it.

Identifies areas of low coverage

In combination with your knowledge of where important functionality lies, you can see where tests are needed. Without code coverage metrics, it’s pretty hard to do this.

Instills a culture of continually adding tests as you go

Let’s not forget that we want to be writing tests. We’ll get good coverage just by doing it as a habit, and by monitoring the coverage, we’ll see it go down if we write code that’s untested. So this encourages us to keep up with writing tests as we add features, and helps us see when we’re not adding them.

This keeps test writing on everyone’s minds, and influences the culture to make people value tests.

If you’re not measuring, you don’t know if you’re improving!

Conclusion

This article is very much a developer’s perspective, but at the end of the day, code coverage is a Return on Investment decision. Care should be taken on where the coverage is increased. Writing tests for existing code should be done in a way that prioritises high value, low effort new tests.

Code coverage is a good thing in that it gives a picture of where you are, and helps you monitor your testing journey. It’s always problematic to incentivise metrics, or even push to maintain a level. But we should be mindful of the level of coverage.

Focus on code coverage detracts from why you should be writing tests in the first place. The important thing is that we build tests around requirements and edge cases - tests which exercise and document real life scenarios. Tests are not about lines of code covered. This is an indicator - not an incentive.

Writing tests is a very important part of software development. Do it for the right reasons, and it will be done well.

The Importance of Good Acceptance Criteria

Stuart Dobson — Thu, 23 Sep 2021 07:49:50 +0000

Acceptance Criteria can be seen as a chore, a convoluted, verbose set of prose with the sole purpose of satisfying "the business". At best, its value is underestimated and it is often written as a vague list of requirements.

Given the right attention, Acceptance Criteria can be extremely valuable to all members of a Scrum team. Before it can be done correctly, we have to understand its value.

So what exactly is the point of Acceptance Criteria?

Purpose of Acceptance Criteria

To define boundaries

Acceptance criteria help development teams define the boundaries of a user story. In other words, acceptance criteria help you confirm when the application functions as desired.

To reach consensus

Having acceptance criteria synchronises the development team with the client. The team knows exactly what conditions should be met, just as the client knows exactly what to expect from the developed functionality.

To allow for accurate planning and estimation

Acceptance criteria scenarios allow for the correct division of user stories into tasks so user stories are correctly estimated and planned.

To serve as a basis for tests

Acceptance criteria provide a good baseline for writing tests. Test cases can break down Acceptance Criteria to go into more functional detail, and to cover edge cases.

Acceptance Criteria helps the team deliver quality

Acceptance Criteria is vital for delivering quality. If done correctly, it can simplify development and guide a comprehensive testing strategy. It is the glue that holds requirements together.

Acceptance Criteria is valuable to all stakeholders; Developers, QA, Product Owners, and the team as a whole. How it helps each stakeholder, however, varies according to their role.

Good Acceptance Criteria

How it benefits Developers

Good Acceptance Criteria gives developers clarity and allows them to break down their tasks into manageable pieces of functionality. With visibility of all possible scenarios, good Acceptance Criteria actually allows optimum design of the code. It enables developers to structure their code in a way that best meets the requirements. The code can be written around each scenario, ensuring each criteria is met in the simplest way possible.

The clarity given by good Acceptance Criteria keeps the business requirements at the forefront of the developer's mind, helping them to avoid getting bogged down in technical details which may not be conducive to the task.

How it benefits QA

Good Acceptance Criteria can guide QA in generating test cases and any required test data. With clear, simple scenarios, QA will have a solid base for test cases, and can then focus on expanding the Acceptance Criteria to cover edge cases.

Without clear, broken down Acceptance Criteria, it can be hard to work out test cases. If this happens, certain scenarios might be missed, and the important expectations of the job might be overlooked.

How it benefits the team

Good Acceptance Criteria helps get all the team on the same page. It aligns everyone with common goals, and helps them work together to build out the requirements. This collaboration is important and often overlooked.

Development and QA can come together at the start of a task in order to work out what needs to be tested. This allows Development to perform some degree of Test Driven Development. Even if it isn't possible to write automated tests before the code, the developer will at least have a good idea of what those tests are going to be before writing any code.

QA can guide this process, elaborating on what they will be testing, helping to set up test data, and informing the developer of possible edge cases to watch out for.

If the Acceptance Criteria is missing anything, the Product Owner can be questioned for more details before the work commences. Without clear Acceptance Criteria, there is no way of knowing if there are any missing details.

Good Acceptance Criteria can make a difference

With good Acceptance Criteria, the team is able to see, at a glance, what is required from a task. It provides a consensus for the whole team which aids both planning and delivery.

Good Acceptance Criteria helps developers come up with cleaner code. It makes testers' lives much easier. It helps the team come up with the best Automated Testing solutions, which is vital for Agile projects. It helps the team plan the best possible approach, and avoids stumbling into questions mid-development.

Don't underestimate the value of good Acceptance Criteria. It can increase productivity, collaboration, and quality.