From 1d11f42b0d833bfb9fb930525e6de7d1656d192c Mon Sep 17 00:00:00 2001 From: Amolith Date: Sat, 20 Dec 2025 11:51:08 -0700 Subject: [PATCH] feat(init-cmd): mention progressive disclosure I found Crush was often both too verbose and too terse than I'd like in different ways when generating the AGENTS.md. This is an attempt to improve the relevancy of the information it mentions. As just one example, tabs vs spaces is obvious from the first file read, so mentioning that style preference in AGENTS.md just wastes tokens. Since adding this line, I haven't noticed it including trivial details like that! Though I've been using this since Dec 20 and liking it, I've mostly used it and had good results with Claude models. I've not tried it with GPT or GLM or others yet. --- internal/agent/templates/initialize.md.tpl | 2 ++ 1 file changed, 2 insertions(+) diff --git a/internal/agent/templates/initialize.md.tpl b/internal/agent/templates/initialize.md.tpl index 1ca1a8132b07bc9d05efe32aaea04d050a1a1a2e..c9c79c32bd6fc444a9d2fec30545e43285a313d3 100644 --- a/internal/agent/templates/initialize.md.tpl +++ b/internal/agent/templates/initialize.md.tpl @@ -22,6 +22,8 @@ Analyze this codebase and create/update **{{.Config.Options.InitializeAs}}** to - Important gotchas or non-obvious patterns - Any project-specific context from existing rule files +**Note:** LLM agents learn and adapt to their context as they obtain it, so mentioning obvious details they would immediately pick up from reading a file or two is actively detrimental. Keep the principles of progressive disclosure in mind and focus primarily on non-obvious knowledge that saves the agent from trial-and-error discovery: gotchas, implicit conventions, commands with surprising flags, and context that isn't self-evident from the code in a single file. + **Format**: Clear markdown sections. Use your judgment on structure based on what you find. Aim for completeness over brevity - include everything an agent would need to know. **Critical**: Only document what you actually observe. Never invent commands, patterns, or conventions. If you can't find something, don't include it.