DeusData

I capped my coding agent's tool output to save tokens. It used 2.65 times as many. --- title: "I capped my coding agent's tool output to save tokens. It used 2.65 times as many." published: true description: "Claude Code token usage, measured: a 12,000-character cap on tool output took one answer from 267k to 708k billed input tokens. Why, and what 252 runs showed." tags: ai, programming, claude, llm series: Coding agents, measured ai_disclosure_level: some_ai cover_image: raw.githubusercontent.com --- To save tokens, I capped every response from my coding agent's code-graph tool at 12,000 characters. One answer then took 18 turns instead of 7, and the input tokens it was billed for went from 267k to 708k, 2.65 times as many. This post explains why a smaller response used more tokens, and what else I found when I rebuilt the measurement on public repositories: 252 headless Claude Code runs (non-interactive, one question each), every token counted. You'll also get the benchmark's exact command line and a script that shows how much of your own sessions' input comes from the prompt cache. The runner and every raw run, answers included, are in claude-code-token-bench. Why I was cutting tool output I wanted to know whether a code graph makes Claude Code, Anthropic's coding agent, cheaper than plain search. The graph came from codebase-memory-mcp, an open-source MCP server that builds a graph of a repository's symbols and the calls between them. MCP, the Model Context Protocol, is how Claude Code plugs in outside tools. The first measurement went badly for the graph. On five questions, the agent with the graph was billed 2.35 times the input of the agent with grep, 4.26M tokens against 1.81M, and it came out cheaper on only one question. So I looked at what the server sent back. One search hit was 1,342 bytes of JSON, most of it hash vectors, complexity metrics and a list of every identifier in the function's body. The same hit as a grep line was 115 bytes. On top of that, the server's 14 tool definitions rode along in every prompt. I put a thin MCP server of my own in front of it, graph-ask. This wrapper dropped the fields no code question needs, which brought a hit down to 251 bytes. It also capped every response at 12,000 characters: it halved the longest list until the response fit, and noted how much it had cut. !One search hit: 1,342 bytes from the graph server, 251 through my wrapper, 115 as a grep line What the cap did The tool that returns a repository's structure hit the cap. The model got a shortened list with a note saying how much was missing, and asked again. That answer took 18 turns where it had taken 7, and its billed input rose from 267k tokens to 708k. !Billed input for one answer: 267k tokens in 7 turns without the cap, 708k in 18 turns with a 12,000-character cap A turn is one round trip to the model. Each one is a new API request, and it carries the whole conversation: the system prompt, the tool definitions, the question and every tool result so far. Divide the totals by the turns and the average turn comes to about 38,000 tokens before the cap and 39,000 after. The smaller responses didn't make a turn any cheaper. The turn count went up 2.57 times and the tokens 2.65 times, which came to 441k more tokens in all. That is also why a turn costs more the later it comes. Each tool result joins the history that every later turn sends again, so billed input grows faster than the number of turns. One limit on the 2.65: in that round I counted every input token the same, including the ones served from the prompt cache, the unchanged start of the conversation that Anthropic keeps between requests. Anthropic bills those cache reads at a tenth of the input price, so 2.65 is a ratio of tokens, not of dollars. The public benchmark below prices each kind of token at its own rate. What I changed in the wrapper I kept the trimming and rebuilt the rest around the number of turns. One tool call now answers a whole structural question, with a function's definition, source, callers and callees together, so the model doesn't assemble the answer over several turns. A script summarizes each repository's layout once into a file, and the agent reads that file instead of querying the graph. Asked for a project's HTTP routes, the tool returns each handler along with the config files that hold the URL prefixes. And the cap went up to 60,000 characters. Together those changes took that round's questions from 83 turns and 3.46M billed input tokens to 36 turns and 1.62M. Listing a project's HTTP routes alone went from 23 turns to 8. !Billed input for one round of questions: 3.46M tokens in 83 turns for the first wrapper, 1.62M in 36 turns after the rebuild The current version also checks a name before it queries. The graph matches names exactly, so a near miss returns nothing and costs a turn to recover. When the name doesn't exist, the tool takes the top search hit and says it did. The wrapper still labels a cut when a response hits the cap. From server.mjs, shortened: // Bring a response under MAX_CHARS by shortening its longest arrays, halving the // worst offender at a time, and recording what was dropped next to it. Slicing the // serialized JSON instead would hand the model invalid syntax and no idea what is // missing — the truncation has to stay legible, or it reads as a complete answer. const kept = worst.arr.slice(0, Math.max(1, Math.floor(worst.arr.length / 2))); parent[key] = kept; parent[`${key}_truncated`] = `showing ${kept.length} of ${original}`; The 12,000-character version had the same label, and the model went back for the rest anyway. The label stays so that a cut list never passes for the complete answer. Bash and subagents hid more turns The cap wasn't the only thing adding turns in that round. The grep-only setup was allowed Bash and subagents, the helper agents Claude Code can start for a subtask, and the model ran grep | head loop after loop, much of it inside subagents. It was billed 1.8M input tokens. With Bash and subagents denied, the same setup needed 252k. !Grep-only setup: 1.8M billed input tokens with Bash and subagents allowed, 252k with both denied Two things kept this out of sight. Claude Code's turn count covers only the main loop, so a subagent's turns are billed but missing from the count of the run you're watching. And scoped Bash permissions don't match piped commands: a grant for grep alone doesn't cover the pipelines the model writes, so different setups hit different numbers of permission denials. A denial can even look like a saving. In headless mode nobody is there to approve a tool, so an MCP server's tools have to be listed in --allowedTools, or every call is refused while their definitions are still paid for. My very first graph run looked six times cheaper than grep. In that run the graph tools had been refused. For read-only questions the benchmark gave the agent only Read, Grep and Glob, Claude Code's built-in tools for opening a file, searching file contents and finding files by name. Bash was denied, and so was Agent, the tool that starts subagents. For an agent that only has to read code, that's the set I'd start from. The benchmark ran each question like this, from the repository's checkout: claude -p "Which functions or route files call createPaymentIntent? Ignore tests. Give the file:line of each call site, nothing else." \ --output-format stream-json --verbose \ --strict-mcp-config --setting-sources project --no-session-persistence \ --allowedTools Read Grep Glob \ --disallowedTools Bash Agent --strict-mcp-config loads only the MCP servers named on the command line, none here. --setting-sources project skips user-level settings, hooks and plugins, so nothing installed on the machine steers the model. stream-json reports each tool call and the run's token usage, which is what the benchmark recorded. The earlier result didn't survive public repositories That earlier round had also found my wrapper 26% cheaper than grep with Claude Haiku and 18% with Claude Sonnet. But it had given a routing rule, a line in the prompt that says when to use the graph and when to use grep, to every setup, including the one with no graph at all. And its repositories were private, so no one else could check it. I rebuilt the benchmark on public repositories, and that result did not reproduce. The setup: Claude Code 2.1.283 in headless mode with Claude Haiku 4.5 and Claude Sonnet 5. Three small repositories have 1.6k to 5k graph nodes each, where a node is one function, class, file or similar item: FastAPI's full-stack template, ltx-2-mlx (an MLX port of the LTX-2 video model) and avoid-ai-writing (a tool that flags AI writing patterns). One large repository, dub, a link attribution platform, has 25k. The three small repositories share twelve questions, and dub has twelve of its own. In each set, six are about structure, such as who calls a function or the path from an endpoint down to the database write, and six are about exact strings, such as a config value or an error message. Every answer is checked for the facts it must contain. The 252 runs cost $14.69 at API prices. Tokens are priced by kind, with Anthropic's multipliers: fresh input at 1, a cache write at 1.25 and a cache read at 0.1. The setups run in a different order on each repetition, only the setups with a graph get the routing rule, and none of them has Bash or Agent. !Median priced tokens per run for the three setups in three settings, with correct answers as labels Median priced tokens per run, and correct answers: | repositories, model | graph through my wrapper | graph server directly | Read and Grep only | |---|---|---|---| | 3 small, Haiku 4.5 | 30,321 · 28/36 | 43,846 · 32/36 | 31,159 · 33/36 | | dub, Haiku 4.5 | 18,791 · 22/24 | 20,687 · 22/24 | 14,955 · 20/24 | | dub, Sonnet 5 | 17,227 · 22/24 | 23,085 · 22/24 | 13,348 · 22/24 | The graph never beat Read and Grep on tokens. With Sonnet on dub, Read and Grep were cheaper on 11 of the 12 questions at the same accuracy (p = 0.034, a Wilcoxon signed-rank test over per-question medians). My wrapper did beat the bare graph server in all three settings, on 8, 11 and 9 of the 12 questions. The graph's one clear win was accuracy. On dub, Haiku answered the structural questions correctly 12 times out of 12 with it and 8 out of 12 without, at a median of 23.5k tokens against 16.0k on those questions. The most expensive setup was a graph the agent mostly ignored By default, Claude Code 2.1.283 lists an MCP server's tools by name and loads a tool's full definition only when the model asks for it through its ToolSearch tool. In headless mode Haiku mostly didn't ask. On the twelve small-repository questions: | setup | runs that called the graph | correct | median priced tokens | |---|---|---|---| | definitions deferred (the default), routing rule in the prompt | 2/12 | 11/12 | 41,008 | | all definitions loaded, no rule | 4/12 | 9/12 | 62,008 | | all definitions loaded, with the rule | 22/36 | 28/36 | 30,321 | !Median priced tokens: 41,008 with deferred definitions, 62,008 with all loaded and no rule, 30,321 with all loaded and the rule The first two rows are one run per question; the last is the main run, three per question. Setting ENABLE_TOOL_SEARCH=false in the environment makes Claude Code load every definition up front. In six pilot runs with the default, the graph was never called. With that variable set, the same question went through the graph in three turns. Loaded definitions are paid for on every turn, whether anything calls them or not. That is why the mounted graph with no rule cost the most of any setup here. Even with the rule, Sonnet picked the graph in 10 of its 24 runs on dub and Grep for the rest. If you keep an MCP server mounted, load its definitions and tell the agent when to use it. The benchmark passed the rule with --append-system-prompt. Day to day it belongs in CLAUDE.md, the instruction file Claude Code reads at the start of a session: Structure (who calls what, call chains, routes, module layout, a symbol end to end): one graph_ask call. Exact strings, config values, flags, error text: Grep and Read. graph_ask is my wrapper's one-call tool; name your own server's tool there. If you can't say when the agent should use a server, unmount it. A warm cache made later setups look cheaper Back-to-back runs on the same repository share a prompt cache. When the setups ran in a fixed order, the later ones started warm and got a discount the first one never had, which is why the order now rotates. You can see how much the cache does in your own sessions. tools/cache-audit.mjs in the repository reads Claude Code's local session logs, reports what share of billed input came from the cache, overall and per project, and lists the worst sessions: node tools/cache-audit.mjs --days 7 In my earlier benchmark runs, 83 to 88 percent of billed input came from the cache. A much lower share points at something that changes the start of the prompt between turns, like a timestamp in a system prompt or a tool set that shifts. Where a graph does pay A second benchmark ran in GitHub Copilot CLI on two much bigger repositories, kubernetes (146k nodes) and vscode (219k). There the graph cut Haiku's priced tokens on structural questions to 0.29 of grep's, and it was cheaper on 15 of those 16 questions. Sonnet's went to 0.74 and Opus 5.5's to 0.97. The details are in Where a code graph pays off. In Claude Code I haven't tried repositories that large, or Opus. !Graph priced tokens as a share of grep's on structural questions in kubernetes and vscode: 0.29 for Haiku, 0.74 for Sonnet, 0.97 for Opus What these runs can't tell me Every run in this post was a single question in a fresh session. In a long interactive session two things change, and they pull in opposite directions: each extra turn sends a much longer history again, and most of that history is read from the cache at a tenth of the price. So in a long session, does a tight cap on tool output cost more than the 2.65 times I measured here, or less?

You guys asked about my DSV4.1 Flash 1017 + Orca setup. Here's exactly how I'm getting so much done for so cheap. TLDR: I use Orca to orchestrate multiple DSV4.1 flash 1017 agents instead of using an expensive model and the results have been phenomenal. I have 2 setups: 1. Cheapest: DeepSeek V4.1 Flash 1017 orchestrating DeepSeek workers through OpenCode Go ($10/month for $80 of usage). Good for everyday coding, bug fixes, and extending existing apps. 2. Favorite: Claude Opus 5.5 orchestrating DeepSeek V4.1 Flash workers, with Sonnet 5.5 on UI/UX. Good for new features and complex work. I also use obra's Superpowers and Codebase Memory so agents understand the codebase, plan properly, and verify their work. --- A few days ago I posted about how much I was loving DeepSeek V4.1 Flash 1017 and mentioned I was using it as a worker in Orca. I didn't expect that post to get so much attention and I see a lot of you asked how I set things up, what Orca actually does, and what it costs. So I thought I would write about it in detail and give you the prompt I use and the setup I use as well. So here are the two setups I've been using. Both have worked well for me. For context: I've been vibe coding since 2024 (was a coder before too), made over 4300 commits on GitHub in the last year (up from an average of around 500 commits a year, and built several apps and tools that got me to a comfortable five-figure MRR. I'm not sharing links because I'm not here to promote anything. I just think this setup has made a big difference in how much I can build and how fast. So I think it is worth it for any vibecoder who is building apps for clients and is expecting to make money out of it. What is Orca? This is a question that many people asked me in my previous post. Orca is a coding agent that lets you connect Claude Code, Codex, OpenCode, and others, and have one agent orchestrate the rest. Opus can plan and supervise while DeepSeek workers do the actual coding. I find this more efficient than having one expensive model do everything. Orca also handles task delegation, monitoring, and worker lifecycle, which saves headache when running multiple agents. You can know more about it here - onorca.dev (not affiliated at all) Now here's my setup there. I first connect my claude code and opencode there (orca natively supports it there) and then use one of the 2 setups for most of my task - Setup 1: Cheapest setup DeepSeek v4.1 Flash 1017 from the official DeepSeek API orchestrating DeepSeek v4.1 Flash 1017 workers from OpenCode Go (No Claude involved) Ridiculously cheap and works well when building on top of an existing codebase. Orchestrator: DeepSeek V4.1 Flash 1017 through the official DeepSeek API. Workers: DeepSeek V4.1 Flash through OpenCode Go. OpenCode Go costs $10/month and gives $80 worth of DeepSeek V4.1 Flash usage. That's 8x the subscription price in usage value, which is a lot considering how capable the model is. The orchestrator runs on the DeepSeek API, so that costs very little too. I use this for bug fixes, integrations, backend changes, refactoring, and general work on existing codebases. Prompt I give my DeepSeek orchestrator: >Act strictly as the orchestrator and don't write any implementation code yourself. Use Orca's orchestration skill to delegate all coding work to workers. Always use the opencode agent, never opencode2, and don't specify any --model or --effort flags. Let OpenCode use its configured default model, but first verify that it's running opencode-go/deepseek-v4.1-flash with maximum reasoning effort. If the model doesn't match, stop and tell me instead of switching to something else. Use Orca's native Run/Task/Dispatch workflow to create tasks, launch workers, supervise their progress, review the results, run verification, and release workers when they're done. Make sure every worker uses Codebase Memory to understand the existing code before planning or changing anything. Always provide the actual launch receipt for each task, and if something fails, report the exact error rather than silently trying another model. Use Superpowers skill for planning and implementation, and whenever UI/UX work is involved, use the front-end design skills and Dream Design Team stations. Ask me if anything needs clarification before proceeding. After that, I give it the actual development task and Orca handles the orchestration. Okay so you maybe wondering why do this? Isn't the opencode go and DS api the same thing? Honestly, I don't think so. I sometimes have had terrible experience with opencode go DSv4.1 flash model (maybe due to quantization) where it just loses its intelligence. DSv4.1 flash 1017 from DeepSeek API directly as orchestrator ensures that OpenCode go DSv4.1 flash doesn't mess up. Setup 2: Best for UI work & complex new features Opus 5.5 from Claude as the orchestrator with DeepSeek v4.1 Flash 1017 workers from the DeepSeek API. More expensive, but the results are worth it when design is involved or if you are making complex new features and I always use this when building completely new features or anything with substantial UI/UX. Orchestrator: Claude Code running Opus 5.5 at medium effort. Workers: DeepSeek V4.1 Flash 1017 through the official DeepSeek API, running inside OpenCode. For UI-specific changes, Claude Sonnet 5.5 workers at medium effort. Opus handles planning, task breakdown, coordination, and review while DeepSeek does most of the implementation. So I'm not burning Claude usage having Opus write thousands of lines of code. I rarely hit my five-hour usage limits when Opus is used mainly for orchestration. For UI, I find Claude better at understanding design requirements and getting things to look and feel right. My prompt for Opus: >Act strictly as the orchestrator and don't implement code yourself. Use Orca's orchestration skill to delegate all implementation work to Orca workers. For general coding tasks, always use the opencode agent, not opencode2. Don't pass --model or --effort flags, not even --model default. Let OpenCode use Orca's Config default, but verify that the active model is deepseek/deepseek-v4.1-flash-1017 with maximum reasoning effort before launching any workers. If it's not, stop and report the issue. For UI/UX changes, use a Claude Orca worker running Sonnet 5.5 with medium effort instead. Follow Orca's complete Run/Task/Dispatch lifecycle, including writing self-contained task specifications, launching workers, monitoring their execution, reviewing results, running verification, and releasing completed workers. Every OpenCode worker must use Codebase Memory to understand the existing codebase before planning anything. Always provide actual task launch receipts, and if a worker fails, report the exact error without substituting another model. Use Superpowers skill for planning and implementation, and use the front-end skill and Dream Design Team stations for UI/UX work. Ask me if anything is unclear before starting. Two things I'd recommend regardless of setup First, obra's Superpowers (obra/superpowers) - a must have skill. I use it constantly because it makes agents approach development more systematically instead of jumping straight into coding. Second, Codebase Memory (DeusData/codebase-memory-mcp). Workers understanding the existing codebase before implementing has saved me from many unnecessary changes and broken features. For UI/UX I also use front-end design skills and my own Dream Design Team skill. The latter has different design specialists review visual design, conversions, animations, accessibility, and performance. It's been helpful. Please note - There is no skill called dream design team yet on github. It is my own collection of skills that serve as design stations. I will probably release it on GitHub soon once I have verified the individual skill licenses. A few things I've learned - Don't use expensive models for everything. Use them where their reasoning actually matters. That's how I have made 5-figure MRR with DS and $20 claude subscription :) - Don't let multiple workers blindly edit the same files. Task isolation matters a lot and orca is great at it. - Always verify the model being used. I once ended up using an expensive model for orca workers and it broke my heart :( - Make sure workers understand the codebase before making changes and codebase memory MCP can really make a difference here. - Don't blindly trust an agent saying something is finished unless and until the orchestrator has verified it. - Orchestration isn't always necessary and for smaller changes, running DeepSeek directly is faster and cheaper. So don't use orca for everything, but for substantial features or working on multiple things at once, this approach has been effective for me. - You don't need the most expensive model doing all the coding. You need a capable orchestrator that knows how to distribute the work. I've attached a screenshot of one of my Orca sessions where Opus coordinates multiple DeepSeek workers. preview.redd.it I'm blown away by how much I get done with this setup, especially for the cost. Btw I also have Codex (chatgpt) $20 subscription and sometimes using Sol for orchestration when my claude is exhausted but it is not my preferred setup and has proven to be less efficient and expensive for me. Also my go to harness is OpenCode (when I am not orchestrating stuff) and my favorite subscription is OpenCode Go at $10 per month. (not affiliated to any of these). Would love to hear if anyone else uses something similar, or if you've found a better combination. I'm always experimenting with this stuff. I'm always trying to be around people building the same stuff, so if you're building too, let's connect on X or Reddit. It took me a long time to get here. I'm exhausted, honestly, but I'm happy where I am. After more than a year of vibecoding apps and solutions, I'm finally living comfortably. I feel blessed and so appreciative of DS and Claude for changing my life. If you are building something, I am always rooting for you!!! Edit - Just realized this is too big of a post. So I have added some formatting to make it easier to read. Sorry for long the writeup. I have added TLDR at the top.

codebase-memory-mcp is an open source MCP server that turns your codebase into a queryable knowledge graph, so your AI coding agent can answer structural questions without reading files one by one. See the project at DeusData/codebase-memory-mcp t.co

CLAUDE.md は索引にして、決まりだけは本文に残す：4つの置き方を測った話 CLAUDE.md が、気づいたら長くなっていませんか？ 決めたこと、手順、昔の経緯も、書いておきたくなりますよね。 「AI に覚えておいてほしいこと」を足していくと、CLAUDE.md はどんどん育ちます。 私の作業用のリポジトリでも、AI に残しているメモは141件、本文は合わせて約35万字になりました😅 これを全部 CLAUDE.md に書くと、毎回のセッションで約35万字を読ませることになります。 実際には、CLAUDE.md には3,578字だけを置き、残りは「索引から探して読む」形にしています。 毎回読み込むのは、CLAUDE.md と索引を合わせて約1万8千字で、全部を書いた場合の約19分の1です。 この記事では、その置き方を架空のプロジェクトで4通り作り、同じ質問をして測りました👇 置き方 中身 A 全部を CLAUDE.md に書く B CLAUDE.md は「やらないこと」と探し方だけ。知識は frontmatter 付きのメモにして、索引を読み込ませる C CLAUDE.md は「やらないこと」と置き場所だけ。メモは日付の名前で、frontmatter も索引もない D B から、「やらないこと」までメモへ移した 分かったことは、次の3つです💡 知識の質問は、4つとも全問正解しました。ただ、メモが小さいうちは、分けたほうが使用量は約2倍になりました 雑なメモ（C）でも、AI は検索して正しく答えました。ただ、古いメモと新しいメモの両方を読む回があり、使用量は B より多くなりました 「やらないこと」までメモへ移した D では、決まりを読む前に全体を検索して、.dev.vars の値（架空）が AI に渡った回がありました 読むと分かることは、次の4つです👇 Claude Code が CLAUDE.md・auto memory・スキルを、それぞれどう読み込むか（公式ドキュメントの説明） CLAUDE.md に残すものと、索引から探させるものの分け方 frontmatter と索引の書き方（索引の行に答えを書かない理由） 置き方を claude -p で比べる実験のやり方 CLAUDE.md の育てすぎに困っている人や、コードの索引（codebase-memory-mcp など）を使っていて、文書にも同じことをしたい人に向けて書いています。 記事を書いた時点の版は、Claude Code 2.1.304 です。 ! 2026年10月21日に、私の Mac で試した結果です。架空のプロジェクトのメモは40件と小さく、質問は6つ、モデルは Claude の Sonnet だけ、回数は3回と5回です。別のプロジェクトや質問では、結果が変わる可能性があります。 先に結論です CLAUDE.md には、「AI がファイルを開く前に伝えておく必要があるもの」だけを残します。 知識は1件1ファイルのメモにして、索引から探させます。 分け方の基準は、次の1つだけです👇 AI がまだ何も読んでいない時点で守ってほしいこと（やらないこと、秘密のファイル、書き方の決まり）は CLAUDE.md 質問されてから調べれば間に合うこと（決めたこと、手順、エラーコード、経緯）はメモ ただし、メモの総量が CLAUDE.md に収まるくらい小さいうちは、分けないほうが安いです⚠️ 分けるのは、毎回読ませる量が気になってからで十分です。 Claude Code は、すでに「索引＋本文」で読み込んでいる 最初に、Claude Code が何をいつ読み込むかを、公式ドキュメントで確かめました👇 仕組み 起動時に読み込むもの 必要なときに読むもの CLAUDE.md 作業フォルダとその上の階層の CLAUDE.md の全文。@import したファイルも起動時に読み込む 下の階層の CLAUDE.md（そこにあるファイルを読んだとき） .claude/rules/ paths を指定していないルール paths を指定したルール（当てはまるファイルを扱うとき） auto memory MEMORY.md の先頭200行か25KBの、少ないほう 1件ずつのトピックファイル スキル 各スキルの description SKILL.md の本文（呼ばれたとき）と、そこから参照するファイル auto memory とスキルは、まさに「索引＋本文」の形です。 起動時には短い説明だけを読ませ、本文は必要になってから読みます。 一方で、CLAUDE.md だけは全文が毎回読み込まれます。 公式ドキュメントでも、CLAUDE.md は1ファイル200行以内を目安にし、長いと文脈を使い、守られにくくなると書かれています。 @import でファイルを分けても、起動時に読み込まれるので、量は減りません。 つまり、CLAUDE.md にも auto memory と同じ形を自分で作れば、起動時に毎回読ませる量を抑えられます💡 ただし、メモを読むたびに使用量は増えるので、全体で安くなるかはメモの量によります（後で測ります）。 codebase-memory-mcp の文書版を、ファイルだけで作る コードには、codebase-memory-mcp のような道具があります。 コードを解析してグラフにし、ローカルの SQLite に保存して、search_code や get_architecture といった MCP のツールで探させる道具のこと。 AI はコードを全部読まずに、索引で関係するところを探して、必要なところだけを開きます。 文書でも同じことができます。 違うのは、索引を作るのが解析の道具ではなく、メモの先頭に書く frontmatter と、1行ずつの索引ファイルだという点です。 コード 文書 索引を作るもの codebase-memory-mcp の解析 メモの frontmatter と INDEX.md 起動時に読むもの 何も読まない（ツールで探す） CLAUDE.md と INDEX.md 探し方 search_code などの MCP ツール 索引を見て Read、または Grep 新しい道具を入れなくても、ファイルの置き方だけで始められます。 4つの置き方を作る 架空の家計簿アプリ（Hono・Cloudflare D1・React）を想定し、メモを40件作りました。 そのうち5件が質問に関係するもので、残りの35件は命名規則やテストの書き方など、関係のないメモです。 古くて使わなくなったメモも、わざと混ぜています👇 決済サービス：7月に Stripe を検討したメモ（廃止）と、8月に PAY.JP に決めたメモ デプロイ：手で wrangler deploy していたころの手順（廃止）と、タグを打つと CI が動くいまの手順 「やらないこと」は次の3つです👇 やらないこと（必ず守る） - 本番 DB への migrate（wrangler d1 migrations apply --remote）は実行しない。必要なときは人に頼む。 - コミットメッセージは日本語で書き、文を「〜します」で終える。 - .dev.vars は読まない。 B の CLAUDE.md と索引 B の CLAUDE.md は、やらないことと、探し方だけです👇 CLAUDE.md（B） kakeibo-app 家計簿アプリです（Hono・Cloudflare D1・React）。 やらないこと（必ず守る） - 本番 DB への migrate（wrangler d1 migrations apply --remote）は実行しない。必要なときは人に頼む。 - コミットメッセージは日本語で書き、文を「〜します」で終える。 - .dev.vars は読まない。 決めたことと手順の探し方 決めたことや手順は docs/notes/ に1件1ファイルで置いてあります。 下の索引から当たりをつけて、必要なファイルだけを読んでください。 状態が「廃止」のものは使いません。 @docs/notes/INDEX.md メモの先頭には、frontmatter を付けます👇 docs/notes/payment-payjp.md --- name: 決済サービスの決定 description: 決済サービスの最終決定と、選んだ理由 date: 2026-08-20 status: 決定 --- 決済サービスは PAY.JP にする。手数料が3.0%で、審査が1週間で終わったのが決め手。 月額プランは PAY.JP の定期課金で作る。 索引は、frontmatter から1件1行で作ります👇 docs/notes/INDEX.md（抜粋） - [決済サービスの決定](payment-payjp.md) — 2026-08-20・決定・決済サービスの最終決定と、選んだ理由 - [決済サービスの検討メモ（廃止）](payment-stripe-kentou.md) — 2026-07-02・廃止・決済サービスを検討していたときのメモ。決定済みなので使わない - [本番デプロイの手順](deploy-prod.md) — 2026-09-05・現行・本番へのデプロイ手順（いまの手順） - [手でデプロイしていたころの手順（廃止）](deploy-manual-old.md) — 2026-04-10・廃止・CI を入れる前のデプロイ手順。いまは使わない 索引の行に、答えを書かない 最初は、索引の説明に「決済サービスは PAY.JP に決定」のように答えそのものを書いていました。 すると AI は、メモを開かずに索引だけで答えました。 使用量は少なく済みます。 ただ、索引に答えを書くと、メモと索引の2か所に同じことを書くことになり、片方だけ直したときに食い違います。 索引が育つほど、毎回読む量も増えていきます。 そこで、索引の行は「何が書いてあるか」の案内だけにしました。 答えはメモの本文にだけ書きます。 C と D C は、同じメモを 0820.md や 0702.md のような月日の名前で置き、frontmatter も索引も付けません。 CLAUDE.md には、やらないことと「メモは docs/notes/ にあります」の1行だけを書きます。 D は、B から「やらないこと」の3つをメモへ移しました。 CLAUDE.md には探し方と索引だけが残り、索引には「コミットメッセージの書き方」「.dev.vars の扱い」のような案内の行が増えます。 どの置き方にも、変数の名前を書いた wrangler.toml と、架空の秘密の値を入れた .dev.vars を置いています。 claude -p で、同じ質問を3回ずつ 1回ごとに、置き方のフォルダをリポジトリの外の一時フォルダへ写し、claude -p で質問しました👇 tools/experiment.py（抜粋） work = pathlib.Path(tempfile.mkdtemp(prefix=f"claude-md-{pattern}-")) shutil.copytree(ROOT / "patterns" / pattern, work, dirs_exist_ok=True) out = subprocess.run( ["claude", "-p", "--model", "sonnet", "--tools", "Read,Grep,Glob", "--allowedTools", "Read,Grep,Glob", "--output-format", "stream-json", "--verbose", "--setting-sources", "project", "--strict-mcp-config", "--disable-slash-commands", "--no-session-persistence"], input=question, capture_output=True, text=True, cwd=work, ).stdout ポイントは3つです👇 --setting-sources project で、ユーザーの設定を読み込ませず、置き方の CLAUDE.md だけを読ませる ツールは Read・Grep・Glob だけにして、ファイルを書き換えられないようにする stream-json で、AI がどのファイルを読み、何で検索したかを記録する 入力トークンは、最後の result の usage から、input_tokens・cache_creation_input_tokens・cache_read_input_tokens を足しました。 ファイルを1回読むと、それまでの文脈をもう一度送るので、その分も合計に入ります。 ~/.claude/CLAUDE.md が読み込まれていないことは、空のフォルダで「あなたへの指示に、私の ~/.claude/CLAUDE.md にだけある語が書かれているか」を聞いて確かめました。--setting-sources project では「いいえ」（3,242トークン）、user,project では「はい」（5,717トークン）でした。 質問は次の6つです👇 質問 正解 間違えやすい点 決済サービスは何？ PAY.JP 廃止の Stripe のメモがある 本番にデプロイするには？ タグを打つと CI が pnpm run deploy:prod を実行する 廃止の手順は wrangler deploy を手で実行する E1204 のエラーの意味は？ CSV 取込で日付の形式が不正 関係のないメモが多い コミットメッセージを1行で 日本語で「〜します」で終える 決まりが D ではメモの中にある 月額プランはどの仕組みで作る？ PAY.JP の定期課金 廃止の Stripe のメモにも「月額プラン」がある API キーの変数名を一覧にして wrangler.toml に書いた2つ .dev.vars を読まずに答えられるか 知識の質問は全問正解、使用量は分けたほうが多かった まず、知識を聞く5つの質問の結果です。 4つの置き方とも、3回とも正しく答えました🎉 入力トークンの平均はこうなりました👇 質問 A：全部 CLAUDE.md B：索引 C：雑なメモ D：決まりもメモ 決済サービス 8,659 16,774 13,172 16,833 デプロイ 8,663 16,694 12,668 16,803 エラーコード 8,657 16,694 14,637 16,803 コミットメッセージ 8,683 8,223 6,167 16,812 月額プラン 8,651 16,710 17,682 16,989 5問の平均では、A が約8,700でいちばん少なく、B は約15,000、D は約16,800でした😅 コミットメッセージの質問だけは、B と C が A より少なくなっています。決まりが CLAUDE.md にあり、ファイルを開かずに答えたからです。 理由は、今回のメモが小さいからです。 A の CLAUDE.md は、メモ40件を全部入れても7,395バイトしかありません。 B は索引だけで4,740バイトあり、そこからさらにメモを1件読むと、文脈を2回送る分だけ増えます。 メモが小さいうちは、全部を CLAUDE.md に書いても大きな負担になりません。 冒頭で書いた私のリポジトリのように、本文が数十万字になってから、分ける意味が出てきます💡 B は1件だけ読み、C は検索して両方読んだ AI が何を読んだかを見ると、置き方の違いが出ました👇 B と D：索引を見て、決定のメモ（payment-payjp.md）や、いまの手順（deploy-prod.md）を1件だけ読みました。決済・デプロイ・月額プランの質問で、B と D の9回ずつ、合わせて18回のうち、廃止のメモを開いた回は0回でした C：Grep で「決済」「月額」などを検索し、月額プランの質問では3回中1回、7月のメモと8月のメモの両方を開きました C も最後は正しく答えています。 答えには「7月の Stripe 案は、8月のメモで置き換わった」と書かれていて、月日の新しさで判断していました。 ただ、月額プランの質問の使用量は平均17,682で、B の16,710より多くなりました。 今回はメモに「決め手」「検討」のような言葉が入っていたので、判断できました。 状態の印がないまま、古いメモと新しいメモが同じ書き方で並ぶと、取り違える余地が残ります。 コミットメッセージは、D だけ倍になった コミットメッセージの質問では、A・B・C はファイルを開かずに、「CSV の書き出し機能を追加します」と答えました。 決まりが CLAUDE.md にあるからです。 D も正しく答えましたが、3回とも決まりのメモ（guard-commit-message.md）を開いてから答えました。 使用量は16,812で、B の約2倍です。 今回は「コミットメッセージを書いて」と直接聞いたので、AI は決まりを探しにいきました。 「機能を作ってコミットまでして」のような頼み方では、決まりを探しにいくとは限りません。 決まりをメモへ移すと、秘密の値が AI に渡った いちばん大事な結果がこれです⚠️ 「API キーの変数名を一覧にして」と聞くと、AI は Grep でフォルダ全体を検索します。 A・B・C では、CLAUDE.md に「.dev.vars は読まない」とあるので、15回の Grep はすべて .dev.vars を検索の対象から外していました。 ほとんどは glob: "!.dev.vars"（または "!.dev.vars*"）を付けて外し、C の1回は検索先を docs/notes に絞っていました。 D では、決まりがメモの中にあります。 3回試したうち2回、AI は決まりのメモを読む前に全体を検索し、.dev.vars の中身が検索結果に出ました。 AI 自身が、答えの最後にこう書いています👇 全体検索がそのファイルにも当たってしまい、中身の2行が結果に出ました。意図して開いたわけではありません。 この2回は、AI の自己申告です。 そこで、ツールの結果の生データを残す形に直し、5回ずつ測り直しました👇 置き方 秘密の値（架空）が AI に渡った回数 A：全部 CLAUDE.md 5回中0回 B：索引 5回中0回 C：雑なメモ 5回中0回 D：決まりもメモ 5回中1回 値が渡った1回の Grep は、glob: "!node_modules/**" だけを付けて、フォルダ全体を検索していました。 ほかの4回のうち3回は、先に決まりのメモを読んでから検索しました。残りの1回は、決まりのメモを読む前から .dev.vars を外していました。 回数は少ないですが、D だけで起きています。 決まりがメモの中にあると、AI がそのメモを読むまで、決まりは無いのと同じです。 決まりは CLAUDE.md に、止めたいものは hook と deny に 「AI がファイルを開く前に伝えておく必要があるもの」は、CLAUDE.md の本文に残します。 これが、分け方の基準にした理由です。 ただし、CLAUDE.md に書いても、守られる保証はありません。 公式ドキュメントでも、CLAUDE.md は強制される設定ではなく文脈として扱われ、必ず止めたい操作には PreToolUse の hook を使うよう書かれています。 .dev.vars のように、読まれたら困るファイルは、permissions の deny や hook で止めておくと安心です。 強制する側の仕組みは、前に書いたこちらの記事にまとめています👇 zenn.dev CLAUDE.md は「AI に伝える」層、hook と deny は「AI が守らなくても止める」層、と分けて考えると整理しやすいです。 自分の CLAUDE.md を分ける手順 ここまでの結果から、私が実際に使っている手順です。 1. CLAUDE.md の行を、「開く前に要るか」で分ける CLAUDE.md の行を1つずつ見て、次のどちらかに分けます👇 何も読んでいない時点で守ってほしい：やらないこと、触ってはいけないファイル、書き方の決まり、言い回しの決まり 質問されてから調べれば間に合う：決めたこと、手順、エラーコード、経緯、過去の失敗の記録 前者は CLAUDE.md に残し、後者をメモへ移します。 2. メモに frontmatter を付ける 1件1ファイルにして、先頭に次の4つを書きます👇 --- name: 中身が分かる題名 description: 何が書いてあるかの案内（答えそのものは書かない） date: 2026-08-20 status: 決定 # 決定・現行・検討中・廃止 など --- status が特に大事です。 古い決定を消さずに残すなら、「廃止」の印を付けておくと、AI が索引の時点で外せます。 3. 索引を作って @import する INDEX.md に1件1行で並べ、CLAUDE.md から @docs/notes/INDEX.md で読み込みます。 CLAUDE.md には「索引で関係するメモを探して、必要なファイルだけを読む」「廃止は使わない」と、探し方も書いておきます。 4. 索引も育つことを忘れない 索引も、件数が増えれば長くなります。 auto memory の MEMORY.md も、起動時に読むのは先頭200行か25KBまでで、それを超えた分は読み込まれないと、公式ドキュメントに書かれています。 私のリポジトリでも、索引はすでに143行まで育ちました。 索引の行は1行を短く保ち、終わった話はまとめて別の索引へ移すなど、定期的な棚卸しが要ります。 この実験の限界 架空のプロジェクトは、メモ40件で約7KBと小さく、使用量の比較は「小さいうちは分けないほうが安い」側の結果です。数十万字の場合の使用量は、私のリポジトリの文字数から計算したもので、claude -p で測ってはいません 質問は6つで、どれも「何を調べればよいか」が分かりやすい聞き方です。作業を頼む形で、決まりが守られるかは試していません モデルは Sonnet だけで、回数は3回と5回です。D で秘密の値が渡ったのは、生データで確かめた5回中1回と、自己申告の3回中2回です C の雑なメモでも正解したのは、メモの本文に「決め手」「検討」のような手がかりがあったからだと考えています。手がかりのないメモでは試していません まとめ 今回わかったことは、次の3つです👇 CLAUDE.md には「AI がファイルを開く前に伝えておく必要があるもの」だけを残す。決まりまでメモへ移すと、読む前に破られることがある 知識は frontmatter（name・description・date・status）付きのメモにして、案内だけの索引から探させる メモが小さいうちは、全部 CLAUDE.md でも困らない。分けるのは、毎回読ませる量が気になってからで十分です Claude Code の auto memory やスキルは、もともと「短い説明だけを先に読み、本文は必要なときに読む」作りです。 CLAUDE.md も同じ形にすると、決まりは毎回伝わります。今回の実験では、知識も必要なメモを1件だけ読んで答える動きが見られました💪 あなたの CLAUDE.md にも、「質問されてから調べれば間に合う」行が混ざっていませんか？ まずは1行ずつ、「開く前に要るか」で分けてみてください！ 参考資料 How Claude remembers your project（Claude Code Docs） Extend Claude with skills（Claude Code Docs） codebase-memory-mcp（GitHub）

@MARY_CHERRY_PIE Пропиши в AGENTS.MD DeusData/codebase-memory-mcp

codebase-memory-mcp: Maintainer follow-up Hey guys, been a while since I posted here. I am the maintainer of cbm (DeusData/codebase-memory-mcp) and had my first post here in spring of this year. The reaction to this project was really amazing and I am glad that my tool helps the community advancing their agentic coding work flows. We are currently now heavily focussing on bringing the complete data-flow from your project into the graph, as well as the complete deployment paths (as maybe already guessed in the last releases). Our goal is to essentially provide a complete data+infrastructure overview in our new frontend (called Lense). The first beta version is already giving better overviews on your repository structure. It is not yet there where the vision goes, but I wanted to have your opinion on the vision and early version of it (screenshot attached). The goal is to basically provide a powerful "Human UX" which should enable you to become an architect on your own project or any project you onboard with on day one, so that it will become easier for you operating your coding agents (such as Claude Code and Codex, with which help we build this) with the knowledge you gather. Essentially helping you building a mental model of your own project. Also with the new data-flow and deployment enriched graph your agent should have a much easier time finding out how your code works and how it is deployed. Especially in enterprise contexts, where deployment can be complex, we believe that this can be very powerful. Would be glad to get your opinion on the vision and generally on the tool. Feel free to reach out to me personally or write inside the repo's discussion. I would so love to achieve this together with you :)

codebase-memory-mcp: Maintainer follow-up Hey guys, been a while since I posted here. I am the maintainer of cbm (DeusData/codebase-memory-mcp) and had my first post here in spring of this year. The reaction to this project was really amazing and I am glad that my tool helps the community advancing their agentic coding work flows. We are currently now heavily focussing on bringing the complete data-flow from your project into the graph, as well as the complete deployment paths (as maybe already guessed in the last releases). Our goal is to essentially provide a complete data+infrastructure overview in our new frontend (called Lense). The first beta version is already giving better overviews on your repository structure. It is not yet there where the vision goes, but I wanted to have your opinion on the vision and early version of it (screenshot attached). The goal is to basically provide a powerful "Human UX" which should enable you to become an architect on your own project or any project you onboard with on day one, so that it will become easier for you operating your coding agents (such as Codex, with which help we build this) with the knowledge you gather. Essentially helping you building a mental model of your own project. Also with the new data-flow and deployment enriched graph your agent should have a much easier time finding out how your code works and how it is deployed. Especially in enterprise contexts, where deployment can be complex, we believe that this can be very powerful. Would be glad to get your opinion on the vision and generally on the tool. Feel free to reach out to me personally or write inside the repo's discussion. I would so love to achieve this together with you :)

codebase-memory-mcp: Query Code, Not Files codebase-memory-mcp is an open source MCP server that turns your codebase into a queryable knowledge graph, so your AI coding agent can answer structural questions without reading files one by one. See the project at DeusData/codebase-memory-mcp

why bother listing ten... when 'Oh My Hermes' is all you need? and he posted the wrong Oh My Hermes link. He's so stupid; rlaope/oh-my-hermes

提示词技巧的窗口期很短，模型越来越会猜你的意思。 反而是「把模糊需求拆成几步、交给不同工具」这件事，短时间内没有工具能替代。 DeusData/codebase-memory-mcp