Why Does AI Coding Get Messier with Every Change? From Requirements to Spec-Driven Development

You ask AI Coding Agent to make a simple request:

Add “Export CSV” function to order list.

Agent quickly adds buttons and interfaces. You tried it and added:

The exported order should be the filtered order, and the Chinese should not be garbled.

It continues to be modified. A product colleague saw this and said:

It also supports exporting all data, and the browser cannot freeze when there are more than 10,000 items.

Agent also introduces background tasks, polling and download centers. During testing, we discovered that: Ordinary employees can also export orders from other departments; switching filter conditions during export will result in incorrect data; newly added dependencies conflict with project specifications; originally only one list page was changed, but in the end more than a dozen files were changed.

Each round of dialogue makes perfect sense on its own, but the code becomes increasingly confusing.

It’s usually not that the agent “suddenly dumbed down” but rather that the task never had a stable source of truth. Each addition is like moving the end point, and the Agent can only re-guess based on the current dialogue: which old decisions are still valid, what scope this modification affects, and to what extent it is considered complete.

The solution is not to make the first Prompt infinitely long, but to first organize the requirements into a Specification (Spec) that can be discussed, versioned, and accepted, and then let plans, tasks, codes, and tests unfold downward from this specification.

This is the problem that Spec-Driven Development (SDD) wants to solve.

1. Let’s talk human words first: Spec is a “task contract” used by the team and Agent.

Descriptions of daily needs usually express wishes:

Add CSV export, the experience should be better, and it should be usable even when there is a lot of data.

This sentence is enough to start a discussion, but not enough for the Agent to safely modify the code. Because it leaves at least these questions:

• Who can export?
• Export the current page, all results, or the current filtered results?
• How much exactly does “a lot of data” mean?
• Synchronous download or asynchronous task?
• What encoding, time zone and field order does the CSV use?
• What does the user see after the export fails?
• Does it contain hidden fields and sensitive information?
• What evidence can prove that the requirements have been completed?

The role of Spec is to turn “everyone’s possible different understandings in their minds” into an explicit agreement.

A practical Spec doesn’t have to be long, but it should give at least three roles the same answer:

It can be understood as:

Need description: What do I want?
Spec: What the system must behave like, and how to prove it does it
Plan: How to prepare to achieve it
Tasks: Modify which parts in what order
Code & Tests: Implementation and verification evidence

Spec is not intended to replace communication, but to fix the results of communication and prevent the same problem from being reinterpreted repeatedly during the implementation phase.

2. Why does the Prompt driver easily get out of control?

There is nothing wrong with Prompt itself. For small and clear tasks, one Prompt is enough. The real danger is keeping ever-increasingly complex requirements just in the chat log.

1. Dialogue is a chronological sequence, and requirements are structural relationships.

Chat history usually looks like this:

Add export button first
→ Change to export filter results
→ Support all data again
→ Asynchronous processing of large amounts of data
→ Ordinary employees can only export their own department
→ The field order has been adjusted again

But what really needs to be implemented is a set of rules that are established at the same time: permission rules, scope rules, performance rules, field rules, and exception rules. They are not as simple as “the last sentence overwrites the previous sentence.”

When the constraints are scattered across dozens of dialogue rounds, it’s easy for the Agent to:

• Only execute the latest additions and forget about earlier constraints;
• Mistaking the suggestions in the discussion for the final decision;
• Destroying one scene while repairing another;
• It is impossible to determine which code changes are requirements and which are just convenient refactorings.

2. Fuzzy words will be automatically completed

“Fast”, “friendly”, “large quantities”, “compatible”, “as much as possible” and “appropriate” are not requirements that can be directly accepted.

Human colleagues often complete these words based on project experience. Agent will also complete it, but what it completes is the most likely answer, not necessarily the answer to your project.

For example “export cannot be too slow” might be interpreted as:

• Download starts within 2 seconds after clicking;
• 10,000 pieces of data generated within 30 seconds;
• Requests cannot exceed the gateway’s 60 second timeout;
• The main thread of the page cannot be frozen for more than 100 milliseconds.

All four explanations are reasonable, but result in completely different designs.

3. Without non-goals, Agent will regard “doing it more completely” as correct

If you only write “support export”, the Agent may add it by the way:

• Export history;
• Scheduled export;
• Excel format;
• Custom fields;
• Email sending;
• A new set of task queues.

These features are not bad ideas, but they are outside the current task. A specification’s non-goals tell the Agent clearly: do not build these yet.

4. There are no acceptance criteria, and “completion” can only rely on feeling.

When the Agent says “completed”, it may only mean that the code has been written to the file. When you say “not what I want”, it usually means that the two parties have never agreed on observable completion conditions.

Without acceptance criteria, Review will degenerate into:

It looks wrong to me, please change it again.

Each “re-revision” opens up a new round of speculation.

3. Specification-driven does not mean waterfall, nor does it mean writing a hundred pages of documents first.

When they hear “write specifications first”, many people worry: Will we have to go back to requirement freezing, long document approval, and writing code months later?

no.

Specification-driven emphasizes the elimination of high-cost ambiguities before entering implementation, rather than requiring all future changes to be predicted at once.

Spec can be iterated and should change as real decisions are made. The difference is that changes go into the spec first, re-examine the impact, and then go into the code, rather than directly applying layer upon layer of patches to the code.

GitHub’s Spec Kit summarizes this link as Spec → Plan → Tasks → Implement. Its official description emphasizes that the Markdown product generated in each stage will become the structured context of the next stage, rather than continuing to rely on temporary prompts.

4. What should an executable Spec contain?

Different teams can use different templates, but the following seven sections are very general.

1. Background and issues

Explain why you are doing it first, rather than specifying button colors and interface paths right away.

## background

Operations staff can currently only copy order data page by page, and it takes about 2 hours to compile reports every week.
And it is easy to miss the filtering conditions when copying manually. Requires permission-controlled CSV export capability.

“Why” will help the agent make more reasonable judgments when details conflict. For example, if the goal is to reduce manual reporting time, “Keep current filters” is more consistent with the goal than “Export only current page.”

2. Users and usage scenarios

Don’t just write “Users can export”, indicate who can use it and under what circumstances.

## User

- Operations Specialist: Export the filtering results of his own department.
- Operations administrator: can export all department data that has permission to view.
- Users without order viewing rights: cannot see the export entrance, nor can they call the export interface.

3. Scope and non-target

Scope answers “What to do this time”, non-target answers “What things that seem relevant will definitely not be done this time”.

## scope

- Provides CSV export in order list.
- The export conditions are consistent with the filter conditions when initiated.
- Direct download of small data amounts, and create asynchronous tasks for large data amounts.

## non-target

- Excel and PDF formats are not supported.
- User-defined export fields are not supported.
- No additional scheduled export and email sending.
- Do not refactor the existing order query module.

The non-goal is not to never do it, but to protect the current delivery boundaries.

4. Functional requirements

Each requirement uses a stable number to describe observable behavior.

## Functional requirements

- FR-001: Users with order viewing rights MUST be able to initiate CSV export in the order list.
- FR-002: Export MUST solidify the filtering conditions when the user clicks, and will not be affected by subsequent page operations.
- FR-003: Export results MUST only contain orders that the user has permission to view.
- FR-004: SHOULD download directly when the number does not exceed 10,000.
- FR-005: MUST create asynchronous tasks and show progress when more than 10,000 items are exceeded.
- FR-006: Failed tasks MUST show an understandable reason and allow the user to retry.

The requirement levels from the IETF RFC 2119 are borrowed here: MUST means an absolute requirement, SHOULD means that it should generally be met and the consequences of deviation must be understood and weighed, and MAY means that it is truly optional. Business Specs do not have to copy the full text of the standard, but unifying the meaning of these words can reduce the debate between “best to support” and “must support”.

5. Constraints and quality attributes

Just because the function is correct does not mean it can go online. Permissions, performance, compatibility, observability, and data security also go into specifications.

## Constraints

- SEC-001: The backend MUST re-verify the data range based on the current user and cannot trust the department ID passed in by the frontend.
- PERF-001: When directly exporting 10,000 orders, the server processing time p95 MUST be less than 8 seconds.
- UX-001: Async tasks MUST show "Building" status within 1 second after creation.
- DATA-001: CSV MUST use UTF-8 with BOM, and the date is uniformly output in the `Asia/Shanghai` time zone.
- OBS-001: Export tasks MUST record the operator, filter summary, number of results, and failure reason.

More numbers are not better. Only metrics that truly impact design or acceptance are worth writing about; pseudo-precise numbers that can’t be measured and no one cares about just create noise.

6. Acceptance scenario

Requirement items explain the rules, and acceptance scenarios use specific examples to eliminate ambiguities.

Cucumber’s Gherkin Reference Organize the example as Given / When / Then: the initial state is known, an action occurs, and an observable result is obtained. The official documentation also reminds that Then should focus on external observable results such as interfaces, messages or reports, rather than internal database implementation.

Scenario: The operations specialist exports the screening results of his department
If the user belongs to the East China Operations Department and has order viewing permissions
And the list filter condition is "paid, 2026-07-01 to 2026-07-31"
When the user clicks "Export CSV"
Then the downloaded file only contains orders that meet the filter conditions in the East China Operations Department.
And the file uses UTF-8 with BOM encoding
Moreover, the operation log records this export

Scenario: User tries to bypass the front-end to export data from other departments
If the user only has data permissions for the East China Operations Department
When the user directly requests the export interface and passes in the South China Operations Department ID
Then the interface returns 403
And no export file is created
And the security log records rejected requests

Not all teams need to install Cucumber. Even if we only use Given/When/Then as a manual acceptance template, it forces us to write clear preconditions, actions, and results.

7. Open issues and decisions

Don’t let the Agent quietly decide for the team on matters that are still controversial.

## Open issues

- Q-001: Are asynchronous export files retained for 24 hours or 7 days? Responsible: Product, Deadline: August 5th.
- Q-002: Do I need to escape formula injection characters? Responsible: Security, Deadline: August 5th.

## Decision confirmed

- D-001: This issue reuses the existing task center and does not create a new download center.
- D-002: The field set is fixed and is not open to user customization.

Open issues should prevent related tasks from entering implementation, rather than being passed off with a “common practice” statement.

5. How to write natural language more accurately: borrow the sentence pattern of EARS

Requirements do not necessarily have to be turned into a formal mathematical language. A lightweight approach is to add stable structure to natural language.

EARS (Easy Approach to Requirements Syntax) proposed by Rolls-Royce researchers at the IEEE Requirements Engineering conference uses a small number of sentences to constrain natural language requirements and address common problems such as ambiguity, complexity, and ambiguity. Its value does not lie in memorizing terminology, but in forcing the author to complete “when, in what state, and what the system does.”

Common sentence patterns can be simplified to:

Compare the following two sentences:

Bad: Be friendly when exporting fails.

Good: If an asynchronous export task fails, the system must display the failure status and understandable reasons in the task list.
and allows users to re-create tasks while filters are still in effect.

The second sentence is still natural language, but it can already derive interface status, error model, retry logic and test scenarios.

6. From Spec to code, Plan and Tasks cannot be skipped in the middle.

Once you have Spec and let the Agent write the code immediately, problems may still occur. Because “how the system should behave” and “how to implement it in the current warehouse” are two types of questions.

Spec: Definition of What and Why

Spec should try not to be tied to a specific implementation:

When the number exceeds 10,000, an asynchronous task must be created.

Plan: Explain How

Plan combines the real code base to make technical decisions:

- Reuse existing `JobService` and add `ORDER_EXPORT` task type.
- Query multiplexing `OrderQueryService`, the server injects the data range according to the current user.
- The generated file is written to existing object storage with a lifetime set to 24 hours.
- The front end reuses the `TaskProgress` component and does not add a new polling framework.
- Risk: Order query currently does not provide streaming reading and needs to verify the memory peak of 10,000 items.

Tasks: Split the plan into verifiable increments

The task is not a big package like “implementing the export function”, but should be completed and verified individually:

- [ ] T001 [FR-003] Add server-side data range test for order export query
- [ ] T002 [FR-002] Define immutable ExportFilter snapshot
- [ ] T003 [FR-004] Implement small data volume CSV generation and encoding test
- [ ] T004 [FR-005] Access JobService asynchronous task
- [ ] T005 [UX-001] Display task creation and progress status on the list page
- [ ] T006 [OBS-001] Add export audit log
- [ ] T007 [AC-01~AC-05] Run end-to-end acceptance scenario

Implement: Execute according to tasks, do not reinvent requirements in the process

Problems with Spec can be discovered during implementation, but should not be fixed silently in the code. The correct approach is:

find ambiguity
→ Back to Spec for clarification
→ Update affected plans
→ Regenerate or adjust Tasks
→ implement
→ Verify based on acceptance scenario

Spec-driven is not a one-way pipeline, but a feedback loop with clear fallback positions.

7. Complete practice: rewrite one sentence of requirements into executable specifications

Let’s start with the initial requirements:

Added CSV export to order list.

Step one: Let the Agent ask questions first, don’t let it write code immediately

Don't modify the code yet. Please read the order list, permission model, existing task center, and test structure first.

For the requirement of "adding CSV export to the order list":
1. List the ambiguities that will affect implementation;
2. Distinguish between business issues and technical issues;
3. Provide documentary evidence for facts that can be confirmed from the warehouse;
4. List matters that cannot be confirmed as questions and do not make assumptions on your own;
5. Finally, a Spec draft is given without generating an implementation plan.

The key to this step is to separate “exploration” and “modification”. Agents can confirm existing permissions, components, and task infrastructure through code, but cannot guess business retention periods or product scopes from code.

Step 2: Review the Spec, not the writing

Key points to check:

• Is each role clear?
• Is each ambiguous word replaced by a number or scene?
• Are normal, empty data, no permission, failure and large data volume covered?
• Can non-targets prevent range inflation?
• Do the constraints come from a real system?
• Can each acceptance criterion be observed or measured?
• Are there still product decisions made privately by Agents?

You can have another session just do counterexample review:

Only review this Spec, do not write code.

Please find out from the five perspectives of product, development, testing, security and operation and maintenance:
- Ambiguity and conflicting requirements;
- Missing boundary conditions;
- Unverifiable acceptance criteria;
- Implementation details that were incorrectly written as requirements;
- Scenarios that may lead to unauthorized access, data leakage, or unrecoverable operations.

Each question quotes the corresponding requirement number and provides minimal modification suggestions.

Step 3: Establish tracking relationship

No need to purchase a complex requirements management platform. Small and medium-sized projects can use Markdown numbering to establish basic tracking:

Tracing relationships answers two very practical questions:

1. Which requirement is this change intended to meet?
2. What evidence can be used to prove that this requirement has been met?

If a task cannot find the source of the requirements, it may be scope drift; if a requirement cannot find evidence of testing or verification, it may not be truly completed.

8. Use GitHub Spec Kit to run the standard process

GitHub Spec Kit is an open source specification-driven development toolkit. It is not a new programming language, nor will it determine product requirements for you; it provides templates, commands, and product directories to allow Agents to work in a stable process.

The official current core process is:

constitution
→ specify
→ clarify
→ plan
→ checklist
→ tasks
→ analyze
→ implement
→ converge

The command form of different Agents may be /speckit.*, $speckit-* or other integration forms, which should be subject to Spec Kit official integration instructions.

1. Installation and initialization

According to the official README, you can use uv to install specify-cli:

uv tool install specify-cli
specify init . --integration codex

If you use another Agent, replace codex with the officially supported integration name. Do not use --force directly on important repositories without understanding what files will be written during initialization.

2. Constitution: First determine the principle that the project cannot change with the task.

/speckit.constitution
The project must reuse existing components; the generated code must not be modified manually;
All data reads must perform server-side permission checks;
Functional changes must include automated testing and reproducible verification evidence.

Constitution solves “how this project will work in the long term”; Spec solves “how the function must behave this time”. Don’t mix the two into one document that grows indefinitely.

3. Specify: Write What and Why first

/speckit.specify
Added CSV export for order list. Operation personnel need to export the current filtering results for weekly reporting;
Export must comply with order data permissions, and Chinese can be opened directly with Excel;
This issue does not support custom fields, scheduled export and email sending.

Spec Kit officially recommends focusing on “what to do and why” at this stage, leaving the technology stack and architecture selection to Plan.

4. Clarify vs. Checklist: Eliminate ambiguity before design becomes expensive

/speckit.clarify
Focus on checking permission scope, large data volume threshold, failure retry and file retention time.

/speckit.checklist
Generate specification quality lists for safety, performance and acceptability.

The official analogy of Checklist is to “unit testing of requirements”: it checks not the code, but whether the specifications are complete, clear, and consistent.

5. Plan: Choose the implementation method based on the real warehouse

/speckit.plan
Reuse the existing JobService, Object Storage and TaskProgress components of the warehouse;
The backend uses the existing OrderQueryService and injects the current user's data permissions;
The tests follow the project's existing Vitest and Playwright structures.

Spec Kit’s Plan template will explicitly record the technical context, dependencies, testing methods, target platforms, performance goals, constraints, scale, and project structure. This information should not be pretended to be achievable if it is still NEEDS CLARIFICATION.

6. Tasks and Analyze: Check whether each task has a source

/speckit.tasks
/speckit.analyze

According to Agentic SDD Official Reference, analyze will read-only check for conflicts, omissions, and ambiguities between spec.md, plan.md, and tasks.md. For example: a task does not have corresponding requirements, or the Plan selection conflicts with the Spec.

7. Implement and Converge: implement in pieces and return to specification acceptance

/speckit.implement only implements permission checking and filtering snapshots, and stops after verification.
/speckit.implement implements synchronous CSV downloads, stopping after verification.
/speckit.implement implements asynchronous tasks and front-end progress.
/speckit.converge

Complex Functions Do not have the Agent perform all tasks at once. Spec Kit’s Complex Function Guide also points out that the Agent may gradually ignore plans or tasks during a long implementation process; the official recommendation is to reduce the scope of each implementation and split it into independent sub-specifications if necessary.

Spec Kit is a process scaffold, not a correctness proof. The generated Specs, Plans, and Tasks still require review by business, technical, and security leaders.

9. How detailed should the specifications be written?

Specifications are not longer the better. The granularity should match the ambiguity, risk, and cost of modification.

To determine whether more detail is needed, you can ask four questions:

1. Will different people have different understandings of this sentence?
2. Should I change a button after making a mistake, or will it leak data and damage the state?
3. Does it span multiple modules, teams or external systems?
4. Do I need to continue working after a few days or using another agent?

The more “yes”s there are, the more worthwhile it is to write the spec first.

10. When needs change, where to change first?

Spec-driven development doesn’t prevent change, it makes it trackable.

Suppose the product later requires that asynchronous file retention be changed from 24 hours to 7 days.

Wrong way:

Tell the Agent directly: "By the way, change the retention time to 7 days."

Correct order:

1. Update the retention policy and reasons in Spec;
2. Check whether privacy, storage costs and download permissions are affected;
3. Update the object storage life cycle in Plan;
4. Update corresponding tasks and tests;
5. Only modify the affected code;
6. Use old and new acceptance scenarios for regression.

This way the next person who takes over can know “why 7 days” instead of just seeing a mysterious number in a configuration file.

11. Common failure methods

1. Write Spec as a solution list

Writing “add a Redis queue, create three tables, and use a certain library” at the beginning will lock the design prematurely.

First write the system behavior and constraints, and then let Plan choose the technical solution based on the current situation of the warehouse.

2. Spec is generated by Agent but no one confirms it

Agent can sort out language and find missing items, but cannot decide permissions, scope and compliance requirements for business leaders.

Generation is not confirmation. Any assumptions that affect product behavior must be reviewed explicitly.

3. Acceptance criteria are still adjectives

Bad: The page responds quickly and the failure prompt is friendly.
Good: The task status appears within 1 second after clicking export; if it fails, the reason and retry entry are displayed.

4. All requirements are marked MUST

If there is no priority, there is no real priority. Use MUST, SHOULD, and MAY with consistent meaning and allow the team to discuss costs and trade-offs.

5. Spec, Plan, and Tasks will drift after writing.

More documentation does not mean traceability. Requirement numbers, task references, and test evidence must be connected; otherwise you’re just moving the clutter out of the chat window into multiple Markdown files.

6. Stuff the implementation log back into Spec

Spec records stable intent and confirmed behavior, Plan records technical decisions, Tasks records execution, and PR or delivery report records actual modifications. Responsibilities get mixed up and documentation quickly loses credibility again.

7. Small tasks also complete the entire process

It doesn’t take a Constitution, ten pages of Spec, and twelve commands to correct a typo. Process costs should be matched to risks.

12. Lightweight Spec template that can be copied directly

# Feature: <feature name>

## Background and goals
- Current issues:
- Target users:
- Expected results:

## scope
-

## non-target
-

## Functional requirements
- FR-001：
- FR-002：

## Constraints and quality requirements
- SEC-001：
- PERF-001：
- DATA-001：

## Acceptance scenario
### AC-001: <scenario name>
- Given：
- When：
- Then：

## Boundaries and exceptions
- Empty data:
- No permissions:
- Repeat:
- Concurrent changes:
- External dependency failed:

## Open issues
- Q-001: <question>; owner: <role>; deadline: <date>

## Decision confirmed
- D-001：

When used with Agent, you can require:

Please organize the following requirements into a lightweight Spec based on the warehouse facts.

Require:
1. Explore relevant codes, rules and tests first without modifying files;
2. Distinguish between goals, scope, non-goals, functional requirements, quality constraints and acceptance scenarios;
3. Use a stable number for each requirement;
4. Business matters that cannot be confirmed from the warehouse are listed in "Pending Issues", do not guess;
5. Acceptance criteria must be observable or measurable results;
6. Before the Spec is confirmed by me, no Plan will be generated and no code will be written.

Original requirement: <paste requirement here>

13. Minimal practices you can start today

Start with your next moderately complex need without installing any tools:

1. Spend 15 minutes writing goals, scope, and non-goals;
2. Number the functional requirements;
3. Write one normal scenario and three failure/borderline scenarios;
4. Let the Agent only find ambiguities without writing code;
5. Generate Plan after confirmation;
6. Split the Plan into verifiable Tasks at each step;
7. The delivery report is required to correspond to requirements and evidence item by item.

You will find that the greatest value of specifications is not to “let the Agent write all the code at once”, but to expose errors earlier:

• Requirement issues are exposed in the Spec stage;
• Design issues are exposed in the Plan stage;
• Dependency and order issues are exposed in the Tasks stage;
• Implementation issues are exposed during the testing and review phases.

The earlier it is detected, the cheaper the repair will be.

Summary

AI Coding becomes more and more chaotic as it changes, often not because the generation speed is not enough, but because of the lack of stable boundaries: requirements are scattered in the dialogue, fuzzy words are automatically completed, non-goals are not declared, and completion conditions cannot be verified.

Specification-driven development establishes a traceable link:

Intent → Spec → Plan → Tasks → Code → Tests → Evidence

Remember four principles:

1. Clarify behavior before choosing an implementation.
2. Write non-goals and acceptance criteria into the specification.
3. Make every task and test traceable to a requirement.
4. When requirements change, update the source of truth before updating code.

When Spec becomes a task contract read jointly by the team and Agent, Prompt no longer bears the pressure of “remembering everything”. The agent does not need to re-guess the destination in each round of dialogue, but can complete the delivery along a clear and verifiable path.

References

• GitHub Spec Kit
• Spec Kit：What is Spec-Driven Development?
• Spec Kit: Agentic SDD Command Reference
• Spec Kit：Handling Complex Features
• Cucumber Gherkin Reference
• RFC 2119：Key words for use in RFCs to Indicate Requirement Levels
• EARS: Easy Approach to Requirements Syntax