Context
I’m evaluating BMAD Method for serious enterprise software development and for the most part I like the structured approach it offers. I consider it a huge step up compared to simple vibe coding.
I’m building a career management system that replaced dozens of scattered excel files with BMAD so I have a decent handle of the workflows, agents, etc.
Initial Technical Docs
I started with a new greenfield project and I honestly like the thorough documentation it generated. I sharded the architecture.md into different files in the docs/ folder. Then I jumped to using the agents to bootstrap the project, which did a good job overall.
I was very in love when I opened Cursor and went to my docs/ folder and saw all a lot of details about my project documented.
Then scope changed
Then when significant progress had already been made, it happen what happens to ALL projects in real life: scope creep and/or scope change. BMAD offers something like a correct-course workflow so that you can handle this situation. Even though the execution of that workflow was not deterministic in the 4-5 times I did it, overall it did let me focus on a different user story so I did not complain.
Some of that changes in scope caused technical decisions to be made that affected the initial architecture defined by BMAD.
HOWEVER, as this happened more frequently, I realized the docs were not kept up to date. I don’t know if this should have been managed by BMAD or by me. IMHO, this is the type of task that should be offloaded from humans because we already failed at keeping documentation up to date in real-life projects with no AI involved, so in this case I think the BMAD method has an opportunity there.
After several weeks now, I am convinced that BMAD’s approach to technical documentation is not exactly agile. All the docs that I loved to see in the docs folder of Cursor, now I feel repelled by them. Most of them are out of date and since there are too many, I don’t even know where to start.
Context Engineering for Architecture
BMAD is all about context engineering, and that’s why Kiro attracted me when I learned about it. I liked their simple approach to documenting features which I already wrote about on [[Initial impressions of Kiro]] and [[Kiro spec-driven development is better for large features]]. Also the best practices of Claude Code’s memory management tell you to optimize your context.
Also, when I think about software architecture I immediately remember the book Software Architecture for Developers by Simon Brown which tells you that the architecture represents the important technical decisions that are hard to change later, and I tend to agree with that. Therefore the level of detail generated by the BMAD method for the architectural documents is just too much, too waterfall-ish regardless if I failed at keeping them up to date.
The question is, what is the right-sized context engineering that should be made available to the context immediately? Don’t have an answer yet.