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 growing consensus that prompts should be versioned, best practices for doing so have not yet been developed.

I'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 come from a client call in a B2B use case or from user interviews in a B2C use case. A human edits notes/context so that the AI can have this context in the future.
2. The new information leads us to a new feature. The feature is complex, so we use an AI to perform the research. A dedicated research agent compiles it and adds it to notes/research with a human reviewing before committing.
3. Engineers and PMs discuss the research and business context, and settle on an implementation, which is written by a dedicated 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 that 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/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/research	Pure research gathering facts and best practices from documentation and the internet. Helps us audit LLM reasoning.	Facts generally change slowly so there is little need to update. They are generally only useful for a short period as their insights eventually get baked into the code.
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 filenames should have a date-stamp 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!