{
  "title": "Vibe Coding's Next Paradigm: From 'Requirement First' to 'Contract First'",
  "url": "https://miaok.ong/en/posts/contract-first-vibe-coding-paradigm/",
  "date": "2026-06-20T00:00:00Z",
  "lastmod": "2026-06-20T00:00:00Z",
  "type": "posts",
  "kind": "page",
  "language": "en",
  "description": "\u003ch3\u003eThe 500-Line Curse\u003c/h3\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003eHave you experienced this? You open Cursor or Claude Code, describe your needs in three sentences, and AI generates hundreds of lines of code. The feature works—you're happy. You add more features, ask AI to modify things, then modify again…\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003eBy the fifth round of conversation, something is wrong. AI has started to \"forget\" the interface formats you previously agreed upon. A parameter name mysteriously changed. A working function has been refactored into three conflicting versions. You find yourself spending more and more time \u003cstrong\u003ereading code\u003c/strong\u003e—not reviewing, but debugging. Worse still, these aren't logic errors: they are \u003cstrong\u003einconsistencies introduced by AI across different conversation turns\u003c/strong\u003e.\u003c/p\u003e",
  "keywords": null,
  "tags": ["Vibe Coding","AI Development","Software Engineering","Contract First","OpenSpec","Claude Code","Codex"],
  "categories": ["Engineering"],
  "author": "Mark (Miao) Kong",
  "image": "https://miaok.ong/images/avatar.jpg",
  "content": "\u003ch3\u003eThe 500-Line Curse\u003c/h3\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003eHave you experienced this? You open Cursor or Claude Code, describe your needs in three sentences, and AI generates hundreds of lines of code. The feature works—you're happy. You add more features, ask AI to modify things, then modify again…\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003eBy the fifth round of conversation, something is wrong. AI has started to \"forget\" the interface formats you previously agreed upon. A parameter name mysteriously changed. A working function has been refactored into three conflicting versions. You find yourself spending more and more time \u003cstrong\u003ereading code\u003c/strong\u003e—not reviewing, but debugging. Worse still, these aren't logic errors: they are \u003cstrong\u003einconsistencies introduced by AI across different conversation turns\u003c/strong\u003e.\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003eThis is the \"500-line curse\": vibe coding's charm faces a \u003cstrong\u003ecliff-like decline\u003c/strong\u003e when confronted with the \u003cstrong\u003elinear growth\u003c/strong\u003e of project complexity.\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003ch3\u003eA Security Engineer's Epiphany\u003c/h3\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003e@Pluvio9yte's recent deep dive captures this insight perfectly. Originally a security engineer, he went all-in on full-stack development—using AI coding tools intensively every day.\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003eHis core insight is counterintuitive: \u003cstrong\u003eThe best practice for Vibe Coding is neither \"Requirement First\" nor \"Code First\"—it's \"Contract First.\"\u003c/strong\u003e\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003eWhy? The problem with \"Requirement First\" is that after you write the requirements document, AI won't naturally adhere to it. It re-interprets the requirements in every conversation turn, and the interpretation may differ slightly each time. The problem with \"Code First\" is more direct: when the code itself is the sole source of truth, each of AI's modifications can destroy global consistency in pursuit of local optimization.\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003eHe built a methodology around OpenSpec:\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003cblockquote\u003e1. \u003cstrong\u003eDefine interface contracts first\u003c/strong\u003e—inputs, outputs, side effects, invariants—must be established before any line of code\u003cbr\u003e2. \u003cstrong\u003eThe contract becomes the single source of truth for both human and AI\u003c/strong\u003e—all conversation context is anchored to the contract\u003cbr\u003e3. \u003cstrong\u003eSpec drift is caught at development time\u003c/strong\u003e—not discovered in production by your users\u003c/blockquote\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003eThe greatest value of this approach: it externalizes \"drift-prone context\" into a stable reference point. Humans fully understand it; AI has explicit constraints around it.\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003ch3\u003eWhat's Happening on the Tool Side\u003c/h3\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003eIf you've been following updates from major AI coding platforms over the past month, you'll notice a common trend.\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003e\u003cstrong\u003eClaude Code Artifacts: Solving the collaboration black hole.\u003c/strong\u003e Previously, AI programming output was \"only visible to the operator.\" Claude Code has just shipped Artifacts—turning AI programming outputs (debug data, architecture diagrams, PR walkthrough results) into shareable interactive web pages. But the key dependency: this feature only works when there's something structured to share. If your AI code is a tangled hash, Artifacts can't save you.\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003e\u003cstrong\u003eOpenAI Codex Record \u0026 Replay.\u003c/strong\u003e Launched June 18, this feature takes a different path: you perform a task once, AI watches, then automatically compiles that workflow into a reusable Skill. This is essentially a \u003cstrong\u003ebehavioral contract\u003c/strong\u003e—you're demonstrating not \"how to write code\" but \"how things should be done.\"\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003e\u003cstrong\u003eLoop Engineering.\u003c/strong\u003e Proposes self-sustaining AI agents that write, test, and modify code through cyclical development. But the prerequisite for this mechanism to function isn't advanced prompt engineering—it's \u003cstrong\u003ehaving stable interface contracts as anchors\u003c/strong\u003e. An autonomous agent without a contract is like a drone without GPS.\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003ch3\u003eWhy Now?\u003c/h3\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003eThree years ago, developers debated whether writing specs was even useful. Today, the question has completely inverted. In an AI-first workflow, specs are no longer \"documentation written for humans\"—they've become a \u003cstrong\u003eruntime artifact\u003c/strong\u003e that both humans and AI continuously reference, compare against, and base decisions on.\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003cblockquote\u003e\u003cstrong\u003eThe spec itself is the product. Code is merely the rendered artifact.\u003c/strong\u003e\u003c/blockquote\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003eThree forces drive this paradigm inversion: \u003cstrong\u003eConversation context unreliability\u003c/strong\u003e—AI's \"memory decay\" in long conversations is a structural flaw, and contracts are the most effective external memory against it. \u003cstrong\u003eThe inevitable need for multi-agent collaboration\u003c/strong\u003e—when multiple AI agents work together, without interface contracts their conversations will be more catastrophic than human ones. \u003cstrong\u003eRising automation levels\u003c/strong\u003e—tools like Codex Record \u0026 Replay signal AI's shift from \"passively responding to instructions\" to \"actively executing workflows\"—without contract-defined boundaries, automation becomes gambling.\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003ch3\u003ePractical Takeaways\u003c/h3\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003eIf you're using AI for serious projects (not toy demos), here are four starting points:\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003cblockquote\u003e• \u003cstrong\u003eInterface before implementation\u003c/strong\u003e—even just a comment block defining input/output formats\u003cbr\u003e• \u003cstrong\u003eVersion contracts alongside code\u003c/strong\u003e—keep them in the same repo, with corresponding commits for contract changes\u003cbr\u003e• \u003cstrong\u003eTreat spec drift as a bug\u003c/strong\u003e—don't let \"close enough\" become a habit\u003cbr\u003e• \u003cstrong\u003eAI generates scaffolding; humans own contract design\u003c/strong\u003e—architectural decisions (especially interface design) remain the least replaceable human role\u003c/blockquote\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp\u003eDevelopers who grasp this relationship can realistically achieve 5x productivity. Those who don't will spend that 5x debugging.\u003c/p\u003e\u003cp\u003e\n\u003c/p\u003e\u003cp style=\"color: #999; font-size: 0.85rem; margin-top: 2rem;\"\u003e2026.06.20 · Based on Pluvio9yte's Contract First methodology, Claude Code Artifacts, OpenAI Codex Record \u0026 Replay, and Loop Engineering observations\u003c/p\u003e\n",
  "wordCount": 758,
  "readingTime": 4,
  "tableOfContents": "\u003cnav id=\"TableOfContents\"\u003e\u003c/nav\u003e",
  "isDraft": false
}