Replies: 1 comment 1 reply
|
This is really helpful. Thanks much for taking the time to write this up! |
4 and 5. If we aren't going to keep the Brief, the PRD, or the original epics and stories for context, then what was the point. Maybe I need to conceptualize the PRD, brief, epics and stories as things that get converted into codebase and documentation files bit by bit, and therefore once a section of the PRD or Brief, or a story, once that part is converted into are converted into code and documents, the PRD and Brief and stories from which it was derived should be erased. However, my concern is that erasing these parts will lead to regression errors in the future. |
Uh oh!
There was an error while loading. Please reload this page.
I have been thinking a lot more about how I work in large brownfield enterprise, or work on a large project I am building that is well past post MVP - and there are a few things I realized I do that I have not clearly shared - and will be in my next video. This is all very opinionated but I find that it helps and works well for me. Would love to hear your thoughts also - this is meant to be a discussion and not my way is the only or even the best - so please share your tips also!
This discussion got me thinking about it some more after my last response a few days ago - so thank you @Shoot2Skoot and @DanielFerreiraJorge for the great conversation!
When I work in enterprise brownfield (large existing apps that have been worked on for a long time maybe even by other teams years ago) or in my own personal post MVP large projects - the biggest contributor to having success with the Agent mode comes down to context and model choice at the end of the day. What does that mean practically - here are some tips:
The artifacts you use to build an MVP or add a feature that are in the docs folder (or ai folder if following older method) are not good for LLM long term artifacts - SOME of them are, some need some rework, and some are potentially detrimental to the LLM.
Refactoring between every epic, or every story, or at a minimum after your current scope of PRD work is complete is VERY helpful - make sure to keep your docs up to date either manually or with LLM assistance.
OK - so - on point number 1. You might have if you followed this - a large Architecture document, a PRD, maybe your brainstorm doc, the stories the devs actually worked from. You also might have all the smaller sliced up documents from the prd and architecture. This is a lot of content - and if you app build is of even a little bit of complexity - there are going to be change logs, things that changed or were overlooked when working on a story, notes from the llm where it made mistakes and you had it record now it fix and proceeded - maybe some refactoring you did or had the LLM do, etc...
In industry on large teams, before kicking off any effort the artifacts we build in this process of the BMAD method are very aligned with how agile takes on large efforts (with a million variations, with some very opposed to this way of working) - but there is ONE key thing - there artifacts are a snapshot in time of ideation.
Once its all build implemented and working providing real world value - those documents are interesting for analytics and history - but they are a TERRIBLE reference of the current state of reality or usage guidance or even future dev guidance - because the only thing constant is change.
So - practically - 2 pieces of advice:
1 - clean up your docs folder, rules, agent instructions to be living documents of what is needed for the agent, get rid or archive the rest - or put it in a folder the LLM will not index or read from.
2 - the docs that remain need to be lean and useful without extra bloat - a source tree is super useful long term, but make sure the tree remains accurate if refactoring or if things diverged - or else it can make things worse in the future. The source tree seems to just generally be one of the most powerful artifacts for most llm models in coding in brown field.
3 - if you are working in a really old brownfield with bad standards and practices - the more you can do to improve or refactor the legacy code to consistent ways of doing things with consistent patterns - the less cognitive overhead there is for the LLM.
4 - While I suggest getting rid (out of context) the prd, brief, stories the dev used, architecture document - that does not mean all the info should go. Keep the fragments that are useful and have that be your docs folder. These sort of become the rules for the LLM to be able to work in your project - without the need to know the vast history.
5 - if you are going to work on a sizable effort and want to do another round - depending on the change - you may not need a full blown PRD or architecture. I would recommend a simple prd and start with telling the agent about your existing project, the current directory structure and architecture patterns libraries and practices that are already in place from the docs you have retained, and explained your new idea for the new post mvp Epic. When you hand off the to the architect if necessary - similar initial guidance.
Instead of building full blown architecture - explain to the architect your goal is to update existing fragment artifacts or add new ones if needed. (Source tree, api guidance, new schemas, existing code files to modify that will work into the new goals, etc...)
And when you do work on the final story - its really important to make clear in the story how the agent should work within this what is now an AI brownfield project - it gets more challenging as the project grows - but this is where you need to help and have some understanding of your own projects structure and best practices to really help guide the LLM.
Also - regardless of the IDE or LLM you are using - I think this really applies to all as some decent advice from Cursor team.
All reactions