Spec-Driven Development: Two Claude Skills That Close the Loop

A conversation on LinkedIn got me thinking about how I actually build software with Claude Code these days. Marc Green posted a 13-step workflow for spec-driven development with AI agents, and it resonated with me immediately. Not because it was new, but because it put names to the things I'd been doing instinctively and exposed the gaps I hadn't filled yet.

Marc's core argument: coding via agents doesn't need to lead to bad code hygiene. You just need a process. His workflow frontloads decision-making into specs and plans, then lets the agent execute with guardrails. The last step is the most important: reflect on what went wrong and backpropagate those learnings into your "agentic harness" - your CLAUDE.md files, hooks, skills, and subagents.

I agree completely. And I want to share two Claude skills I've built that slot directly into this workflow.

The Workflow

Here's Marc's 13-step process, paraphrased:

1. Write down everything relevant about the feature
2. Brainstorm with Claude to explore the design space
3. Subagents verify the spec against CLAUDE.md files
4. Manually review the spec for gaps or over-specification
5. Write an implementation plan
6. Subagents review the plan against the spec and repo patterns
7. Skim or deeply review the plan depending on complexity
8. Execute the plan with automated review at each step
9. Practice swordfighting while waiting (his words, not mine)
10. Deep code review (automated + manual)
11. Test the implementation
12. Fix any bugs
13. Reflect on bugs and imperfections, then backpropagate learnings into the harness

The crux, as Marc puts it, is step 13. It's conceptually simple but not always easy - you need to figure out how to adjust your harness so the same class of bugs won't happen again. When just starting out, investing time into the harness can feel less productive. But as each class of issue gets captured, the speedup becomes exponential.

I've been running a similar process. But two things kept biting me: missing edge cases that only surface during testing, and documentation drifting out of sync with the code. So I built skills for both.

Skill 1: Feature Impact Analysis

Where it fits: Between steps 6 and 8 - after you have a plan but before you start coding.

The problem is subtle. You can have a solid spec and a solid plan, but new features don't exist in isolation. They intersect with existing functionality, and edge cases live at those intersections. A new "archive" feature seems straightforward until you realize: do archived items show up in search results? Do count badges include them? What happens to a bulk operation that includes both archived and active items?

This skill systematically walks through every existing feature and asks: how does the new thing interact with this? It uses a framework of six question types:

The skill reads my project's feature documentation (more on that in a moment) to understand the system holistically before analyzing. It doesn't just think about the new feature in isolation - it maps every intersection.

What it looks like in practice

You invoke the skill after your plan is reviewed but before execution. You point it at your design doc. It produces a categorized list of edge cases grouped by type: display/UI conflicts, data consistency issues, user workflow interruptions, search/filter behavior, performance implications, and migration needs.

The output feeds directly back into your plan. Sometimes it catches things that change the plan significantly. Sometimes it confirms you've already covered everything. Either way, it takes minutes and has saved me hours of debugging after the fact.

Skill 2: Documentation Update

Where it fits: At or around step 13 - after changes are committed.

This one addresses a problem every developer knows: documentation that doesn't match the code. The usual approach is to update docs manually, which means they're perpetually slightly wrong. The agentic approach is to make documentation updates part of the development workflow itself.

After I commit a feature or fix, this skill updates three layers of documentation:

1. CHANGELOG - User-facing: what changed, written from the user's perspective
2. Project Context Docs - Feature documentation: how things work, what they do, how they connect
3. Technical Docs - Implementation details: API endpoints, database schema, architecture

The project context docs are the key piece. I keep these in an Obsidian vault and symlink them into the project so Claude Code can see and update them. Each doc covers a feature area, and the skill knows which docs map to which types of changes. I wrote a separate guide on this symlink pattern if you want the full setup.

Why this matters for the whole workflow

Here's the connection that makes these two skills work together: the documentation skill's output is the impact analysis skill's input.

When the documentation skill updates project context docs after a feature ships, it's maintaining the knowledge base that the impact analysis skill reads before the next feature. Feature docs describe how everything works and interconnects. Impact analysis uses that understanding to find edge cases at intersections.

It's a feedback loop:

Build feature → Update docs → Next feature → Analyze impact using docs → Build → Update docs → ...

Without current documentation, impact analysis is guessing. Without impact analysis, you're shipping edge cases that become bugs that become documentation updates anyway - just slower and more painful.

The Broader Point

Marc's step 13 - backpropagating learnings into the harness - is where the compounding happens. Every time I hit a class of bug that impact analysis could have caught, I refine the analysis framework. Every time documentation drifts, I refine the documentation skill's mapping tables.

The skills themselves are living documents. They get better as the project evolves because they encode the lessons learned from each iteration. That's the exponential speedup Marc describes: not from any single improvement, but from the systematic capture of every class of issue into the harness.

If you're doing agentic development without this kind of structure, you're leaving that compounding on the table.

Get The Skills

I'm sharing both skills below. To use them:

1. Create the skill directories in your Claude folder: .claude/skills/feature-impact-analysis/ and .claude/skills/update-docs/
2. Download the skill files and save them as SKILL.md in their respective directories
3. Adapt to your project: Update file paths and document mappings to match your project structure
4. Use them: Invoke impact analysis after planning, documentation after committing

Feature Impact Analysis

Place this into .claude/skills/feature-impact-analysis/SKILL.md

Download Feature Impact Analysis Skill

Documentation Update

Place this into .claude/skills/update-docs/SKILL.md

Download Documentation Update Skill

Note: The documentation skill references an Obsidian vault with symlinked project docs. You'll want to adapt the file paths and mapping tables to your own project structure. The pattern - not the specific paths - is what matters.

Try It and Let Me Know

I'm refining this workflow in real-time. If you use these skills, extend them, or find gaps I've missed, I'd love to hear about it. Connect with me on LinkedIn.

And credit where it's due - thanks to Marc Green for the post that inspired this writeup. Go give him a follow if you're interested in agentic development workflows.

If you're exploring AI-enhanced development workflows, check out what I'm building at PromptBlocks.