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.
Intrigued enough to set aside my skepticism, I decided to experiment with 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'
I actually used Anthropic Claude instead of Gemini (which required an additional plugin), but maintained the same prompt structure.
The results were genuinely impressive. The AI generated a clear, well-organized description of the project's functionality, structure, and command-line arguments (it was a CLI tool). Perhaps most impressive were the thoughtful suggestions for potential improvements to the codebase—insights I might have overlooked despite my familiarity with the project.
Practical Applications
This approach offers several practical benefits for development teams:
- Onboarding acceleration: New team members can quickly understand project architecture without lengthy explanation sessions
- Documentation maintenance: Generate up-to-date documentation that can be kept in sync with your codebase by repeating the described procedure
- Technical debt identification: The AI often spots inconsistencies or potential improvements that might otherwise go unnoticed
- Knowledge preservation: Capture institutional knowledge about a codebase before key team members depart
Limitations and Considerations
I recognize this technique isn't universally applicable. 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've come to view this AI-powered documentation approach as a valuable addition to a developer's toolkit. In combination with architecting, modeling and developing applications with our Cloud Solutions Workbench (which also provides AI powered assistance for certain tasks) this could be beneficial - especially for cases where you have to integrate older codebases into new application initiatives.
As AI tools continue to evolve, finding practical, focused applications like this—where they genuinely enhance human productivity rather than attempt to replace human judgment—represents the sweet spot for AI adoption in software development.
Have you experimented with AI for documentation or code analysis? I'd be interested to hear about your experiences in the comments.
