The “AI Magic” Hangovers
Coding with AI has become my new normal. I bounce between Codex, Claude Code, and Gemini CLI daily. At first, I fell into the trap of thinking, “Hey, the model is smart, it’ll figure it out.”
Spoiler alert: It won’t.
After restarting my side projects for the third time, I realized that starting without a strict baseline isn’t “agile”—it’s reckless. Without guardrails, AI is just a brilliant junior developer with infinite stamina and zero context.
The Wake-Up Call: “Context” vs. “Rules”
It started with tools like context7 (a doc-fetching MCP). Even with smarter models, relying on their training data for bleeding-edge libraries is a gamble. They hallucinate deprecated APIs with total confidence.
I needed a way to force the AI to check the manual. But I didn’t want to type “check the docs” in every prompt. I needed a rulebook.
I used to treat AGENTS.md as a project dump—a mix of “what is this app” and “todo list.” The result? The AI roamed free, making architectural decisions I didn’t ask for and skipping tests because “it looks simple.”
Just like you wouldn’t let a contractor build a house without blueprints and code compliance, you shouldn’t let AI build your app without SPECS and AGENTS.md.
The Pivot: AGENTS.md is for BEHAVIOR, not Context
I reorganized my brain (and my repo structure):
- SPECS: What we are building.
- ADR (Architecture Decision Records): Why we made those choices.
- AGENTS.md: How the AI must behave.
This separation is crucial. If AGENTS.md gets too big, it’s a smell. It means I’m mixing up “rules of engagement” with project details.
The Ironclad Laws
I’m still experimenting, but a few rules have already saved my sanity:
- RTFM (Read The Manual): If you’re touching an external library, you must verify the API with the official docs. No guessing.
- No Silent Trade-offs: If a change involves an architectural compromise, you don’t commit code. You write an ADR first.
- Ask Before PR: Don’t assume you’re done. Ask me if I want a PR draft.
TDD: Red, Green, Blue
I also revisited the “Plan Then Act” philosophy. Instead of just “coding,” I’m enforcing a TDD loop. The AI shouldn’t just write the function; it should define the failure case first. It changes the workflow from “generate text” to “solve the problem.”
The Document Management Reality
If I shove everything into AGENTS.md, the context window explodes, and the AI forgets the important stuff.
By splitting it up—Rules in AGENTS.md, Decisions in ADR, Reqs in SPECS—I can swap out the AI tool tomorrow, and my project structure remains intact.
The Conclusion
I haven’t “solved” AI coding efficiently yet, but I know one thing for sure: In the age of AI, defining the boundaries is more meaningful than writing the syntax.
So I built a minimal template. It’s the starting line for every new idea I have, so I don’t have to reinvent the wheel (or the rules) every weekend.
Efficiency is great, but only if you’re running in the right direction.
GITHUB: ai-project-template – Stars feed my dopamine. ⭐
Note: I’m a solo developer based in Korea. To share my journey with a wider audience, I used AI to help translate my thoughts into English. If any phrasing feels a bit “too AI” or unnatural, please bear with me.