Long Term Feature Management for Large/Complex Projects

[K3TH3R]

I've been really impressed so far with the way Beads has allowed Claude Code to be proactive both about sourcing information it is unsure of as well as capturing issues automatically. I've been building a custom workflow around using CC to build planning docs and then sharding those into beads issues before beginning work.

But this has also left me with a curious thought. There are potentially thousands of decisions, business rules, and user stories that go into a real product. Realistically, there are thousands of decisions/features that can go into just your design system for a product, let alone the actual features you build with it. Even if you had many of these details captured in epics/issues, you likely won't be able to preserve those details long-term as your database grows and you need to cull issues. Or the agents may not know where to lookup specific information or details. I've had to constantly remind agents, for example, that we're working on Tailwind V4 and not V3 even though the version is already specified in my package.json. Or it gets confused because my React Native app still has to use V3 Tailwind while my main web app was already built on V4.

Some of these things can be mitigated by focused diligence on maintaining the AGENTS.md or CLAUDE.md, but as we start to move into agentic colonies of workers, these files become less realistic to maintain because the Claude SDK for example won't read the CLAUDE.md file if you don't manually inject it as part of your system/user prompt.

What I'm thinking here is that maybe we need to think about adding some more tables or types? I'm still trying to figure out the language/functionality, but it seems to me that we could potentially have a "decision" type that works similar to issues, but would be oriented around capturing permanent details.

For example, let's say I have an "Epic" to implement a RBAC for my saas app, there will be a ton of details in the issues often with a lot of code examples and implementation details that aren't relevant after the epic is completed. However, I would still likely want to be able to document

1. Technology Stack: Auth provider (ie. Clerk, WorkOS)
2. Business Rule: (User must have a Org Role with an Org to view Projects, Orgs can have multiple Projects, User must have a Project Role to view Project Details, etc.)
3. User Stories
4. Monorepo: Technology Selection within apps/libs (ie. you may need different technology choices for different apps in a monorepo) or service coordination and relationships between your different apps

These are all essential details that won't necessarily exist clearly just from looking at the code. Or we often make these decisions in the moment as we're planning work but they don't get captured accurately as part of the plan definition because they're interspersed with other implementation details. We reuse this same JSONL/SQLite setup but with a new item/tables. If this is what we do for a complex project:

Epic → features → stories → tasks (complex projects)

Then I think we would have something like this as the outcome once an epic is implemented:

Feature Definition
 → Business Rules 
 → User Stories 
 → Decisions

Although, stuff like business rules and user stories could potentially be defined ahead of time as well prior to starting on the implementation/epic. Either way, this is a very rough implementation example based on the existing beads api:

# Create feature definition (generates hash ID automatically)
bd define "RBAC Auth System" -t definition -p 1
# Returns: bd-a3f8e9

# Create business rules
bd define "User must have an Org Role to view Org Details" -t rule      # Auto-assigned: bd-a3f8e9.1
bd define "Organisations can have multiple projects" -t rule    # Auto-assigned: bd-a3f8e9.2

# Store a technology decision
bd define "WorkOS is used for authentication with a custom AuthKit integration" -t technology    # Auto-assigned: bd-a3f8e9.3

# Create a user story
bd define "As a member of an organisation, I must have an Organisation Role in order to access the Organisation Detail page" -t story    # Auto-assigned: bd-a3f8e9.4

The idea here is that some things could be defined up front, but we'd could also parse the issues from a complex project/epic being finished to create a final "definition" of the feature once it's complete that captures the essential details. We can link the definition to the epic to be able to traverse in both directions. This would allow us to also capture individual details about the feature (ie. which routes the feature is found on/in) that would streamline the lookup process for agents. This also means we can then re-use this information in the future easily to plan new features, design revisions, create tests/e2e tests, or help plan fixes.

This may, obviously, simply be a custom extension that I have to build for myself, but it seemed worthwhile enough to open up a thread for discussion on. My biggest gripe with the AI Agents has been how many times I've had to remind them about details that aren't clear or obvious from the code. I think this would help build the other half of the agentic information loop that captures the essential details that get lost in the mix after the initial work is complete.

[mrsimpson]

@K3TH3R I wrote about my approach to long term and process memory in this thread