Specification-First Agentic Development: A Methodology for Structured, Traceable AI-Assisted Development

I like clean code. Most of the programs I've written over the years are reasonably well structured. Sure, there's always that moment every two years where I look at old code and think — evolved, great. Stagnation is dead. But the code follows the "right" rules, whatever that means at the time. Most importantly, it follows a common thread.

As a freelancer switching between IIOT applications, web apps, message-based backends, infrastructure automation, and pipelines, I'm mostly in the luxury position of being able to forget what I did and understand it again quickly just by reading the lines and the folder structure.

But what I very rarely do is document the why.

The Religious Wars of Documentation

You know the debate. Using IDE features to auto-generate docs for classes and methods that add exactly zero value:

/// <summary>
/// Gets a blue collar worker 
/// </summary>
public class GetBlueCollarWorkerRequestHandler(
    ILogger<GetBlueCollarWorkerRequestHandler> logger,
    IBlueCollarWorkerAdapter blueCollarWorkerAdapter) 
    : IRequestHandler<GetBlueCollarWorkerRequest, GetBlueCollarWorkerResponse>

When the method is called Handle and the class is called GetBlueCollarWorkerRequestHandler, I really don't need "Gets a Blue Collar Worker" written above it.

So personally I only document two things:

1. Official interfaces — Swagger/REST APIs, NuGet/npm packages, libs
2. Problematic areas — when I write something genuinely non-obvious, with links to sources

Sometimes that's enough. But it doesn't help you get an overview of why the program works the way it does. Documentation of the "why" takes time. I use Arc42 with Architecture Decision Records — but that's in a separate repository, and it only covers architectural thoughts, not implementation decisions made feature-by-feature.

Result: six months after shipping, nobody remembers why anything was built the way it was.

How Developer Work Has Changed

We've all been through the evolution:

• Stack Overflow copy-paste (okay, I did it)
• ChatGPT copy-paste (I lied, I did both)
• Claude/Codex in the IDE writing the code for me

When I started with AI-assisted coding, I ran into the usual problems:

• Claude just implements things. Lots of code. Am I still going to read all of it?
• Using claude.md and coding principles — Claude sometimes just ignores them
• Well-structured code → Claude produces good results. Bad code → Claude makes it worse
• Beyond a certain complexity, Claude starts doing weird things
• "Just let him do" is a terrible idea, even when you're working on three things in parallel
• Context-switching between parallel topics is hard for humans, harder for AI

And then there were the recurring annoyances with IDE-based Claude:

• After context is lost, I waste a lot of tokens just getting back to where I was
• Long chat threads create cluttered history — and once it's gone, re-explaining everything is exhausting
• Every restart, I'm explaining the entire project from scratch again

Specification-First Agentic Development

I felt my approach wasn't good enough. It wasn't leveraging what AI could do — specifically: document whatever you want, without complaining, which is something I as a developer was never willing to do consistently.

The Core Idea

Instead of staying in the IDE and trying to keep track, I needed a more structured approach:

• Everything gets written down
• The AI needs to know where it was and what to do next
• I need to track what's changed, what's planned, and what's done

The Phase Workflow

Here's how it looks in practice:

1. Discuss new things in Claude Web (not the IDE)
2. Build a rough plan and create a .md document from the conversation
3. Move the file to the IDE — let Claude double-check the document, ask questions, resolve ambiguities
4. Move to planned/

When it's time to implement, Claude always knows exactly which phases exist and how to handle them.

The Folder Structure

.agentsmith/phases/
├── done/       # completed phases (historical reference)
├── active/     # phase currently being worked on (max 1)
└── planned/    # upcoming phases with requirements

The claude.md Instructions

## Implementation Workflow (follow this order for every phase)

1. Write phase prompt first — create planned/p{NN}-slug.md BEFORE writing any code
2. Move to active — when starting work
3. Enter plan mode — explore codebase, design approach, get approval before coding
4. Implement step by step — contracts first, then implementation, then DI, then tests
5. Build after each step — fix errors immediately
6. Run ALL tests — 0 failures before moving on
7. Log decisions — append to decisions.md (what, alternatives, why) — MANDATORY
8. Update context.yaml — move phase from active to done
9. Move to done
10. Commit — one commit per phase

The Decision Log

After every phase, Claude appends to decisions.md in the repo:

## p66: Docs Enhancement — Self-Documentation & Multi-Agent Orchestration

- [Architecture] DESIGN.md placed in docs/ not project root — it is a docs-site
  concern, not product code
- [Tooling] CSS-only theme overrides via extra_css, no custom MkDocs templates —
  keeps MkDocs upgrades safe
- [TradeOff] Content first, styling second — missing content is a blocker,
  imperfect styling is not

## p67: API Scan Compression & ZAP Fix

- [Architecture] Category slicing (auth/design/runtime) instead of finding
  compression — findings are already compact at ~90 chars/piece, compression
  would lose information
- [Implementation] Skip DAST skills on ZAP failure via ZapFailed flag — avoids
  wasting 2 LLM calls on empty input

Six months later, when nobody remembers why anything was done the way it was — it's all right there.

Saving Tokens with context.yaml

Having all these documents in the repo, I don't want Claude to re-read everything from scratch every time. That's what context.yaml is for.

It describes the architecture, stack, integrations, quality rules, and — critically — a compressed summary of every phase:

meta:
  project: agent-smith
  version: 1.0.0
  type: [agent, pipeline]
  purpose: "Self-hosted AI orchestration framework: code, legal, security, workflows."

stack:
  runtime: .NET 8
  lang: C#
  infra: [Docker, K8s, Redis]
  testing: [xUnit, Moq, FluentAssertions]
  sdks: [Anthropic, OpenAI, Google-Gemini, Octokit, LibGit2Sharp]

state:
  done:
    p01: "Solution structure, domain entities, contracts, YAML config loader"
    p02: "Command/Handler pattern: 9 context records, 9 handler stubs, CommandExecutor"
    p03: "Providers: AzureDevOps+GitHub tickets, Local+GitHub source, Claude agentic loop"
    p04: "Pipeline execution: IntentParser, PipelineExecutor, ProcessTicketUseCase, DI wiring"
    ...

Claude knows directly what features have been implemented just by reading this file — and knows which phase document to look at for details.

An Interesting Parallel: Karpathy's Knowledge Base

Andrej Karpathy recently wrote about using LLMs to build personal knowledge bases: collecting external material into a raw/ directory, letting the LLM compile it into a linked markdown wiki, then running Q&A against it.

The structural parallel is obvious. But there's a key difference:

• Karpathy collects external knowledge — papers, articles, datasets
• Specification-First Agentic Development persists internal knowledge while building the product

The documentation isn't a separate artifact you create after the fact. It's generated as a side effect of the development process itself.

A Real Example: The Documentation Site

As all features, bugfixes, ideas, and decisions are already documented in the repo, it's not surprising that Claude can generate full technical documentation rapidly — and accurately.

Phase 53 of my project was exactly this:

# Phase 53: Documentation Site

## Goal: Technical documentation at docs.agent-smith.org

Complete file structure, MkDocs Material setup, GitHub Actions
deployment, README reduction to essentials...

How long did it take? About 15 minutes. Because all the information was already there — in the phase files, the decision log, the context.yaml. Claude just had to synthesize it.

I really celebrated that one.

Summary

Specification-First Agentic Development is just how the work is structured. It defines phases directly in code, producing a consistent development pattern that includes the plan, the decisions, and the reasoning.

The benefits:

• Fewer wasted tokens — context.yaml gives Claude what it needs without re-reading everything
• Parallelism — multiple phases can be planned and tracked simultaneously
• Traceability — every decision is logged with alternatives and rationale
• Restartability — restart your machine, restart Claude, pick up exactly where you left off
• Self-documentation — the docs practically write themselves

It's not rocket science. It's just discipline — finally enforced by a patient AI that never complains about writing things down.

GitHub Repo with the template and howto explanation.
Agent Smith implementation where the idea was born GitHub repo
Originally posted on CodingSoul