Develop Phase Documentation
What Happens in This Phase
The Develop phase is where architectural decisions are made and code is written. Documentation here captures design rationale, API contracts, and coding standards. AI can generate API documentation and standard templates while humans focus on architectural decisions that require domain expertise and security judgment.
Where AI Helps
- Generating API documentation from code annotations and OpenAPI specs
- Drafting Architecture Decision Records (ADRs) with consistent structure
- Creating design rationale documentation from meeting notes and discussions
- Maintaining coding standards documentation aligned with DoW baselines
- Identifying undocumented interfaces through code analysis
Example: Architecture Decision Record
This example demonstrates GenAI Augmentation—AI structures the document while humans own the architectural decision and provide the technical context that makes the ADR valuable.
Context Setup
Before prompting, the architect provided:
- The architectural decision (event-driven with Kafka)
- Performance requirements (10,000+ concurrent updates, sub-second latency)
- Alternatives evaluated (request-response, polling, event-driven)
- Reasons for rejecting alternatives
- Team's ADR template
Prompt
"Generate an Architecture Decision Record for our choice to use event-driven architecture for the logistics tracking system. Context: We need to handle 10,000+ concurrent shipment updates with sub-second latency. We considered request-response, polling, and event-driven approaches. Document the decision, rationale, and consequences using the standard ADR format."
Output
# ADR-007: Event-Driven Architecture for Logistics Tracking
## Status
Accepted
## Context
The logistics tracking system must handle 10,000+ concurrent shipment updates
with sub-second latency. The system integrates with multiple carrier APIs and
must notify downstream systems of status changes in near real-time.
## Decision
We will use an event-driven architecture with Apache Kafka as the message broker.
## Rationale
- Request-response: Would require polling, increasing latency and load
- Polling: Inefficient for high-volume, low-latency requirements
- Event-driven: Enables push-based updates, horizontal scaling, and decoupling
## Consequences
- Teams must learn event-driven patterns and Kafka operations
- Need robust dead-letter queue handling for failed events
- Enables future integration without modifying core services
What AI-Generated Develop Documentation Often Misses
- Alternatives actually considered - AI may invent options that weren't evaluated
- Organizational constraints - Team skills, timeline pressure, existing infrastructure
- Security architecture implications - Data flow, trust boundaries, encryption requirements
- Integration complexity - Real-world dependencies and failure modes
- Why alternatives were rejected - Specific technical or mission reasons
Human reviewers must validate that ADRs reflect actual decisions and constraints.
Governance Checklist
Before accepting AI-assisted Develop phase documentation:
- [ ] ADRs reflect decisions actually made by the team
- [ ] API documentation matches implemented behavior
- [ ] Security implications documented and reviewed
- [ ] Design rationale traceable to requirements
- [ ] Coding standards align with DoW/organizational baselines
Brownfield Additions
For modernization efforts, Develop phase requires additional focus:
- Reverse-engineered architecture documentation - AI analyzes legacy code to generate initial architecture views; architects validate accuracy
- Integration point documentation - Catalog interfaces between legacy and modern components
- Technical debt inventory - AI identifies patterns; humans prioritize remediation