Requirements First: The Software Architecture Methodology Used at StratoNext
Most software projects start from a rough idea, a draft architecture and move straight to implementation. Requirements, if they exist at all, are written after the fact. Architecture decisions are made implicitly, buried in pull requests, or never recorded at all. The result is a system that works technically but is hard to reason about, hard to onboard into, and full of decisions nobody remembers making.
At StratoNext we do it differently. Before any code is written, we design. And we design with agents.
The reason is context. An AI agent only knows what you tell it. Hand it an isolated task and it will produce plausible code that ignores half the system, re-decides things you settled months ago, and quietly invents architecture to fill the gaps. Agents need to know what they are working on, not just what they are being asked to do. So the context has to exist somewhere outside the conversation, written down, versioned, and readable.
We did not invent a new methodology for this. We intentionally combined four existing engineering practices:
- Requirements-first engineering, using the classic NASA style of writing requirements
- ADRs, Architecture Decision Records
- AARs, Architecture Assumption Records
- C4 architecture documentation
The goal was simple:
- Give agents the complete picture, not isolated tasks.
- Capture decisions and assumptions as they happen.
- Reconstruct the architecture at any point in time.
- Generate diagrams automatically.
- Restart agent sessions without losing context.
- Let agents reason about the system instead of just producing code.
The rest of this post is how that works in practice.
An Opinionated Approach
This is not a universal methodology. It is our opinionated answer to a specific problem: how do you build software deliberately, without the overhead of traditional waterfall, but with more structure than pure agile allows?
Agile is great at responding to change. Waterfall is great at thinking before building. We want both, the ability to move fast and iterate, but grounded in requirements that are stated before architecture is designed, and architecture that is designed before code is written.
It turns out this balance works particularly well when agents are involved. Agents are good at following structure. They are bad at navigating ambiguity. A methodology that forces clarity upfront, requirements, decisions, assumptions, cross-checks, gives agents exactly the kind of grounded context they need to be useful. The more we write down before implementation, the better agents perform during implementation.
For requirements, we chose the NASA writing standard. It is strict, unambiguous, and battle-tested: active voice, one statement per requirement, verifiable thresholds, no implementation detail. It forces you to say what the system must do, not how it should do it. That distinction matters more than it sounds.
The following is what we use at StratoNext.
The Methodology
The pipeline is linear and deliberate:
Requirements → Architecture → Architecture Decision Records (ADR) → Architecture Assumptions Records (AAR) → Code
Each stage has a gate. You cannot design architecture without requirements. You cannot write code without architecture. Every significant decision produces an ADR. Every assumption produces an AAR. Nothing is implicit.
Requirements define what the system must do, never how. They are verifiable, numbered, and traceable. A requirement that cannot be tested does not get written; it gets a TBR marker until it can be. This forces the team to think about outcomes before solutions.
Architecture responds to requirements. Every document references the requirements it satisfies. Every constraint traces back to a stated need. The architecture describes what will be built and why, not how it will be implemented. Implementation is a separate concern.
ADRs (Architecture Decision Records) capture every significant design choice: what was decided, what was rejected, and why. They are permanent. Six months from now, when someone asks why the system works a certain way, the answer is already written.
AARs (Architecture Assumption Records) capture everything the design relies on that has not yet been confirmed. Assumptions are not buried in prose, they are named, tracked, and linked from the documents that depend on them. An open AAR is a known risk. A closed AAR is a resolved one.
Code is the last step. By the time implementation begins, every decision is already made, every tradeoff is already recorded, and every assumption is either confirmed or flagged. Developers, human or agent, implement what is designed, not what they guess.
The critical discipline at every stage is cross-checking. New requirements are checked against existing ones. New architecture documents are checked against existing decisions. The agent flags contradictions before they compound. The goal is not to produce documents, it is to surface issues early, when fixing them is cheap.
The Software Architect Agent Skill
This methodology is document-heavy by design. Requirements, architecture documents, ADRs, AARs, every stage produces structured text. Without agents, this would be as slow and painful as traditional waterfall: too much ceremony, too much overhead, too much friction for a fast-moving team.
But agents are exceptionally good at reading and producing structured text. They can hold the full context of a requirements file, cross-reference it against a dozen architecture documents, spot a contradiction, and ask the right question, in seconds. The document-heavy nature of this methodology is not a cost when agents are involved. It is an advantage.
To make this methodology practical and consistent, we implemented a single agent skill: software-architect. The skill has two modes, requirements and architecture, and it governs how the agent behaves in both. It is not a prompt. It is a structured definition that lives in the repository alongside the code, versioned, reviewable, and shared across every session and every engineer.
The skill reads one input and produces a structured set of outputs:
# Input
project.md project context, vision, terminology
# Outputs
requirements.md all requirements, numbered and traceable
docs/architecture/ARCH-XXX-*.md architecture documents (C4 prose)
docs/architecture/decisions/ ADRs - one per significant decision
docs/architecture/assumptions/ AARs - one per open assumptionThe skill enforces discipline that would otherwise depend on memory or convention. It tells the agent what to ask, what to record, what to refuse, and what to produce. The agent does not freelance.
Mode 1, Requirements
When a feature or constraint is described, the agent enters requirements mode. It applies NASA-style writing rules: active voice, one statement per requirement, verifiable thresholds, TBR markers for anything undefined.
Before writing, the agent identifies how many distinct requirements the description contains and confirms the split. It asks for clarification on any unverifiable term. It refuses to write a requirement it cannot test.
## REQ-036, Agent Credential Request via Approval Flow
StratoNext shall allow an agent to pause a running task and emit a credential
request that enters an approval flow before execution continues.
## REQ-037, Task Resumption After Credential Approval
StratoNext shall automatically resume a paused task once its pending credential
request has been approved, and shall allow the resumed task to be assigned
to a different agent than the one that originally paused it.The result is a requirements.md file that is the single source of truth for what the system must do. Every requirement is numbered, traceable, and verifiable. Nothing is vague.
Mode 2, Architecture
Once requirements exist, the agent enters architecture mode. It produces C4-level documents in prose, context, container, component, feature, and writes an ADR (Architecture Decision Record) for every significant decision.
Every document is structured with a YAML front matter block that carries metadata: document type, C4 level (L1 through L4 for standard C4 documents, extended with cross-cutting and infra for feature and deployment documents that span multiple levels), status, and related documents. This is not decoration. It means every architecture document is machine-readable. Agents can automatically categorize documents, resolve cross-references, and generate C4 diagrams directly from the metadata without parsing prose.
---
id: ARCH-004
title: Approval Workflow
type: container
c4_level: L2
status: draft
---Before writing any document, the agent scans existing architecture files for conflicts. If a new design contradicts a prior decision, it surfaces the conflict and asks for resolution. It does not silently override.
For feature documents, the agent challenges the description with clarifying questions before writing a single line. It applies software engineering and security best practices as lenses: single responsibility, least privilege, no credential persistence, audit trail, failure handling. The questions force design thinking before implementation thinking.
Agent: "Before I write this, a few questions:
1. Who generates the credential, the platform or the identity provider?
2. Is the credential fetch a one-time operation or can the agent re-fetch?
3. What happens when the approval window expires, terminal failure or retriable?
4. Can the same approval be reused across tasks?"Each answer shapes the architecture. The document that results is not a description of what was built, it is a specification of what will be built, with every decision already made and recorded.
## Constraints and Decisions
- Credentials are generated by CredentialBrokerService at fetch time, not at
approval time, and retrieved once; they are never persisted → REQ-024, REQ-041
- Only one credential request may be active per task; new requests invalidate
prior pending ones → REQ-040
- Approval window expiry results in a retriable task failure → REQ-040
- Email is used for human approval notification; CIBA is not used → ADR-009Tracked, Not Buried
Every time the design relies on something not yet confirmed, the agent creates an AAR, Architecture Assumption Record. Assumptions are not buried in prose. They are tracked, named, and linked from the documents that depend on them.
---
id: AAR-006
title: Cross-Agent Credential Fetch Does Not Introduce a Security Gap
status: open
---
## Assumption
Allowing a different agent to fetch an approved credential than the one that
originally paused the task is safe, provided the fetching agent is the one
currently assigned to the task at fetch time.
## Impact if Wrong
If the task-assignment-at-fetch-time check is insufficient, an attacker who
can manipulate task assignment could redirect credential issuance to an
unintended agent.This is the difference between assumptions that surface in production and assumptions that are resolved before a line of code is written.
The Architecture Is Visible
Every container, every service, every decision is documented. The architecture can be rendered as C4 diagrams directly from the documents.
This means the architecture is not in someone’s head. It is in the repository, queryable, renderable, and always current. Any AI Agent can query the architecture repository and understand the system’s design without needing to read code. Also generate a diagram like this one becomes straight-forward for any AI Agent.
Every Decision Is Traceable
The skill enforces cross-checking at every step. New requirements are checked against existing ones. New architecture documents are checked against existing decisions. The agent flags contradictions before they become bugs.
Every architecture document is validated against the requirements. The agent identifies requirements with no architectural coverage and architecture decisions with no corresponding requirement. Every gap must be resolved before moving forward. The cross-check is not a one-time audit-it is part of every design session.
The Codebase Starts With Context
One of the most important properties of this approach is that everything is written down, in a form that both humans and agents can read. When a new engineer or a new agent joins the project, they do not start from code. They start from requirements and architecture documents that tell them exactly what the system does, why every decision was made, and what assumptions are still open.
Future implementation agents, the ones that will actually write the code, are guided by this foundation. They do not take assumptions. They do not invent architecture. They implement what is already designed, with full context for every decision.
Design Before Code
The software-architect skill is not a documentation tool. It is a design tool. It forces requirements to be stated before architecture is designed. It forces architecture to be designed before code is written. It forces every assumption to be named. It forces every decision to be recorded.
The agent is not doing the thinking. The agent is making sure the thinking happens, by asking the questions that are easy to skip, by refusing to proceed on ambiguity, by surfacing conflicts before they compound.
The result is a codebase that starts from clarity rather than arriving at it.