I’ve been experimenting with a small repo convention for making Cursor/agent context easier to navigate without depending on a separate indexing service.
The workflow has two parts:
- Every meaningful directory gets an
index.mdwith short links/descriptions of the files and subdirectories there. This gives the agent a tree to follow instead of asking it to infer repo structure from search alone. - Cross-cutting concepts get explicit
@tag:<slug>tokens in both docs and code comments. For example, a payment flow might have@tag:paymentsin a design doc, a service file, a test file, and a migration. Then a plain text search finds all related code/docs even if they live in different directories.
I wrote the convention up here:
The intent is not to replace Cursor project rules. I think it works better as something project rules point to: “read the nearest index.md, follow related links, and use tags for cross-cutting concepts.” That keeps the rules file smaller and moves durable repo knowledge next to the code/docs.
I’d be interested in feedback from people using Cursor on larger repos:
- Do you keep long-lived repo knowledge in Cursor rules, docs, or both?
- Have you found a good pattern for cross-cutting concepts that don’t map cleanly to directories?
- Would visible tags in code comments be helpful, or too noisy?