Codex as a Solution Architect: A Practical Experiment
Generating BRDs, HLDs, Test Strategies, Estimates, and Migration Plans from Source Code
At some point in our careers, most of us in the technology industry have been involved in migrating an application, whether as developers, testers, architects, project managers, or support engineers. If you’ve ever been part of a go-live weekend, you know exactly how challenging it can be. Consider this a salute to the unsung heroes who make those migrations successful.
This article is dedicated to you.
Long before the go-live weekend arrives, teams spend countless hours understanding the existing application, gathering requirements, analyzing architecture, identifying risks, estimating effort, and producing the documentation needed to execute the migration successfully. When documentation is missing, outdated, or the original developers are no longer available, this process becomes even more challenging.
Modernization projects rarely fail because teams cannot write new services. They fail because teams do not understand the existing system well enough before they start changing it.
For many enterprise applications, the discovery phase is slow, manual, and fragile. Architects interview subject matter experts, review scattered diagrams, browse unfamiliar code, sit through demos, and reverse-engineer business behavior from database tables and service classes. If the original developers are no longer available, that discovery effort becomes even harder. The team may know the application is important, but not where the real business boundaries are, which workflows are risky, which integrations are active, or where data ownership actually lives.
This is especially true in monolith-to-microservices migration programs. Before writing a target architecture, teams need a current-state view, bounded-context inventory, dependency map, service candidates, risks, assumptions, estimates, test strategy, and migration plan. Producing that documentation manually can take weeks, and the first version is often incomplete because it depends heavily on people’s memory.
AI-assisted repository analysis can shorten that discovery cycle. Used properly, it does not replace architects or engineers. It gives them a faster way to inspect the codebase, generate first-draft documentation, expose assumptions, and create a shared baseline for review.
This article walks through a practical approach using Codex CLI against the nopCommerce repository as a sample migration assessment.
What is Codex?
Codex is an agentic coding assistant that can work directly with a local repository. In a terminal-driven workflow (CLI), it can read files, inspect project structure, search for references, understand code organization, and generate or update documentation based on repository evidence.
For modernization work, this matters because the repository is often the most reliable source of truth. Documentation may be stale. Diagrams may be missing. SMEs may remember the major workflows but not every dependency. Codex can help explore the codebase systematically and produce structured outputs for human review.
In this demonstration, Codex CLI is used to:
- Inspect solution structure and project dependencies.
- Discover business domains and bounded contexts.
- Identify service extraction candidates.
- Capture risks, assumptions, and unknowns.
- Generate stakeholder deliverables such as BRD and HLD.
- Support a repeatable migration assessment workflow.
Setup is intentionally out of scope here. The focus is the assessment workflow and how repository analysis can accelerate documentation and architecture discovery.
Project Overview
For this walkthrough, I used nopCommerce as the sample application. It is a mature commerce platform with a realistic modular monolith structure.
The repository includes:
- Core domain entities.
- Data access and migrations.
- Business services.
- Storefront and admin web projects.
- A plugin ecosystem for payments, shipping, tax, marketing, analytics, storage, authentication, search, and content.
It has real business domains, integration points, shared data concerns, and enough complexity to make manual discovery non-trivial.
The expected outputs for the assessment included:
- Executive Summary
- Domain Inventory
- Dependency Map
- Service Candidates
- Risks and Assumptions
- BRD
- HLD
- Test Strategy
- Revised Estimates
- Migration Plan
The goal here is to accelerate discovery and produce a structured baseline for architecture review.
Repository Preparation
The first step is simple: fork or clone the target repository and open it locally.
Then open the repository in a terminal where Codex CLI can operate. At this stage, the repository should be treated as the source of evidence. Instead of starting with assumptions about the architecture, the workflow starts by asking Codex to inspect the solution structure, projects, folders, dependencies, services, entities, and plugins.
Agent Instructions
For larger assessments, it helps to provide project-level guidance through an `AGENTS.md` file. This file tells Codex what role it should play and what standards it should follow.
In this case, the agent was guided to behave like a migration architect performing a monolith-to-microservices assessment. The instructions emphasized evidence-based analysis, repository-first reasoning, bounded context discovery, business capability alignment, and incremental strangler migration.
A representative snippet of agents.md looks like this:
# NopCommerce Migration Architect
You are a software architect performing a monolith to microservices migration assessment.
Objectives:
1. Understand current nopCommerce architecture.
2. Discover bounded contexts and business domains.
3. Identify service decomposition candidates.
4. Produce migration deliverables.
5. Prefer business capabilities over technical layers.
Outputs:
- Domain Discovery
- BRD
- HLD
- Test Strategy
- Estimates
- Migration Execution Plan
Rules:
- Keep analysis evidence-based.
- Use repository structure before assumptions.
- Prefer incremental strangler migration.
- Highlight risks and dependencies.
# Available Skills
- domain-discovery
- architecture-analysis
- migration-planning
Skills are located under:
codex/skills/The benefit is consistency. Instead of each prompt restating architectural principles, the agent has a standing operating model for the whole assessment.
Organizing the Codex Workspace
A clean workspace structure makes the assessment repeatable. I organized the repository-side artifacts into a “codex” folder with separate areas for skills, prompts, analysis, and deliverables.
codex/
skills/
architecture-analysis/
skills.md
domain-discovery/
skills.md
migration-planning/
skills.md
prompts/
01-solution-structure.md
02-domain-discovery.md
03-dependency-map.md
04-service-candidates.md
05-risks-and-assumptions.md
06-executive-summary.md
07-brd.md
08-hld.md
09-test-strategy.md
10-estimates.md
11-migration-plan.md
analysis/
deliverables/This structure separates working analysis from stakeholder-ready documents. It also lets the team rerun or improve a specific stage without losing the broader context.
Skills
Skills are reusable instruction blocks for a particular type of work. Instead of writing a long prompt every time, a skill captures the repeatable behavior expected from the agent.
For example, a domain discovery skill might tell Codex to inspect:
- Controllers
Get Manish Aganani’s stories in your inbox
Join Medium for free to get updates from this writer.
- Services
- Domain objects
- Event usage
- Database entities
And then produce a structured output with:
- Domain name
- Responsibilities
- Key entities
- Dependencies
- Candidate service boundary
- Risks
A small representative example:
# Domain Discovery Skill
Purpose:
Identify bounded contexts and business domains.
Analyze:
- Controllers
- Services
- Domain objects
- Event usage
- Database entitiesIf multiple applications are assessed, the same skills can drive consistent outputs across codebases.
Prompts
The workflow used prompt chaining. Each prompt produced one artifact, and later prompts used earlier outputs as inputs.
The sequence followed a natural architecture discovery flow:
-> Solution Structure
-> Domain Discovery
-> Dependency Map
-> Service Candidates
-> Risks and Assumptions
-> Executive Summary
-> BRD
-> HLD
-> Test Strategy
-> Estimates
-> Migration PlanThis entire process is cumulative. A good HLD depends on the domain inventory and dependency map. A migration plan depends on service candidates, risks, assumptions, and complexity. A test strategy depends on the workflows and integration points discovered earlier.
AI-Driven Discovery Workflow
Rather than asking Codex to generate a BRD or HLD immediately, I broke the exercise into a series of smaller discovery activities.
The workflow started with repository analysis to understand the solution structure, project relationships, dependencies, and major functional areas. Once the application structure was clear, the next step was identifying business domains and potential bounded contexts.
From there, Codex generated dependency maps, service extraction candidates, and migration risks. These intermediate artifacts provided the context needed to evaluate service boundaries and migration complexity before making architectural decisions.
Finally, the accumulated analysis was used to generate stakeholder-facing deliverables, including risks and assumptions, a BRD, HLD, test strategy, revised estimates, and a migration plan.
The key takeaway is that Codex was not asked to produce the final documents in a single prompt. Instead, the output of each step became input to the next, creating a structured discovery workflow similar to how an architect would approach a real modernization project.
A Note on Usage Limits
Repository analysis can consume a significant number of tokens, especially when working with large solutions and multi-step workflows. During this exercise, Codex displayed a warning when the weekly usage limit was nearly exhausted. You can monitor your consumption at any time using the /status command.
For larger repositories or extensive documentation generation, keep an eye on usage to avoid interruptions.
Deliverables Produced
To keep the workflow organized and easy to review, I separated the generated outputs into two categories:
- Analysis — Intermediate artifacts used during discovery, such as repository analysis, domain identification, dependency mapping, service candidates, risks, and assumptions.
- Deliverables — Stakeholder-facing documents generated from the analysis, including the Executive Summary, BRD, HLD, Test Strategy, Revised Estimates, and Migration Plan.
The key deliverables generated during this exercise were:
- Executive Summary — High-level findings and modernization recommendations.
- Risks and Assumptions — Migration risks, unknowns, and validation items.
- Business Requirements Document (BRD) — Business objectives, scope, requirements, and success criteria.
- High-Level Design (HLD) — Current-state architecture, target architecture, service boundaries, and migration approach.
- Test Strategy — Validation approach for functional, integration, performance, and migration testing.
- Revised Estimates — Effort estimates based on complexity and migration phases.
- Migration Plan — A phased roadmap for incremental modernization.
Observations and Benefits
The biggest advantage of this approach is speed. Instead of starting with a blank page, architects begin with a repository-backed first draft that can be reviewed and refined.
It also improves onboarding. New team members can understand the application’s domains, dependencies, risks, and architecture before diving into thousands of lines of source code.
Finally, the process is repeatable. Once the skills and prompts are organized, the same workflow can be applied to other repositories, making it particularly useful for organizations managing multiple legacy applications with limited or outdated documentation.
Limitations and Human Review
Like any AI-generated output, the results should be treated as a starting point, not a final answer.
Codex can analyze repository structure, dependencies, and implementation patterns, but it has no knowledge of production traffic, business priorities, operational constraints, compliance requirements, or organizational context unless that information is explicitly provided.
The generated artifacts should always be reviewed and validated by architects, technical leads, and domain experts before decisions are made.
The goal is not to replace discovery. The goal is to make discovery faster, more consistent, and less dependent on starting from a blank page.
Conclusion
In this experiment, Codex CLI was used to analyze a real repository and generate a structured set of discovery and design artifacts, including domain analysis, dependency mapping, risks and assumptions, a BRD, HLD, test strategy, estimates, and a migration plan.
By breaking discovery into a series of focused analysis steps and chaining the outputs together, teams can accelerate documentation recovery, architectural assessment, and migration planning for existing applications.
Architects still make the decisions. Codex simply helps them get to those decisions faster.
Repository and Prompt References
- Project Repository (nopCommerce): nopCommerce GitHub Repository
- Assessment Repository and Prompt Workflow: GitHub Fork and Codex Artifacts
For this experiment, nopCommerce was selected as the sample application because it is a mature, open-source .NET e-commerce platform with a sufficiently large and realistic codebase for demonstrating discovery and modernization workflows.
