Vintage punch cards, modern AI—programming education resurrected. #kiro #kirodotdev #ai

tangit.ozukum — Fri, 05 Dec 2025 06:25:17 +0000

Bridging the Decades: Revitalizing Punch Card Data with Modern AI

tangit.ozukum ・ Dec 5

Bridging the Decades: Revitalizing Punch Card Data with Modern AI

tangit.ozukum — Fri, 05 Dec 2025 04:52:10 +0000

Remember punch cards? Those paper cards with holes that programmed computers in the 1960s? I brought them back as an AI-powered learning tool for kids.

This is how I built PunchCard.AI using Kiro - from requirements to deployment.

Why Punch Cards?

Programming used to be physical. You'd arrange cards in sequence, each card doing one thing. It was tactile, visual, and made you think step-by-step.

Modern programming is powerful but intimidating. Kids see walls of text and syntax errors. What if we could bring back that tactile feeling with modern AI?

That's PunchCard.AI: drag visual cards to build programs, AI compiles them to real code, and you see actual results.

What PunchCard.AI Does

Pick your learning level (elementary to university). Choose a subject you love - or create your own. The AI generates a programming challenge just for you.

Then you build your solution by dragging cards:

"Get User Input" card
"Sort Numbers" card
"Display Result" card

Click run. The AI compiles your cards to Python code and executes it safely. You see real output, real errors, real learning.

The AI gives you feedback that's encouraging and educational. No harsh "wrong answer" messages - just helpful guidance.

Building with Spec-Driven Development

I didn't jump straight into coding. I used Kiro's spec-driven approach:

Planning

Wrote 10 user stories with acceptance criteria
Used EARS syntax for clear requirements
Mapped out the architecture
Designed all service interfaces
Created 11 correctness properties for testing
Broke design into 19 actionable tasks

Implementation

Executed tasks one by one
Tests caught bugs immediately
No major refactoring needed
19 of 19 tasks completed

The upfront planning felt slow at first. But it saved me from the usual chaos of "build first, fix later."

Steering Docs: Teaching Kiro to Be a Teacher!

The AI needed to generate educational content - challenges, feedback, card libraries. But AI can be inconsistent.

I created three steering documents:

ai-behavior.md: How to talk to students

Age-appropriate language
Encouraging tone (never discouraging)
Specific, actionable feedback
Educational explanations

card-patterns.md: How to design cards

Six categories (INPUT, PROCESS, OUTPUT, etc.)
Complexity ratings (1-5 scale)
Subject-specific theming
Consistent naming conventions

subject-generation.md: How to create diverse subjects

No keyword overlap between subjects
Balance across categories
Age-appropriate examples
Educational value validation

These docs transformed AI quality:

Feedback consistency: 60% → 95%
Challenge quality: 70% → 90%
Subject diversity: 75% → 100%
Inappropriate content: 5% → 0%

Kiro automatically includes these guidelines when generating content. The AI stays on-brand without me micromanaging every prompt.

Agent Hooks: My Silent QA Team

I set up two hooks that run automatically:

test-on-save.json: Runs all tests when I save a file

Catches regressions instantly
No manual test running
Saved a lot of time!

lint-on-save.json: Fixes code style automatically

Consistent formatting
No style debates

These hooks caught 15+ bugs during development. Issues that would've made it to production were fixed immediately.

The hooks also validate requirements. When a test fails, it shows which acceptance criteria broke. Continuous validation throughout development.

MCP: The Secret Sauce

The core feature is real code execution. Students need to see actual Python output, not simulations.

Running arbitrary code in the browser? Dangerous. Building custom sandboxing? Complex.

Enter MCP (Model Context Protocol).

I configured the MCP code-executor server:

{
  "mcpServers": {
    "code-executor": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-code-executor"],
      "env": {
        "EXECUTION_TIMEOUT": "5000",
        "MAX_MEMORY": "128MB"
      }
    }
  }
}

That's it. Now I have:

Safe sandboxed execution
Real stdout/stderr output
Timeout protection (5 seconds max)
Memory limits (128MB)
Multi-language support

Without MCP, I'd need to build custom infrastructure, worry about security, and maintain execution environments. With MCP, it's one config file.

Students see real code behavior. Real error messages. Real learning.

The AI Pipeline

Every feature uses AI differently:

Subject Generation: Gemini creates 6 diverse learning themes

Robotics, art, science, games, data, web
Or students create custom subjects
Steering docs ensure diversity and appropriateness

Challenge Generation: AI creates unique programming problems

Matched to subject and skill level
Clear objectives and expected output
Hints for when students get stuck

Card Library: Subject-specific programming cards

"Move Robot Forward" for robotics
"Play Musical Note" for music
"Analyze Data" for data science

Code Compilation: Cards → Python code

AI translates card sequence to executable code
Adds comments explaining logic
Handles edge cases gracefully

Feedback Analysis: AI reviews student solutions

References specific cards used
Explains what worked and what didn't
Suggests improvements
Always encouraging, never harsh

The entire learning experience is dynamic. No two students get the same challenges.

Property-Based Testing

I didn't just write unit tests. I wrote 11 correctness properties - rules that should always be true.

Examples:

Challenge Uniqueness: No two challenges should be identical in a session
Card Library Completeness: Library must contain cards that can solve the challenge
Feedback Relevance: Feedback must reference the student's actual cards
Subject Diversity: No keyword overlap between subjects
Progressive Difficulty: Difficulty adapts based on performance
Error Recovery: System maintains state without crashing
...and 5 more properties

I used fast-check to test these across 100 random inputs each (800 total iterations). Found edge cases I never would've thought of.

Final test coverage: 91.6%

Challenges I Overcame

AI Consistency: Free-tier Gemini API can be slow (10-15 seconds per generation). Solution: Added caching and clear loading states with helpful messages.

Property Test Flakiness: AI-generated content varies slightly. Solution: Adjusted tests to allow minor variations while maintaining correctness.

State Management: Complex state across 6 services. Solution: Clear interfaces and progress tracking kept everything synchronized.

The Tech Stack

React 18 + TypeScript (strict mode)
Vite for blazing fast builds
Tailwind CSS for styling
Google Gemini for AI generation
MCP for code execution
Vitest + fast-check for testing
Local storage for progress tracking

Everything chosen for simplicity and speed.

What I Learned About Kiro

Spec-driven development works: way faster overall, higher quality.

Steering docs are powerful: Small guidelines create massive consistency. The AI stays on-brand without constant supervision.

Agent hooks are underrated: Automated testing and linting saved 3-5 hours per day. Bugs caught before they spread.

MCP is a game-changer: Complex features (code execution) become simple. One config file replaces weeks of custom development.

Property-based testing finds bugs: Testing universal properties catches edge cases that example-based tests miss.

The Results

PunchCard.AI is live with:

AI-generated subjects and challenges
Drag-and-drop card programming
Real code execution via MCP
Intelligent, encouraging feedback
Progress tracking and metrics
Four educational levels
Enhanced Library Info panel with API usage stats and quick tips
Helpful context about AI generation times
Improved user guidance throughout the interface

Completely free and open source. No limits, no paywalls.
PS - "Wait times or API rate limits may occur because we are using free AI API!:)"

Try It Yourself

PunchCard.AI is live at https://punchcard-live.vercel.app/

Pick a level, choose a subject, solve a challenge. See how punch card programming feels in 2025.

Building this taught me that with the right approach (specs + steering + hooks + MCP), you can build complex educational tools without chaos.

The 1960s had punch cards. 2025 has AI-powered punch cards. The future of learning is surprisingly retro.

Built with: Kiro IDE, React, TypeScript, Gemini AI, MCP
Category: Resurrection (Kiroween 2025)
Time: 16 days from idea to deployment
Lines of Code: ~3,500 (plus 2,000 lines of tests)
Test Coverage: 91.6%
Bugs in Production: 0

DEV Community: tangit.ozukum

Vintage punch cards, modern AI—programming education resurrected. #kiro #kirodotdev #ai

Bridging the Decades: Revitalizing Punch Card Data with Modern AI

tangit.ozukum ・ Dec 5

Bridging the Decades: Revitalizing Punch Card Data with Modern AI

Why Punch Cards?

What PunchCard.AI Does

Building with Spec-Driven Development

Steering Docs: Teaching Kiro to Be a Teacher!

Agent Hooks: My Silent QA Team

MCP: The Secret Sauce

The AI Pipeline

Property-Based Testing

Challenges I Overcame

The Tech Stack

What I Learned About Kiro

The Results

Try It Yourself