스펙 극대화: AI 코딩 정신착란을 극복하는 법

Skip to main content Acai.sh home page Docs API Reference Blog Search... Search... Navigation Specsmaxxing App (login) GitHub Blog Blog Blog Home On this page Does this look familiar? Peak Slop Specifying the plane while we fly it Dreaming in markdown Acceptance Criteria for AI (ACAI) Acai.sh - an open-source toolkit How it works Step 1 - Specify Step 2 - Ship Step 3 - Review Step 4 - Iterate / repeat Future Gazing Thought Experiment -> From Specsmaxxing to Testmaxxing -> From Testmaxxing to reactive software factories Comparison to other spec-driven development tools GitHub SpecKit OpenSpec Kiro Traycer.ai Reasons you might not like acai.sh Hate it? Documentation Index Fetch the complete documentation index at: https://acai.sh/llms.txt Use this file to discover all available pages before exploring further. ​ Does this look familiar? Wow. Claude. Mind-blowing. The whole feature works great. But I forgot to mention one very important edge case. You’re absolutely right! Let me fix that. Ah, and I just noticed. You used offset pagination for the table UI. Obviously cursor pagination is a better fit here? You’re absolutely right! Let me fix that. Also, is that an N+1 query? Fetching for every row in the table? Why not do a single round-trip? You’re absolutely right! Let me fix that. This is why I still have a job, right? … ​ Peak Slop I’ve watched this scene play out many times, but the frequency is decreasing. Both my tools, and my methods for using them, continue to improve. I think Peak Slop has already come and gone. We are entering the post-slop era. My software is more robust, better tested, better integrated, and more observable than ever before. And my velocity keeps increasing! Some days it feels like the sky is the limit. Other days, I am painfully reminded, the sky is not the limit. The context window is the limit. And what happens when I fill the context window? Or kill a session? Switch machines? Hand off the project to someone else? We already know what happens. The agent goes off the rails, or requirements get lost, and critically important detail gets squashed. So we adapt and mitigate. We document. We list requirements. Yes, millions of us are coming to the same realization: we should put more requirements in writing. We should update those requirements when they change. Look! I wrote a spec! Am I doing spec-driven development? Perhaps, but it is nothing new. Our mentors tried to teach us these habits decades ago. ​ Specifying the plane while we fly it What’s your favorite flavor of spec? A README.md and AGENTS.md is a good start. Don’t forget a testing-guide.md . Maybe an architecture.md , a PRD.md , and a design doc too. Have you considered md.md (to teach your agents how to write .md )? The more .md the better, right? Unironically, yes. Docs and unstructured specs can get you very, very far. Much farther than prompts alone. If you aren’t writing any docs yet, you should just stop reading this and start there. And remember, slop in, slop out. Nothing beats an organic, pasture-raised, hand-written spec. Spec-writing is where the act of software engineering really happens. So a few weeks ago, I started asking myself, how far can I take this? How far should I take this? ​ Dreaming in markdown As the story goes, I fell into an AI psychosis, I became a “spec maxxi”, and I spent hours and hours writing the most beautiful PRDs and TRDs you’ve ever seen. I drafted templates and skills and roles, thinking that maybe my agents can write specs too! I assembled an army, working together like a mini dark factory, to turn my specs into reality. My tasks grew more ambitious, and at one point I broke the vibe-coding sound barrier: an agent that ran for 1.5 hours unsupervised! Exciting. But what did that army ship for me? Well, it wasn’t slop, in fact it worked , which is more than I can say about the garbage that other companies force me to use every day. But it was still a bit sloppy. I’m far from a perfectionist and I love cutting corners more than most, but this somehow wasn’t good enough. One hallmark symptom of AI psychosis is using AI to build AI harnesses for building products , rather than just using AI to build the damn product. I embraced my illness, threw out the branch, scrapped all my markdown, and started all over again. ​ Acceptance Criteria for AI (ACAI) A few days later, I noticed an ambitious little sub-agent doing something unexpected. # Requirements AUTH-1: Accepts `Authorization: Bearer <token>` header AUTH-2: Tokens are user-scoped, providing access to any of the user&#x27;s resources AUTH-3: Rejects with 401 Unauthorized // AUTH-1 const authHeader = req . headers [ "authorization" ]; // AUTH-2 const isAuthorized = verifyBearerToken ( authHeader ); // AUTH-3 if ( ! isValid ) return res . status ( 401 ). json ({ error: "Unauthorized" }); The little guy just went and numbered my requirements and then referenced them all over my codebase. Why? I did not ask for this! I was disgusted. This is a tight coupling of code to spec, and spec to code, which is bad right? You really expect me to refactor all my code every time I change my spec? Oh. I suppose that’s a good thing? Interesting. I wonder… Perhaps these tags can help me navigate these massive PRs? Perhaps they can point me to where, exactly, a requirement is satisfied or tested! Perhaps I can annotate them with notes and states (todo, assigned, completed)! Perhaps I can start tracking acceptance coverage instead of test coverage! I leaned in. I named these tags ACIDs (Acceptance Criteria IDs). But a few questions remained. Can my ACIDs number and label themselves? Is it cumbersome to keep them aligned? How do I share specs and progress across sandboxes, branches, features and implementations? ​ Acai.sh - an open-source toolkit I built Acai.sh to solve some of these newly invented problems. And I’m very excited about the results. A simple and flexible template for feature specs, called feature.yaml . Feature.yaml makes it possible to reference each requirement by ACID. Tiny CLI to power your CI and your agent (available on npm or via github release). Webapp that serves a dashboard, and a JSON REST API (Elixir, Phoenix, Postgres). I will keep the hosted version free for a while, or maybe forever depending on how popular or expensive this gets. The source code is on GitHub under an Apache 2.0 license. ​ How it works ​ Step 1 - Specify Start by writing a spec for a feature. Be ambitious— something that adds real value. Don’t put nitpicky UI and nail polish stuff in your specs. Keep the requirements concrete, testable, and focused on what really matters (functional behavior + critical constraints). Rather than markdown, use acai’s feature.yaml format instead. A spec in Acai is just a numbered list of requirements. feature.yaml feature : name : imaginary-api-endpoint product : api description : This is an example feature spec for an imaginary REST API endpoint, using the feature.yaml format components : AUTH : name : Authn and Authz requirements : 1 : Accepts Authorization header with `Bearer <token>` 1-1 : Token must be non-expired, non-revoked 2 : Respects the scopes configured for the owner 2-note : See `access-tokens.SCOPES.1` for complete list of supported scopes constraints : ENG : description : Constraints are for cross-cutting or under-the-hood requirements. Here are some example engineering constraints; requirements : 1 : All actions are idempotent 2 : All HTTP 2xx JSON responses wrap their payload in a root `data` key Of course you could also have LLMs assist you with spec writing, but I enjoy the process of writing them myself, because I like to maintain some illusion of self-worth as a software developer. ​ Step 2 - Ship Copy and paste the prompt below. Copied Copy prompt Note: In addition to the npm package, there are Linux and MacOS releases for the CLI available on GitHub . If all goes well, your agent will embrace ACIDs, referencing them in code and tests, so you can m