DEV Community

Cover image for I Built a Framework That Makes AI Ask Questions Before Writing Any Code
Muhammad Hamid Raza
Muhammad Hamid Raza

Posted on

I Built a Framework That Makes AI Ask Questions Before Writing Any Code

#opensource #ai #productivity #python

I Built a Framework That Makes AI Ask Questions Before Writing Any Code

The Moment I Got Frustrated

I asked AI to build me an authentication system.

90 seconds later — 40 files generated.

3 months later — I had no idea how any of it worked.

I couldn't debug it. I couldn't extend it.
I was completely dependent on AI forever.

Sound familiar?

The Real Problem

AI coding tools are optimized for one thing: speed.

You say "add authentication"
AI immediately starts writing code.

But that's NOT how senior developers work.

A senior developer never opens their editor
the moment they hear a feature request.

They:

  1. Ask questions — What exactly do you need?
  2. Consider options — What are the trade-offs?
  3. Surface edge cases — What could go wrong?
  4. Plan architecture — How does it fit the system?
  5. THEN write code — Only after all of the above

AI skips steps 1 through 4.

My Solution: Spec-Kit-CoLearn

I built Spec-Kit-CoLearn — a free open-source
framework that transforms any AI coding tool into
your senior architect co-partner first,
coding worker second.

Two Modes — One Tool

MODE 1: Senior Architect (Default)

When you start, AI enters Senior Architect Mode:

✅ Asks 3-6 discovery questions
✅ Presents 2-3 design options with trade-offs
✅ Teaches you concepts you don't know
✅ Surfaces at least 3 edge cases
✅ Defines measurable success criteria
❌ Does NOT write code in this mode

MODE 2: Coding Worker

Only activates AFTER you say "tasks approved":

✅ Executes tasks one by one in order
✅ Writes code matching spec exactly
✅ Runs tests after each task
✅ Stops and asks if scope changes

Why This Order Matters 

WRONG: Code first → Realize it's wrong → Rewrite → Waste days
RIGHT: Think first → Spec → Plan → Tasks → Code once, code right
Enter fullscreen mode Exit fullscreen mode

Teaching Mode — The Feature I'm Most Proud Of

This is what makes Spec-Kit-CoLearn unique.

You say: "I want users to log in"

AI doesn't write code. It teaches:

You mentioned authentication. Let me explain
your options before we design anything.

JWT is like a concert wristband.
You show your ID once at entry.
They give you a wristband.
You show the wristband everywhere inside.
No ID check again on every request.

Sessions store user data on the server.
More control. Instant logout possible.
But harder to scale.

OAuth lets users log in via Google or GitHub.
Less friction. You don't manage passwords.
But you depend on third-party.

Which fits your use case?

Now you've learned AND made an informed decision.

The Clarity Gate

Before ANY spec is written, AI must pass
a hard check — all 6 must pass:

✅ WHO is clear        — Who uses this feature?
✅ WHAT is clear       — What exactly does it do?
✅ SCOPE is defined    — What's IN and what's OUT?
✅ EDGE CASES covered  — At least 3 discussed
✅ SUCCESS measurable  — At least 2 measurable criteria
✅ YOU approved        — You explicitly said "approved"
Enter fullscreen mode Exit fullscreen mode

If ANY item fails → more questions.
No gate passed = no spec written.
This alone saves weeks of rewrites.

The Learning Log

After every feature, AI generates a Learning Log:

## What You Learned:

| Term         | Definition                              |
|--------------|-----------------------------------------|
| JWT          | Stateless token for API authentication  |
| OAuth 2.0    | Third-party login protocol              |
| Sessions     | Server-side user state storage          |
| Bcrypt       | Password hashing with built-in salt     |
| httpOnly     | Cookie JavaScript cannot read (XSS safe)|
Enter fullscreen mode Exit fullscreen mode

You don't just ship code — you ship understanding.

Full Workflow 

1. pip install spec-kit-colearn
2. spec-kit-colearn init my-project
3. Open any AI coding tool
4. Paste activation prompt
5. Tell AI what you want (vague is fine!)
6. AI asks questions → teaches concepts
7. You choose from 3 options
8. Say "approved"
9. AI creates spec → plan → tasks
10. Say "tasks approved"
11. AI switches to Mode 2 → codes task by task
12. Learning log generated ✅
Enter fullscreen mode Exit fullscreen mode

Install 

# Python
pip install spec-kit-colearn

# JavaScript / Node
npm install -g @muhammad-hamid-raza/spec-kit-colearn

# Initialize project
spec-kit-colearn init my-project
Enter fullscreen mode Exit fullscreen mode

Works With Every AI Tool

AI Tool Support
Claude Code ✅
Codex CLI ✅
Gemini CLI ✅
GitHub Copilot ✅
Cursor ✅
Windsurf ✅
Qwen CLI ✅

Who Is This For?

Non-developers — Have ideas but can't code?
AI guides you step by step and teaches along the way.

Junior developers — Learn architecture, not just syntax.
Understand WHY before HOW.

Senior developers — Structured workflow, clear docs,
no more "just write it" chaos.

Links

⭐ GitHub: https://github.com/MuhammadHamidRaza/spec-kit-colearn
📦 PyPI: https://pypi.org/project/spec-kit-colearn
📦 npm: https://npmjs.com/package/@muhammad-hamid-raza/spec-kit-colearn

MIT license. Free forever. Contributions welcome.

Final Thought

AI should be your thinking partner.
Not just your code generator.

Build with clarity.
Ship with confidence.
Learn along the way.

Built with 🔥 from Pakistan 🇵🇰
Feedback welcome in the comments!

Top comments (0)