Lesson 18 of 65 · Free to read
Day 18 ΓÇö Comment-driven and spec-driven development.
Month 1 · Week 4 — Context Engineering Audience: Final-year students & early-career engineers (0–3 years) Format: Self-paced study + optional live clinic · Suggested time: 4–6 focused hours Key tools: GitHub Copilot, Cursor
Overview
Spec-driven and comment-driven development flip the order: write the contract, then let AI fill the body. Review for fidelity to the spec.
Learning objectives
By the end of this session, you can:
- Explain the core ideas behind: Comment-driven and spec-driven development.
- Apply the ideas using GitHub Copilot, Cursor on a realistic task (capstone, internship, or first-job style)
- Produce the exercise deliverable with clear success criteria
- Identify common failure modes and how to recover
- Capture at least one reusable prompt, rule, or checklist for your personal library
- Decide what must remain human-reviewed for this class of work
Core concepts
Spec skeleton
Inputs, outputs, errors, invariants, examples. Leave // TODO(ai): implement regions intentionally.
Fidelity review
Check edge cases named in the spec — models love happy paths.
Tooling for today
Primary tools: GitHub Copilot, Cursor. Prefer official docs when APIs change. When a model invents a symbol, verify against source or docs immediately.
Practice posture
You are a final-year or early-career engineer pairing with a very fast teammate (the model): clear intent, grounded context, inspect consequential changes, keep a paper trail (commits, prompts, decisions).
Process diagram
Watch & learn
Study these free videos before or during the exercise. Each embed is chosen to reinforce today's objectives.
Course video
Course video
Worked example / case study
Scenario
Write a detailed comment/spec skeleton; generate implementation; review against the skeleton line by line.
Step-by-step
- Clarify the outcome in one sentence tied to the exercise below.
- Gather grounding context (files, docs, schema, acceptance checks).
- Run the primary tool(s): GitHub Copilot, Cursor.
- Produce the smallest vertical slice that proves the idea.
- Verify with a command, test, screenshot, or side-by-side comparison.
- Write down one steering note — what you told the AI when it went wrong.
Sample prompt you can adapt
Role: Senior engineer mentoring an early-career developer (pairing with me).
Task: Comment-driven and spec-driven development.
Context: Final-year / early-career project (capstone, internship, or junior role).
Constraints:
- Match existing project patterns
- No new dependencies unless justified
- Include tests or a verification checklist
- Call out assumptions explicitly
Output: step plan first, then code/files, then verification commands.
Hands-on exercise
Primary task. Write a detailed comment/spec skeleton and let the AI fill in the implementation, then review for fidelity.
Coaching notes
Turn the skeleton into a checklist in the PR description.
Steps
- Set up or open the workspace required by: GitHub Copilot, Cursor.
- Skim today's core concepts and watch the video(s) before prompting.
- Execute the task in small commits (or saved artifacts if no-code).
- Fill the success checklist below.
- Note one surprise and one process improvement for tomorrow.
Success criteria
- Deliverable matches the exercise description
- You can explain every AI-generated change in plain language
- Verification ran (tests, manual check, or published URL)
- At least one pitfall from this lesson was consciously avoided
- Artifact saved (repo commit, doc, or published link)
Timebox
Suggested: 90–150 minutes of focused build time after study.
Templates & checklists
| Asset | Purpose |
|---|---|
| Prompt stub | Reuse today's structure (role → task → constraints → format) |
| Verification checklist | Tests / manual QA / security skim |
| Decision log | What you delegated vs kept human |
Copy-paste prompt skeleton
## Goal
Comment-driven and spec-driven development.
## Context files
- (list paths)
## Constraints
- Stack: (fill)
- Do not: (secrets, drive-by refactors)
## Definition of done
- Write a detailed comment/spec skeleton and let the AI fill in the implementation, then review for fidelity.
Daily reflection (3 minutes)
- What did AI do well?
- Where did it confidently fail?
- What rule will you add to your cookbook/rules file?
Common pitfalls
- Specs that omit errors
- Accepting extra unrequested features
- Deleting the spec comments after generation
Key takeaways
- Spec is the source of truth
- Happy-path bias is predictable — counter it
- Keep specs in git
- Tools (GitHub Copilot, Cursor) change; the judgment skills transfer.
Resources
- Official docs for: GitHub Copilot, Cursor
- Course cookbook: keep prompts in a versioned Markdown file in your repo
- Prior days this week — skim objectives if you skipped ahead
Self-paced lesson — Mastering AI-Assisted Development & Vibe Coding — Day 18 of 65.