Clarify product requirements and design system architecture

Product requirements

You wouldn’t expect a human developer to build a complex system from a two-sentence Slack message. Agents are no different.

• Be explicit. Agents can’t read your mind. If a requirement isn’t written down, assume it doesn’t exist.

• Iterate interactively. It’s fine to have the agent propose a first draft of requirements — but you own the final decisions.

• Document the vision. Create a high-quality README that explains:

  • The problem you’re solving

  • The intended users and workflows

  • Key usage examples and expected outcomes

• Review specs before implementation. Treat specs like contracts between you and the agent. Catch ambiguities before they turn into bugs.

Just like with today's software development: expect this part to be hard. Requirements take time to get right. As with any software project, requirements will change as you discover constraints through building. Agents are fast at iterating — lean into that.

System design

Agents are surprisingly good at writing isolated pieces of code, but maintaining a coherent architecture across a growing codebase is still hard for them.

Why it matters

• Without guidance, agents often introduce inconsistent patterns, duplicate logic, or conflicting abstractions.

• If you don’t understand the system’s architecture, you won’t be able to debug when the agent gets stuck.

• One of the most common failure cases we see: an agent produces a maze of ad-hoc code, the user loses track of how it works, and the only fix is to start over.

Your role as the architect

• Own the high-level design. Create a project-architecture.md that outlines:

  • Major entities and their responsibilities

  • Folder and file structure

  • Chosen tech stack and frameworks

  • Key design patterns and conventions

• Keep it simple. Fewer moving parts mean fewer ways for an agent to get lost.

• Stay in the loop. Even if agents get better at proposing architectures, you need to remain the source of truth for system design.

• If you can’t explain your system’s structure to a teammate in five minutes, your agent can’t reliably extend it either.

Expect evolution. Your architecture will change — and that’s okay. Just make sure the changes are intentional and documented.