{
  "markdown": "# prompt-comments\n\nStops `AGENTS.md` / `CLAUDE.md` from growing without bound.\n\nAdding an instruction is cheap. Deleting it is a guess once nobody remembers\nwhy it exists. This package makes the *agent* write the why at add time, even\nwhen the user never mentioned the file.\n\nBased on Chakrabarti, [*Why Does CLAUDE.md Keep Growing?*](https://arxiv.org/abs/2608.11095)\n(arXiv:2608.11095).\n\n## Why these files grow\n\nAcross 1,867 public repos and 247k instruction lifetimes, agent READMEs\n(`AGENTS.md`, `CLAUDE.md`, `copilot-instructions.md`) more than triple\nover their life (+226%). Median file ends at 39 instructions. Net +4.9\ninstructions per commit. Deletion gets *less* likely as a rule ages\n(log-hazard −0.032/commit) and as more authors touch the file.\n\nThat is not staleness (old rules would die more) and not only fragile\ncontent dying young. The instruction stays; the *why* decays. The paper\ncalls this **catastrophic remembering**. Adding is always cheap.\nDeleting without the original rationale is a guess — a safe audit is\nexponential in prompt size; writing the why at add time is O(1).\n\n~77% of instruction deaths are wholesale rewrites. Size drops, then\ngrowth resumes faster (4.1% → 4.9% per commit). A clean file with no\ncomments refills. Stronger models make this worse: they add more\ninsurance rules.\n\nComments that work name the failure, a hypothesis, and the **outcome**\n(plus how often it recurred). Comment-shaped noise does nothing. A\nstory with no outcome is worse than no comment.\n\n![Excess prompt size over 51 maintenance steps: no comments and comment-shaped noise grow past +200%; comments with latent reasoning stay near the optimal size.](assets/excess-size.png)\n\n*From Chakrabarti, Fig. 1(a). Uncommented prompts ratchet; informative comments settle near the minimum cover. Lab covers were 2–3 instructions, not the real median of 39 — direction holds, the % is not a target.*\n\nDo not auto-delete from a recovered why — their protocol emptied about\n1 prompt in 8, and the uncommented arm scored higher on those worlds.\nKeep a human in the deletion path.\n\n## How a user uses this\n\nThey install it. Then they keep working. They do not invoke a slash command\nand they do not ask the agent to update instructions.\n\nAgents already add rules to `AGENTS.md` / `CLAUDE.md` as a side effect of\nnormal work. After install:\n\n1. **Skill description** tells the agent to load this protocol whenever *it*\n   edits those files, not only when the user names them.\n2. **Write-time hook** (Claude Code / Codex plugin) intercepts `Write`/`Edit`\n   of those files and blocks new instructions that lack `failed` / `outcome` /\n   `recurred` comments. Existing uncommented files stay editable.\n3. **Prime extension** does the same on `edit` / `ipython` / `bash`.\n4. **`AGENTS.md` fallback** for hosts that only inject a context file\n   (Gemini CLI and others).\n\n## Install\n\n### skills.sh (70+ agents)\n\n```sh\nnpx skills add vladzima/prompt-comments -g --all\n```\n\nThat installs the skill. For write-time blocking in Claude Code, also:\n\n```sh\nclaude plugin marketplace add vladzima/prompt-comments\nclaude plugin install prompt-comments@prompt-comments\n```\n\n### Prime Agent\n\nPrime already loads `~/.agents/skills/`, so the skills.sh install above is\nthe skill. The Prime package is **extension-only** (the write-time gate).\nDo not expect it to ship a second `SKILL.md`; that collides with the\nskills.sh copy.\n\n```sh\nnpx skills add vladzima/prompt-comments -g --all\nprime-agent package install https://github.com/vladzima/prompt-comments\n```\n\n### Manual\n\n```sh\ngit clone https://github.com/vladzima/prompt-comments.git\n```\n\nThen copy `skills/prompt-comments` into your agent's skills dir.\n\n## What the agent writes\n\n```md\nUse bun, not npm.\n# failed: npm install rewrote the lockfile and broke CI (2026-03-12)\n# try: bun matches CI\n# outcome: lockfile stable after switch\n# recurred: 2\n```\n\nNo named failure → do not add the rule. No outcome → do not add the comment.\nDeletes stay manual. Wholesale rewrites must port comments.\n\n## License\n\nMIT.\n",
  "bytes": 4051,
  "sha": "207fd8405f612f4cac0da47399256530b9b0b03ea86c2eef655ac851dc0c7772",
  "repo_slug": "vladzima/prompt-comments",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_vladzima_prompt_comments_19542578/readme"
}