I keep seeing the same advice about AI coding agents: write a detailed specification first, then let the agent build the software.
Clear requirements certainly help. But how detailed can the specification be before we have tried to build anything? Clear requirements certainly help. But how detailed can the specification be before we have tried to build anything? As Fred Brooks noted in his classic essay on essential and accidental complexity in software, the hardest part of building software is deciding what to build, and those details rarely become clear until you confront real data.
Suppose we need to import a supplier’s product catalogue. The task looks simple:
- Read a CSV file.
- Find each product by SKU.
- Update its price.
We can describe the file format and give the agent a few examples. It writes the code, and the first tests pass.
Then we receive a real file. Some SKUs appear more than once because the supplier uses them for product variants. A missing product might be discontinued, or it might just be absent from this week’s file. A price of zero might be valid, but we probably shouldn’t publish it without checking. Then we receive a real file. Some SKUs appear more than once because the supplier uses them for product variants. A missing product might be discontinued, or it might just be absent from this week’s file. A price of zero might be valid, but we probably shouldn’t publish it without checking. Every one of these edge cases exposes the limits of programming using only natural language.
Now we have questions that weren’t in the original specification. We can answer them and update the document. But we found them by working with the actual problem, not by planning harder beforehand. Now we have questions that weren’t in the original specification. We can answer them and update the document. But we found them by working with the actual problem, not by planning harder beforehand. Because requirements evolve like this during implementation, how we structure C# projects for AI-assisted changes becomes just as important as the initial specification.