[SDD Plugin] The Pitfalls of AI Coding and a Path Forward

Overview

When you use AI coding tools like Claude Code in practice, you quickly discover several problems hiding behind the ability to write code fast. In this post, I’ll organize those problems and share why I decided to create the SDD (Spec-Driven Development) Plugin.

This post is part of the SDD Plugin series. The completed plugin’s structure and usage is covered in SDD Plugin: Full Structure and Usage, the development journey in From Prototype to Completion, and the engineering principles in Analyzed Through 4 AI Engineering Paradigms.

The Pitfalls of AI Coding

Claude Code lets you write code at an amazing speed. Say “build this feature” and code appears almost instantly. I was impressed at first, but after using it repeatedly in real projects, a few issues became hard to ignore.

Coding Without Requirements Analysis

When you tell the AI “build this feature,” it jumps straight into writing code. But if What and Why aren’t clear, the code might not match what you actually wanted. And by the time you realize it’s heading in the wrong direction, quite a lot of code has already been written.

Implementation Without Design

Every codebase has its own architecture and patterns. But AI often ignores them and implements things its own way. The result is a mix of inconsistent styles that makes maintenance harder.

No Tests

Code gets written quickly but without tests, making it difficult to catch side effects when making changes later. Sometimes you don’t even fully understand the logic of AI-generated code yourself.

Lost Conversations

When Claude Code conversations get long, context gets compressed. When a conversation breaks, previous context disappears. You end up relying on memory to figure out what was decided and how far things progressed.

Limitations of Existing Development Processes

Even if your team already has a development process, it’s hard to follow when using AI coding tools.

Explaining “follow this process” to the AI every time is inefficient, and everyone explains it differently, leading to inconsistency. Even with a process in place, it tends to get ignored when working with AI.

How Far Can Claude Go?

After recognizing these problems, I tried working with AI using a structured process. I installed GitHub CLI and worked with Claude Code in the following flow:

1. Task Analysis: Pass GitHub Issues or requirements to Claude and ask “analyze this and outline the problems and tasks”
2. Review the Analysis: Check what Claude analyzed and give feedback where it’s off — “shouldn’t this part be handled differently?”
3. Implementation: Once satisfied with the analysis, instruct implementation
4. AI Code Review: After implementation, improve quality with prompts like “review these changes” or “any refactoring opportunities?”
5. Self Code Review: Review the AI’s review results, plus do your own review
6. Review Response: Forward other team members’ review comments to Claude for analysis

After repeating this process, I learned a few things:

• AI is surprisingly reliable. Analysis and review results were quite accurate.
• AI could be leveraged in nearly every development stage.
• But leaving everything 100% to AI is unrealistic. A human needs to explain the task, review results, and make appropriate judgments.

From Code Generation Tools to SDD

Initially, I was building a separate tool to auto-generate boilerplate code from design documents — drawing screens in Drawio, defining components in spreadsheets, and generating base code with a code generator.

But while developing this tool, I heard that Claude Code’s Skill feature alone could produce results comparable to a code generation tool. So I pivoted. Instead of building a separate tool, the idea became: design a development process that AI can work with effectively.

An approach called Spec-Driven Development (SDD) already existed — a methodology where you define specifications first, then AI develops automatically based on those specs.

• github/spec-kit
• gotalab/cc-sdd
• Fission-AI/OpenSpec

Using these open-source projects as references, I decided to build an SDD Plugin for Claude Code tailored to my practical experience.

The Solution

I concluded that turning the development process itself into a Claude Code plugin would have these benefits:

• Execute the process with a single command. No need to explain the process to AI every time.
• All artifacts are stored on GitHub, so you can resume work even if a conversation breaks.
• The whole team can follow the same process. Just install the plugin.

Designing the Process

1. Analyzing the Development Process

To design the specific process, I first needed to analyze the steps we typically go through when developing software. So I asked Claude about a typical development process.

1. Requirements Analysis
2. Design
3. Implementation
4. Code Review
5. Testing
6. Deployment (Merge & Deploy)
7. Monitoring

Since deployment and monitoring aren’t tasks you do together with AI, I decided to make all the remaining processes workable with generative AI.

2. Defining Input and Output

Next, I defined the Input and Output that generative AI needs for each process stage. For the implementation stage, I decided to use TDD (Test Driven Development) for better code accuracy and quality.

1. Requirements Analysis
   • Input: Requirements document
   • Output: Requirements analysis result
2. Design
   • Input: Requirements analysis result
   • Output: Design document
3. Implementation (TDD)
   • Input: Design document
   • Output: Code
4. Code Review
   • Input: Code
   • Output: Pull Request
5. Testing
   • Input: Requirements analysis result, design document, code
   • Output: E2E test code, QA checklist

3. Adding AI and Human Development Processes

I then added the detailed AI and human processes needed to go from Input to Output.

1) Requirements Analysis

2) Design

3) Implementation (TDD)

4) Code Review

5) Testing

The common pattern applied across all stages is a multi-layered verification structure where AI works, AI self-reviews, a separate AI agent reviews, and the human gives final confirmation.

① Input → ② AI Work → ③ AI Self-Review → ④ AI Agent Review → ⑤ User Confirmation → Output

4. Managing Input and Output

I deliberated on how to manage Input and Output.

Since Claude compresses context as conversations get longer, accuracy can degrade. So it was necessary to manage each stage’s artifacts as proper documents.

Initially, I considered managing them as Markdown files in the Git repository, but I chose to manage them with GitHub Issues instead. The reasons were:

• With file management, even small changes require a commit.
• Temporary fixes and bug patches leave files lingering in the repository even after the work is done.
• Issues can be closed when work is complete, making it easy to clearly distinguish between completed and in-progress work.

Conclusion

In this post, I covered the pitfalls of AI coding tools, the limitations of existing processes, and the hands-on experience of collaborating with AI that led to creating the SDD Plugin.

The key insight was that the goal isn’t “AI writes code fast” — it’s “designing a process so AI works in the right direction.”

Based on the development process analysis and design covered in this post, I built the actual SDD Plugin for Claude Code. In the next post, I’ll introduce the completed plugin’s full structure and usage.

Next post: SDD Plugin: Full Structure and Usage

Github Sponsor Buy me a coffee

Was my blog helpful? Please leave a comment at the bottom. it will be a great help to me!

App promotion

You can use the applications that are created by this blog writer Deku.
Deku created the applications with Flutter.

If you have interested, please try to download them for free.

word learning app for kids

BlaBoo

Korean TOPIK vocabulary app

TOPIK words

Japanese vocabulary app

Japanese words

Chinese HSK vocabulary app

HSK words