Feature Ledger
person concept tool org talk claim — click a node to jump to its page; hover an arrow for the relation
A Feature Ledger is a markdown file maintained by an AI agent during long-running development work, used to log decisions, actions taken, and features implemented as they occur — serving as a running record of agent activity and context.
Concept and Purpose
The Feature Ledger emerged as an approach to giving agents persistent memory across a "messy forever" workspace. As described in To Give an Agent a Workspace: Laying a Foundation for Messy Forever Work, the core idea is straightforward: as an agent does its work, it maintains a markdown file and appends entries like "we did this, we made this decision." 7:46
It is framed as an alternative to Ticket-based workflows — rather than structured task management, it is a freeform, append-oriented log.
Criticisms and Scaling Failures
The Feature Ledger concept is subject to significant criticism, primarily from Alex Damis, who introduced it but subsequently found it unworkable at scale:
Scaling failure with file size: Damis found that the Feature Ledger "did not scale" as tasks grew larger. The log grew to 4,000–8,000 lines, at which point "the agent just could not make sense of it." The format that works for small tasks collapses when a project runs long enough to accumulate substantial history. 8:45
Codebase contamination: A separate criticism targets the practice of storing Feature Ledgers (and similar working documents such as plan MDs) directly inside the codebase. This is characterized as "getting sloppy," carrying the risk of accidentally shipping these intermittent artifacts as part of a release. 39:58
Points of Disagreement
There is no recorded advocacy for the Feature Ledger as a mature, production-ready pattern. The evidence presents it primarily as an early, intuitive approach that its own originator critiques. The tension is between:
- Initial appeal: Simple, low-friction logging that gives an agent a running narrative of its own work.
- Practical limits: Both the cognitive load on the agent (context window / comprehension of massive files) and the operational risk (codebase pollution) make it unsuitable for large or long-running tasks, pointing toward more structured alternatives such as Ticket-based systems or externalized storage.