DEV Community

Cover image for Beyond "Vibe Coding": Bringing SDD and PDCA to Claude Code
Slim
Slim

Posted on

Beyond "Vibe Coding": Bringing SDD and PDCA to Claude Code

#claudecode #ai #productivity #devops

Let's be real for a second. We've all been there with AI coding tools (Claude Code, Cursor, Windsurf, etc.).

You ask for a feature. The AI writes code. The tests fail. The AI says "Apologies, I'll fix that." It churns for 30 seconds, and suddenly—green lights! 🎉

You feel great until you check the diff.

The AI didn't fix the code. It deleted the assertion. Or worse, it rewrote the test to match the broken behavior.

AI models optimize for completion, not correctness. They crave the dopamine hit of a passing test suite, and they don't care how they get there.

I spent three months fighting this "cheating" behavior. I tried elaborate prompts, threats in system instructions, and complex frameworks. Nothing stuck reliably.

So, I built PactKit.

It’s not a heavy SDK. It’s not a wrapper API. It’s a Prompt-as-Code infrastructure that turns Claude Code into a disciplined Senior Developer.

Here is why it’s different, and why I believe it solves the context problem better than the alternatives.

The Hierarchy of Truth (SDD)

The root cause of AI hallucinations in coding is a lack of structured "Truth." If the code, the test, and the user prompt are all equal citizens in the context window, the AI will change whichever one is easiest to change.

PactKit enforces a rigid Spec-Driven Development (SDD) hierarchy:

  1. 🥇 Tier 1: Specification (docs/specs/*.md) — The Law. Immutable during the coding phase.
  2. 🥈 Tier 2: Tests — The Verification. Can only be changed if they conflict with Tier 1.
  3. 🥉 Tier 3: Implementation — The Reality. Must yield to Tier 1 and Tier 2.

When you run pactkit init, it injects this "Constitution" into Claude. Now, when a test fails, the agent knows it is forbidden to lower the bar. It must climb the hill and fix the implementation.

Strict TDD & The PDCA Loop

"Vibe coding" (coding by feeling) is fun, but it creates technical debt at mach speed. PactKit forces a PDCA (Plan-Do-Check-Act) workflow that feels like a seatbelt.

You don't just say "make a login page." You run:

/project-sprint "Implement OAuth2 Login"
Enter fullscreen mode Exit fullscreen mode

The system forces the agent through four distinct phases:

  1. Plan: The Architect Agent analyzes your codebase structure (generating a Mermaid graph) and writes a Markdown spec. No code is written yet.
  2. Act: The Developer Agent reads the spec and writes failing tests first. Only then does it write the implementation.
  3. Check: The QA Agent runs the suite, checks for security issues (OWASP), and verifies spec alignment.
  4. Done: The Maintainer Agent cleans up and commits.

It sounds rigorous, but because it's automated via Claude Code commands, it feels incredibly fast.

Why not OpenSpec or SpecKit? (The Context Problem)

This is the question I get asked the most. Why build a new tool when OpenSpec or SpecKit exists?

The answer is Context Management.

Tools like OpenSpec are powerful, but they tend to be "heavy." They often rely on complex JSON/YAML schemas or extensive external documentation.

Here is the problem: LLMs have a limited attention span.

If you dump a 500-line JSON schema and a massive framework documentation into the context window, the model gets "distracted." It spends its tokens trying to parse the format rather than solving your problem.

PactKit is designed to be "Context-Native":

  • Markdown First: Everything is Markdown. Specs are Markdown. Plans are Markdown. LLMs speak Markdown natively; it costs them almost zero cognitive load.
  • Visual Context: Instead of feeding the agent 50 files to understand the project structure, PactKit generates a code_graph.mmd (Mermaid diagram). The agent reads the map, not the entire territory. This saves massive amounts of tokens and keeps the agent focused.
  • Just-in-Time Loading: The Plan phase doesn't load the Act rules. The Check phase doesn't load the Plan tools. We swap "Agent Personas" dynamically to keep the context clean.

PactKit is simple by design. It doesn't try to be a universal data standard. It tries to be the most efficient way to communicate intent to an LLM.

How to try it

PactKit is open source and works directly with your existing Claude Code setup.

pip install pactkit
pactkit init
Enter fullscreen mode Exit fullscreen mode

Then, just start your next feature:

/project-plan "Refactor the user service"
Enter fullscreen mode Exit fullscreen mode

If you are tired of babysitting your AI to make sure it's not deleting your tests, give PactKit a shot. It turns the AI from a chaotic intern into a disciplined engineer.

Top comments (0)