Architecture Discussions and Technical Documentation with AI

Beyond code generation, AI provides significant value in the higher-level activities of software development: designing systems and documenting them.

Using AI as an Architecture Thinking Partner

AI is a useful sounding board for architectural decisions, particularly when you do not have immediate access to a senior colleague.

Presenting a design for critique > "I am designing a notification system for a multi-tenant SaaS application. My plan is to: [describe your plan]. What are the main risks or weaknesses in this approach? What have I not considered?"

Exploring trade-offs > "I need to choose between approach A and approach B for [PROBLEM]. Here is my current thinking: [EXPLAIN]. What are the trade-offs I should consider? Which would you recommend for a system that prioritises [YOUR PRIORITIES]?"

Pattern identification > "I have this problem: [DESCRIBE]. What design patterns or architectural approaches are typically used to solve this? Give me a brief description of each and when it is appropriate."

Scaling considerations > "This system currently handles 1,000 users. How would the architecture need to change to support 1 million users? What are the bottlenecks in the current design?"

What to Expect from AI Architecture Advice

• AI architectural advice is a starting point, not a final answer. It:
• Knows about established patterns and common solutions
• Can identify obvious problems you may have missed
• Cannot know your specific constraints, team capabilities, or business requirements
• May suggest over-engineered solutions for simple problems
• May suggest simple solutions for genuinely complex problems

Use it as one input, not the only input.

Technical Documentation with AI

Documentation is a known weak point in most development practices. AI makes the pain lower.

README generation > "Write a README for this project. Include: a brief description of what it does, installation instructions based on this package.json: [PASTE], a usage example, and how to contribute."

API documentation > "Write documentation for this API endpoint in OpenAPI format: [PASTE ENDPOINT CODE]"

Code comments > "Add comments to this function explaining what each section does and why any non-obvious choices were made: [PASTE CODE]"

Architecture Decision Records (ADRs) > "Write an ADR documenting the decision to use [TECHNOLOGY/PATTERN]. Include: context, decision, and consequences. Here is the relevant context: [DESCRIBE]"

The Documentation Habit

The most effective pattern: write documentation immediately after writing code, with AI assistance. The code is fresh in your mind; AI handles the formatting and structure.

Waiting until later means the context is gone and documentation never gets written. With AI, the friction is low enough to do it while the code is fresh.