Improving Collaboration and Documentation in Software Development with AI

From Skeptic to Advocate: How AI transforms Software Documentation and Architectural Insight

As a self-proclaimed AI skeptic in our company, I recently had my assumptions challenged after reading an insightful blog post by Simon Willison (who consistently delivers excellent content on AI technologies). In this post, Willison demonstrates a remarkably efficient method for analyzing software projects when you have access to the source code. The procedure generates a comprehensive document outlining the architecture, structure, and inner workings of a given project. I highly recommend checking out his GitHub gist monolith.md to see the impressive results firsthand.

Curious and slightly humbled, I decided to put my skepticism to the test. I applied Simon’s approach to one of our company’s smaller projects (which I unfortunately cannot share publicly). Following Simon's approach, I installed his utilities files-to-prompt and llm, navigated to my project's git repository, and executed a command similar to what Simon demonstrated:

files-to-prompt . -c | llm -m gemini-2.0-pro-exp-02-05 -s 'architectural overview as markdown'

In my case, I swapped Gemini for Anthropic Claude, which required an additional plugin, but I kept the same general prompt.

The results were nothing short of impressive. The AI generated a clear, logically structured description of the project’s functionality, internal modules, and command-line arguments (it’s a CLI tool). Even more surprising were the context-aware recommendations for code improvements -suggestions that I, despite being deeply familiar with the project, might have overlooked.

Practical Applications

This AI-assisted documentation workflow provides value for engineering teams of all sizes:

• Onboarding acceleration: New developers can quickly grasp a project’s architecture without lengthy walkthroughs.

• Automated documentation maintenance: Regenerate accurate, up-to-date technical documentation in minutes, synchronized with your latest codebase.

• Technical debt discovery: LLMs often spot inconsistencies, redundant code, or subtle design flaws that might otherwise stay hidden.

• Knowledge preservation: Capture critical architectural context before key contributors move on, ensuring continuity and resilience.

AI and Architecture Decision Records (ADRs)

One area where AI shows exceptional promise is in documenting and validating Architecture Decision Records (ADRs). These short, structured documents capture key architectural choices and their rationale. Yet they’re often incomplete, inconsistent or outdated in real-world projects.

AI can meaningfully change that:

• Automated generation: Based on code analysis and commit history, an AI model can suggest initial ADRs, summarizing architectural patterns and inferred design decisions.

• Cross-validation: When developers update the code, AI can flag inconsistencies between new implementations and existing ADRs ensuring that documentation reflects reality.

• Context enrichment: By correlating ADRs with related modules, dependencies, and tests, AI can create a richer picture of architectural intent and its implications.

• Continuous evolution: Running periodic “AI-assisted ADR reviews” keeps decisions transparent, traceable and up to date, even as systems evolve.

In short, AI can transform ADRs from static documents into living architectural assets: validated, traceable and dynamically maintained alongside the code.

Limitations and Considerations

For optimal results, the entire codebase should fit within the LLM's context window - a challenge for many enterprise-scale projects. However, with the growing adoption of microservice architectures, this limitation becomes less problematic as individual services are more focused and compact.

Additionally, the quality of the output depends significantly on code readability, commenting practices, and overall project organization. Well-structured projects yield more accurate analyses.

Final Thoughts

Despite my initial skepticism, I now view AI-powered documentation and architecture analysis as a powerful complement to human expertise, not a replacement for it. Combined with our Cloud Solutions Workbench, which already integrates AI assistance for modeling and development tasks, this approach provides a robust foundation for modern software engineering—particularly when integrating legacy codebases into new application ecosystems.

As AI tools continue to mature, their role in augmenting human creativity, discipline, and insight becomes increasingly clear. The sweet spot lies in using AI to handle repetitive, analytical, and documentation-heavy work—freeing developers to focus on design decisions, innovation, and craftsmanship.

Have you experimented with AI for documentation, ADRs, or code analysis? I’d love to hear how it’s reshaping your development process.