Managing Prompts in a Git Repo

As the software development life cycle becomes more about prompting and less about coding, organizing and storing prompt data has become increasingly important. At Global Underdog, we’ve been storing them under the notes/ folder. However, we have found that the notes folder is getting unruly. While there is a growing concensus that prompts should be versioned, best practices for doing this have not really been developed. We've found there are multiple types of notes that we need and they have different lifecycles>

Happy Path Flow

1. We get new information about the business context -- this can either be from a client call in a B2B or through user interviews in a B2C use case. A so human edits notes/context so that the AI can have this context in the future.
2. The new information requires a new feature. It is complex, so we use an AI does some research. A dedicated research agent compiles it and adds it to notes/reserach with a human reviewing it before committing.
3. Engineers and PMs discuss the research and the business context and settle on an implementation, which is written by a special implementation agent in notes/implementation. There may be several rounds of review on this (through PRs) before we are satisfied.
4. A PR is generated with new code. Each PR comes with edits to notes/design, the latest design which future tasks can reference. These are kept in sync like code.

Prompt Folders

This is a more detailed explanation of how we manage our prompt folders:

Folder	What it does	How is it maintained
notes/reserach	Pure research gathering facts and best practices from documentation and the internet. Helps us audit LLM reasoning.	Facts generally don’t change so there is no need to update. They are generally only useful for a short period as their insights eventually get baked into the code.
notes/context	A series of notes on the external business use cases. They are clear and short to encourage humans to be the primary editor.	Only maintained by humans and never automatically edited by the AI.
notes/implementation	These are design specs. They are how we determine what needs to be built and give an AI clear instructions for building them. These are reviewed by PRs before being accepted and merged into the code.	It is accepted that implementation notes go out of date quickly. Their names should have date-time to help us gauge their reliability. They can be automatically removed after some time.
notes/design	A series of notes that reflect the current state of the app. These bake in high level design consideration and business context. They help both humans and models understand codebase	Should be in sync with codebase. We use AI agents to keep them updated.

Thoughts on how to manage prompts? Would love to learn more!