Coding agents work quickly, but speed is valuable only when the intended destination is clear. Vague requests force an agent to make hidden assumptions about behaviour, architecture, security and scope. The result may look convincing while solving the wrong problem.
Specification-driven development makes intent explicit before implementation begins. It combines concise requirements, examples, constraints, interfaces, architectural decisions and executable acceptance criteria. The specification becomes a shared control surface: people can review it, agents can act on it, and automated systems can verify the result.
This course teaches a proportionate approach. Participants will learn when a lightweight task contract is enough, when a more formal specification is justified, and how to keep specifications useful as software evolves.
Learning Outcomes
Upon completion of this course, participants will be able to:
- Explain why coding agents increase the value of precise, testable specifications
- Choose an appropriate level of specification for different types of work
- Convert business intent into behaviours, constraints and measurable acceptance criteria
- Record architectural decisions and boundaries that an agent must respect
- Structure specifications for both human review and machine use
- Generate implementation plans and tests from approved specifications
- Establish traceability between requirements, code changes, tests and evidence
- Manage specification changes without allowing documentation and implementation to diverge
Course Outline
Why Specifications Matter in Agentic Development
- The cost of ambiguity when implementation is inexpensive
- Hidden assumptions made by coding agents
- Specifications as feedforward controls for probabilistic systems
- Differences between prompts, task briefs, requirements and formal specifications
- Balancing precision with speed and maintainability
- Selecting work that benefits most from a specification-first approach
From Intent to Observable Behaviour
- Identifying users, goals, triggers and expected outcomes
- Writing behavioural requirements without prescribing unnecessary implementation
- Defining normal paths, edge cases and failure behaviour
- Using examples and counterexamples to remove ambiguity
- Separating requirements from preferences and possible future work
- Making acceptance criteria objective and testable
Capturing Constraints and Non-Goals
- Recording scope boundaries and explicit non-goals
- Security, privacy, performance and compliance constraints
- Compatibility requirements and supported environments
- Data contracts, retention rules and permission boundaries
- Dependency, licensing and technology constraints
- Preventing agents from broadening scope during implementation
Architecture as Part of the Specification
- Defining system boundaries, components and responsibilities
- Capturing interfaces, schemas and integration contracts
- Using architecture decision records to explain important choices
- Identifying invariants that must remain true
- Providing reference implementations and established codebase patterns
- Allowing implementation freedom without losing architectural coherence
Structuring Specifications for Agents
- Organising goals, context, constraints, deliverables and validation
- Using clear language and consistent terminology
- Referencing authoritative files and documentation
- Combining human-readable Markdown with structured data where useful
- Versioning specifications alongside source code
- Detecting contradictory, stale or incomplete instructions
Planning and Executing from a Specification
- Asking an agent to analyse feasibility before implementation
- Producing a task decomposition and dependency-aware plan
- Reviewing proposed files, interfaces and migration steps
- Establishing approval points for consequential decisions
- Running implementation in bounded stages
- Keeping evidence and decisions attached to the work
Executable Specifications and Quality Gates
- Translating acceptance criteria into automated tests
- Contract, integration, property-based and end-to-end testing
- Using static analysis and policy checks for non-functional constraints
- Creating deterministic gates around agent-generated changes
- Verifying that tests fail for incorrect implementations
- Capturing test results and operational evidence
Traceability and Change Management
- Linking specifications to issues, commits, pull requests and tests
- Handling requirement changes during implementation
- Preventing code, tests and documentation from drifting apart
- Reviewing agent-proposed specification changes separately from code
- Maintaining decision histories for regulated environments
- Defining ownership and approval responsibilities
Practical Capstone
- Convert an ambiguous feature request into a proportionate specification
- Define behaviours, constraints, interfaces and non-goals
- Produce and review an agent-generated implementation plan
- Generate executable acceptance tests and quality gates
- Implement a bounded change using a coding agent
- Demonstrate traceability from intent to verified result
Intended audience
This course is intended for experienced developers, technical leads, architects, business analysts, product engineers and test professionals who define or supervise work completed with coding agents. It is particularly useful for teams that need repeatable, auditable delivery rather than informal prompt-and-accept workflows.
Prerequisites
Those attending this course should meet the following:
- Professional software development or technical analysis experience
- Familiarity with Git, code review and automated testing
- Basic experience using an AI coding assistant or agent
- Understanding of APIs, system boundaries and non-functional requirements