Notes: The Development Workflow (SDD)

I learned something new today

Introduction

Recently I built a rhythm game I’d been imagining for a while, using AI. I can’t help but marvel: in an era where AI is everywhere, when it comes to creating things we may need not just attention but creativity. Anyone with an idea can now become a creator or a developer.

The only problem was that it thought for two hours before writing anything, and looking at the reasoning process there was a lot of redundancy. To build this game I used GLM 5.3 Flash for coding and DeepSeek 4.1 Flash to clean up afterwards.

Even the Flash models are like this; using the larger models would waste a lot of tokens. So I had to reflect on whether something was going wrong somewhere.

Yesterday I sent my demo to the group chat and chatted with some friends about it. Let me note down what came up in that conversation.

Right now I’m having openspec write my requirements, so I’ll write down what I’ve learned along the way.

SDD

What Is SDD

Spec-Driven Development (SDD) is a software development method driven by a “specification” as its core.

It emphasizes writing a clear, complete, and unambiguous specification before writing any code, then treating that specification as the single source of truth to guide the subsequent technical design, task breakdown, and code implementation.

This approach is especially well suited to being combined with AI-assisted coding tools, and it effectively avoids the uncertainty and rework that come with “vibe coding.”

That passage above was told to me by AI — in other words, write a few spec documents to stop the AI from going off the rails.

I feel this counts as prompt engineering too, since in essence it’s the same as a CLAUDE.md constraint file. The only difference is that the AI helps me write the prompts, and it writes several files for different stages of development. All I need to do is give it a rough instruction.

Considering I probably couldn’t write anything decent myself, on a friend’s recommendation I downloaded openspec. It’s a lightweight spec generator, and it can call my tools — from just a description, it generates a detailed spec for me.

The Four Stages

SDD is divided into four stages: Specify — Plan — Tasks — Implement.

Specify

What are you trying to do?

That’s what this stage is about.

What do I want to build? I want to make a game — what features should it have, what’s the core idea?

Here’s an example written by AI:

# Proposal: Build a Basic Rhythm Game

## Background
We want to develop a lightweight web-based music game in which the player interacts with the music's rhythm using the keyboard.

## Goals
- Build a rhythm game with falling notes
- Support keyboard input (four keys: D, F, J, K)
- Judge and score based on hit accuracy

## Scope
**Included:**
- One built-in practice track
- Basic note-falling animation
- Judgment system (Perfect / Good / Miss)
- Score and combo display

**Not included:**
- Song selection screen
- Online leaderboard
- Custom chart import

As you can see, it laid out…

Each stage produces a markdown document that makes the constraints concrete. For example, this stage generates a proposal.md document.

Plan

In this stage, what needs to be pinned down is the technical approach — for example, which tech stack to base it on and what architecture to adopt.

# Technical Design: Basic Rhythm Game

## Architecture Overview
- Use HTML5 Canvas to render the game screen
- Use the Web Audio API to load and play music
- Use requestAnimationFrame to drive the game's main loop

## Tech Stack
- Language: JavaScript (ES6+)
- Rendering: Canvas 2D
- Audio: Web Audio API
- Testing: Playwright (E2E)

## Key Design Decisions
- **Note lanes**: 4 vertical lanes, corresponding to the D, F, J, K keys
- **Judgment windows**: Perfect ±50ms, Good ±100ms, anything beyond 100ms is a Miss
- **Time sync**: use AudioContext.currentTime as the single time source

The resulting artifact might be called plan.md or design.md.

Tasks

Break the project down into small tasks. Each task should be small enough to be developed and tested independently.

The deliverable is an ordered task list, tasks.md, which guides the subsequent coding work.

# Implementation Tasks

- [ ] 1. Set up the Canvas and basic rendering of the 4 lanes
- [ ] 2. Implement music loading and playback with the Web Audio API
- [ ] 3. Implement the note data structure and falling logic
- [ ] 4. Implement keyboard input listening and the judgment logic
- [ ] 5. Implement the UI display for score, combo, and judgment results
- [ ] 6. Write Playwright E2E tests covering the Perfect / Good / Miss scenarios

Implementation

Write the code according to the spec, the plan, and the task list. Each time a task is completed, it must be verified against the original spec to make sure the implementation fully matches expectations. The deliverable is working code that has been tested and meets the original requirements.

This stage produces no new artifact; instead, you check off the previously provided tasks.md one item at a time.

Software Development Notes

Compact

Given that AI has a context window, compact is genuinely a useful feature. Without compression, an overly long context slows down the AI’s thinking, wastes memory, and leads to context pollution. In practice, I ran into cases where, late in the reasoning, the AI was thinking through things it had already thought about — that’s context pollution.

My previous approach had always been to stop at each stage and have the AI summarize its reasoning anew — but after searching around, I learned that in Claude Code you can just click that circle to summarize.

Visual References

My project is based on an existing project, so I could pick a model that can recognize images. Either way it’s reinventing the wheel, so this saves some tokens.

Let the AI Ask Me

A hard-won lesson: don’t turn on Auto mode just to save effort. My prompt mentioned using the judgment windows of an already-released game as a reference, and for some reason the AI agonized over the judgment window for a very, very long time. Because I had Auto mode on, it was quite hard for me to interrupt it midway and explain.

AI can be very powerful, but if you ask it about a field that’s too detailed or too specific, it may well fail to catch on or understand.

So from now on, if I use AI for tasks again, I must make sure it remembers to ask me about the parts it doesn’t understand.

skill

To be expanded.