Try this if
- Your project has one long file the AI keeps opening, like a decision log, a backlog or a running set of notes.
- Your AI only ever needs one entry from a long file like that at a time.
- You want the split checked by counting before anything is saved, with nothing committed and nothing deleted.
- Skip it if your long file is short enough to read at a glance. An index over a handful of items only adds a step.
Each time the AI needs one item from a long file, it opens the whole thing. The file might be a log of decisions, a backlog or a running set of notes, and it grows every week.
The AI pays for every item in the file to reach the one it wanted, and it pays again the next time, for a file that's a little longer. Everything else it read sits in its working space for the rest of the session, taking room the task could have used.
The answer is to split the file. Every item goes in a small file of its own, and the original file becomes a lean index, one line per item, pointing at each. The index works like a map. The AI reads it, picks the line it needs and opens one small file, instead of digging through the whole pile. One project learned this the slow way. It first put a short list on top of its long file and left the long file whole, and only a measurement showed that the list saved almost nothing.
A pointer into a long file saves almost nothing
That project kept 162 decisions in one file of about 490 kilobytes. It also had a shorter file listing which decisions still applied, each pointing into the long one. Asked whether the arrangement was paying for itself, the AI measured it. A typical decision was about 2.9 kilobytes, so following one pointer meant opening a file about 170 times the size of the thing being looked up. Nine other projects built the same way carried the same shape, at 21 to 145 times.
The list on top helped the AI find the right item and did nothing for the cost of reading it. An index only pays when each line points at a file the size of one item.
What the split looks like
In the index that project ended up with, each row carries an id that never changes, a date, a title, one sentence saying what was decided and a link to its own file. That project's index also has a column marking which decisions still bind, and the entries themselves sit in a folder beside it. The index kept the old file's path, so every link that already pointed at the log still works and now lands somewhere useful.
The same shape works for anything the AI reads one item at a time. A backlog becomes one file per piece of work with a table over them, and a notes folder gets one index line per note. Stop your AI agent from forgetting your project between sessions shows where the index files sit among the rest of a project's files.
Keep the index in step with the files
An item with no index line is easy to miss, because the AI reads the index first and may never look past it. An index line with no file behind it is a dead end. So the index line gets written in the same change as the file it points at, and a standing rule in the file your AI reads first says so.
The recipe below checks this once, by counting files against items. To keep it true afterward, compare the number of item files to the number of index lines now and then, and a link checker that fails on a link to nothing catches the second case every time it runs, if your project has one. Keep each index line to one short sentence, because the index grows with every item too.
Try this in your own setup
Paste the block below into your AI. It asks which long file to split and what counts as one item, shows you the plan before it moves anything, splits the file, turns the original into the index and checks its own work by counting. It adds the standing rule, deletes nothing and commits nothing, and it lists every file it wrote so you can read them before you commit.
What you get and what you don't
You get an AI that opens the one item a task needs, and an index you can read yourself to see everything that file held.
You don't get a cleaner file. The split moves every item exactly as it is, so an old entry that should have been retired is still there, in its own file. Marking what still applies is a separate job, and you can add a column to the index for it.
Pick the longest file your AI rereads and count its items. If the AI only ever needs one of them at a time, split it.
Paste this into your AI agent or a new chat. The post above says what it does. Some prompts set something up in your project that keeps working after, and others run once, right where you paste them. None of them pushes anything to a remote.
You are restructuring one long file in my project so that you, and any AI after you, can read one item without reading them all. The goal is one small file per item and a lean index that points at each.
Before you read, list, look at or change anything, ask me these two things and wait for my answers. Your first reply is only the questions:
1. Which long file you keep reading, and what counts as one item in it, such as a dated entry, a heading or a numbered decision.
2. Which tool I work in: Claude Code, Codex, Cursor or the Claude chat app, and if it can read and write my files, which project folder this is in. If I am in the Claude chat app, also ask me to paste the file or upload it with my answers.
If I ask what you are about to do before I answer, explain it in plain words and wait.
Then, using my answers:
- Read the file in full. Count the items. Show me the count, the name of the folder the items will go in, the filename you would give the first three items and the index line you would write for each. A filename starts with the item's id or date, then a few words of its title. Wait for my yes before you move anything.
- Make the folder beside the file. Put each item in its own file, holding exactly the text the item has today, nothing added and nothing summarized.
- Turn the original file into the index, at the same path, so every link that already points at it still works. One line per item, in the file's original order, with the id or date, the title, one sentence saying what the item decided or holds, and a link to its file. Keep any introduction the file had at the top.
- Check your work by counting. The number of item files must equal the number of items you counted before, and every link in the index must open a file. Tell me both numbers. If they differ, stop and tell me which items are missing.
- Add a standing rule where my tool keeps its instructions, in AGENTS.md or CLAUDE.md at the project root in Claude Code, Codex or Cursor, whichever already exists. If neither exists, ask me before creating AGENTS.md. The rule is: "Read the index first and open only the item the task needs. When you add an item, write its file and its index line in the same change." In the Claude chat app, give me the rule to paste into the project's instructions.
- In the Claude chat app, with no access to my files, do the same work as text instead. Give me the index, then the first three item files, each under its filename, and tell me how to finish the rest by hand.
- Delete nothing. The original file stays where it is, now holding the index, so its history carries on. Do not commit anything. List every file you created or changed, so I can read them and commit them myself.
- Do not push to any remote. Do not install software. Do not rewrite, merge or summarize any item.
Finish by telling me how the next session should use it: read the index, open one item.