spec-driven-development

In the AI Era, Development Ability Is Determined by Verification Skills: Strategies for Rapid Validation and Local Environment Setup Learned While Developing the Flava API Gateway (opens in new tab)

AI coding agents iterate quickly, but their output can be inconsistent, make incorrect design decisions, or generate code that does not compile. Because CI runs, environment provisioning, and human review are slower, the article argues that reliable agent-assisted development requires three practices: spec-driven development, automated verification, and fast, self-contained local environments. ## Flava API Gateway and the Development Challenge - Flava API Gateway is part of LY Corporation’s private Flava cloud. - It provides a multi-tenant RESTful control-plane API for creating, deploying, and monitoring web APIs. - Kong serves as the data plane. - The team adopted agent-based coding while building the product and focused on preserving software reliability without sacrificing AI-driven speed. ## Spec-Driven Development The team found that agents became more unpredictable when implementation began before the design was settled. They use explicit specifications to reduce ambiguity and constrain implementation decisions. - OpenAPI is written before code to define the control-plane API. - Features are divided into smaller units and implemented with OpenSpec. - Specifications serve both as implementation guidance and as a standard for detecting deviations. ### Managing OpenAPI with Nickel - Raw OpenAPI YAML is repetitive and difficult to maintain manually. - Nickel is used to describe API resources declaratively and generate complete CRUD specifications. - A resource definition can specify: - Description and parent resource - Whether updates are allowed - Automatic timestamps - Property schemas - Required fields - Sorting and filtering behavior - The generator produces consistent endpoints such as `listPaths`, `createPath`, `getPath`, and `deletePath`. - Generated endpoints include pagination, sorting, filtering, ETags for optimistic locking, and standardized error responses. ### OpenSpec Workflow OpenSpec structures each change into four artifacts: - **Proposal:** Why the change is needed and what will change - **Design:** Technical decisions and trade-offs - **Delta specifications:** Behavioral requirements written as Given-When-Then scenarios - **Task list:** A step-by-step implementation checklist The developer and agent review the feature together, the agent creates these artifacts, and then implements the checklist incrementally. Once complete, the delta specification is archived into the main specification library, creating a versioned, evolving record of the system’s behavior. ## Automated Verification The team initially tried adding lists of pitfalls to prompts, but found this ineffective and potentially harmful. Instead, they made tests and tools reveal errors progressively so the agent could diagnose and correct them. - Automated tests, linters, and formatters provide precise feedback. - Failed tests identify what went wrong, allowing the agent to fix one issue before moving to the next. - Project-specific skills bundle these checks together. - `AGENTS.md` tells the agent when to load the relevant skills, avoiding unnecessary instructions on every turn. - Testing and linting are treated as essential infrastructure rather than optional activities, since agents frequently make errors during implementation. ## Fast, Independent Local Environments Relying on CI and shared test environments is too slow for agent-driven iteration. Long waits can disrupt the agent’s context and make repeated experimentation impractical. - A complete local environment provides immediate feedback. - Local dependencies make logs and state easier to inspect. - Developers avoid sending every failed attempt through a remote pipeline. - The local test suite contains 2,754 tests across three layers: - **Unit tests:** Isolated business logic - **Integration tests:** Real PostgreSQL, database constraints, triggers, soft-delete cascades, transactions, in-process HTTP, and OpenAPI compliance - **End-to-end tests:** Athenz authentication, Kong, API keys, and multi-tenant isolation - The full suite completes in roughly 15 seconds on a developer machine. - Parallel execution and strong test isolation are critical to achieving this speed. ## Practical Recommendation Agent-assisted development works best when agents are given clear behavioral contracts, immediate automated feedback, and a fast local loop. Teams should invest in specifications, comprehensive tests and linting, and realistic local dependencies so agents can correct mistakes continuously without waiting for CI.

What If AI Agents Debated Each Other? Redesigning the Development Process Through Multi-Agent Collaboration (opens in new tab)

AI coding’s main bottleneck is no longer code generation but the human coordination surrounding it: clarifying intent, validating assumptions, testing implementations, and preparing trustworthy pull requests. LY Corporation proposes an AI-native pipeline in which specialized “proposer” and “challenger” agents debate across three stages—specification, build, and delivery—while an orchestrator decides whether to revise, escalate, or proceed. The goal is for AI to substantiate its own work before human engineers review and approve it. ## Human Coordination as the Bottleneck - Traditional AI-assisted development speeds up individual tasks but leaves handoffs between requirements, implementation, verification, and review to humans. - Engineers still need to: - Write or refine specifications - Review AI-generated drafts - Transfer failed tests and feedback between steps - Inspect diffs - Prepare PR descriptions - Decide whether the result is trustworthy - The proposed solution is not to remove human judgment, but to automate repetitive coordination while preserving human ownership and final approval. ## Proposer–Challenger Collaboration - AI responsibilities are divided between two opposing groups: - **Proposers** develop specifications, implementations, and delivery materials. - **Challengers** validate them from specialized perspectives. - The separation prevents one general-purpose assistant from combining design, implementation, testing, and review into a single unchallenged response. - Specialized roles may include: - `requirements-synthesizer` - `security-analyst` - `test-coverage-reviewer` - `technical-writer` - `evidence-verifier` - An **orchestrator** mediates disagreements, redirects discussions, resolves deadlocks, and determines whether to revise, escalate, or advance. ## The Spec–Build–Deliver Pipeline ### Specification - The specification acts as a contract for all later stages. - It records: - Goals and constraints - Interpreted requirements - Explicit assumptions - Open questions - Proposed approach - Definition of done - Agents use evidence from the workspace and external sources such as Jira, Confluence, design documents, APIs, tests, dependencies, and existing conventions. - Ambiguous but low-risk and reversible issues can be documented as assumptions. - Unsafe, destructive, externally constrained, or hard-to-reverse uncertainties are escalated instead of guessed. ### Build - The approved specification is converted into a test-first verification plan before production code is changed. - The proposer identifies expected behavior, edge cases, required tests, and execution commands. - Challengers can dispute the verification design before or during implementation. - Proposers must support rejected objections with concrete evidence such as: - Execution paths - Compiler or linter output - Failing tests - Other workspace evidence - This prevents a simple green CI result from hiding missing or inadequate validation. ### Delivery - The final output is a review-ready PR package rather than merely a diff summary. - It explains: - What changed - Where reviewers should look first - Which checks passed - Remaining risks - Which challenges were already investigated - At this stage, the orchestrator acts more like a jury, judging whether sufficient evidence exists for release. ## Structured Debate Protocol - Each agent receives stage-specific context and returns structured JSON rather than a free-form essay. - Agents do not share one live context window. Shared state consists of: - Workspace files - Generated artifacts - The orchestrator’s accumulated transcript - Each round includes a proposer response, challenger response, and orchestrator decision. - The protocol distinguishes manageable uncertainty from blocking risk. - Consistent schemas make agent outputs easy to parse, compare, and feed into subsequent rounds. - For example, a challenger can identify an unclear scope boundary, explain why it matters, assign severity and confidence, and indicate whether user input is required. ## Overall Impact - Issues move through a continuous chain: debated specification, branch, tested implementation, and review-ready PR. - Humans intervene mainly to define intent, approve the final result, or resolve explicitly escalated decisions. - The central leverage comes not from generating code faster, but from requiring AI to explore, challenge, verify, and package its work before asking engineers to pay attention. The practical recommendation is to redesign AI development around explicit artifacts, specialized adversarial roles, evidence-based decisions, and automated handoffs. Human engineers should remain the final decision-makers, while AI handles the intermediate coordination and proof-building work.

Transitioning from a Legacy Project to an AI-Driven Project: The AX Roadmap (opens in new tab)

AI transformation (AX) is not achieved by simply adding AI tools; it requires redesigning the team’s development system around AI. The post proposes a four-stage roadmap for turning legacy projects into AI-driven projects, beginning with security and standardization and progressing toward specification-based development automation. Its central recommendation is to introduce AI gradually, with clear documentation, human approval gates, and measurable outcomes. ## What an AI-Driven Project Means - AI participates throughout the development lifecycle, including: - Specification writing - Code generation - Testing - Code review - Pull request creation and merging - Developers focus more on direction, judgment, and business decisions rather than repetitive implementation work. - The key methodology is **spec-driven development (SDD)**: - Requirements and implementation specifications are defined before code. - AI generates, tests, and reviews code against those specifications. - Structured specifications compensate for AI’s difficulty in interpreting ambiguous intent. ## Stage 1: AI-Ready — Establish Security and Compliance The first stage creates a safe foundation for using AI with project context and company data. - Remove hardcoded secrets such as API keys, database passwords, and internal IP addresses. - Use secret-management services to inject credentials dynamically at runtime. - Protect personally identifiable information by masking or tokenizing names, emails, phone numbers, and similar data before sending it to AI systems. - Separate or restrict access to critical intellectual property, including proprietary algorithms and sensitive architecture. - Define minimum compliance requirements first rather than delaying adoption until every security improvement is complete. - Use sandboxing, system prompts, filesystem restrictions, and network isolation to limit AI access. - Validate that isolation mechanisms actually prevent sensitive-data exposure. Expected benefits include safer AI usage, faster debugging and repetitive coding, and accumulated team experience that supports later adoption stages. ## Stage 2: AI-Assist — Standardize Team Usage This stage addresses teams where individuals already use AI but follow inconsistent practices. - Create project-level AI guidelines covering: - Project context - Coding conventions - Architecture principles - Domain terminology - Establish shared prompts, skills, or plugins for activities such as: - Brainstorming - Writing implementation plans - Code review - Subagent-driven development - Integrate AI into CI/CD for automated first-pass code reviews. - Let AI identify style violations, likely bugs, and security issues. - Reserve human review for complex business logic, architecture, and policy decisions. - At this stage, AI assists with human-written code rather than independently implementing features. Possible KPIs include: - A reduction in repetitive human review comments. - Increased test coverage. - Improved deployment reliability and system stability. - More consistent adherence to team conventions. ## Stage 3: AI-Development — Automate Implementation The third stage connects specifications directly to working code through an automated pipeline. - The pipeline includes three human approval gates: 1. **Specification review:** Confirm requirements, scope, edge cases, and validation criteria. 2. **Implementation and test-plan review:** Approve the AI-generated execution and testing plans. 3. **Code review:** Approve the final implementation before merging. - AI uses documented domain knowledge and architecture context to generate project-specific code. - A new file in a directory such as `/specs` can trigger CI automation. - CI can generate an implementation plan, execute coding tasks through independent subagents, run tests, and create a pull request. - Approval steps ensure that AI cannot proceed to the next stage without human authorization. To improve adoption, the post recommends expanding AI’s responsibilities gradually: - Begin with unit- and integration-test generation for existing logic. - Move progressively toward boilerplate and broader implementation work. - Avoid delegating critical business logic immediately, since poor early results can undermine team trust. ## Overall Adoption Principles - Each roadmap stage provides value independently; teams do not need to complete all four stages at once. - The appropriate target depends on team maturity, risk tolerance, domain complexity, and adoption speed. - Documentation is essential because AI needs structured project and business context. - Human oversight remains important, especially for requirements, architecture, business rules, and final code approval. - Security controls, common workflows, and measurable KPIs should develop alongside AI usage. Teams should start with the safest achievable stage, standardize practices before automating implementation, and expand AI’s role only as documentation, testing, and review processes become reliable.