The specs exist. The AI just can't see them.
I've always been the type who builds hobby projects, gets satisfied halfway through, and never actually finishes. For a long time I wanted to change that — to build something all the way to the end and actually ship it. So a bit over a year ago, I started building small, microservice-style pieces: if each piece is small, I can actually finish it, reuse it later, and it won't eat months of my life. It might sound like overkill for a solo project, but for me it was a trick to "cut things down to a finishable size."
Then AI-assisted development became the norm. To give the AI context, I started writing proper spec documents even for personal projects. So far, so good.
The problem: with microservices, my repos are separate. The repo I have open in Cursor right now is Service A. The spec I want to reference lives in Service B's repo. The spec exists. It's written down. The AI just can't see it.
"How do I hand the AI a spec that lives outside the workspace I currently have open?" This article is a record of me taking far longer than I needed to turn that problem over in my head.
The actual dilemma: two options, both with a price tag
When you boil it down, there are really only two options (probably).
Option A: Add it to the workspace (index everything)
Use Cursor's multi-root workspaces and add the entire spec repo to your workspace. I actually tried this.
It wasn't terrible, but it wasn't exactly pleasant either. Irrelevant files get pulled into context. Files from a repo I'm not even working on show up in search. The symptoms I remember: edits landing in places I didn't ask to change, and token usage ballooning. All I wanted was to read a few spec files, and instead I was paying the tax of putting an entire repo into the AI's field of view.
(AI models keep getting better, so maybe this is less of an issue today.)
To be fair, multi-root workspaces themselves have evolved. In its April 2026 release, Cursor made it so a single agent session can target a multi-folder workspace and make cross-repo changes (changelog). For "fix something across the frontend and the backend" workflows, it's genuinely better now. But the structure hasn't changed: every folder you open becomes part of the index. For "I just want to read a few spec files," it's still overkill.
Option B: Don't add it — fetch on demand (read everything)
Keep the repo out of your workspace and have the AI go fetch files when needed. For example, by writing the paths into your rules file.
If you know the file path, this works fine. The problem is the "wait, I know I wrote this down somewhere" case. Since the AI doesn't know the path, it has to read through the candidate files to find it. Which means loading full file contents into context just to run a search. That's a lot of tokens.
So the dilemma is:
Pay in noise to index everything, or pay in tokens to read everything.
The options I considered — and my false assumption
"If it doesn't exist, build it" is a fine spirit, but if there's a giant's shoulder to stand on, you should stand on it. Before jumping into building my own thing, I did look at existing solutions.
Self-hosted docs tools: I found there were tools that let you run a GitBook-like setup locally with Docker. But they needed customization to fit my workflow, felt inflexible, and didn't offer the polished experience of the paid tools. Which led me to the classic thought: "If it's not that hard to build, maybe I'll just build it myself?" (Ah yes, the person who was going to build it no matter what.)
External SaaS: Documentation-management services were either shockingly expensive or way too much for a solo project's needs.
GitHub MCP Server: In my research chats with an AI at the time, there was a line saying it "needs to run locally," and based on that I ruled it out from the start. If I have to run a container locally anyway, I figured, it's no different from the self-hosted option.
— And here's where I have to make an embarrassing confession. That exclusion was based on a false assumption. GitHub MCP Server has a remote-hosted version, and it went GA in September 2025 (GitHub Changelog). GitHub hosts it, you authenticate once with OAuth, and that's it. No Docker, no PAT management. I only learned this while researching for this very article.
In other words: if I had been a little more skeptical of the AI's research back then and gone to the primary sources, there's a good chance I never would have started building this product. I'm always telling my nephew not to blindly trust what AI says, and yet here we are...
AI research can be based on outdated or plain wrong premises — I re-learned that lesson only after building an entire product on top of it. That said, I still think it was a good experience (I know how that sounds, but as I'll explain in the next section, what I built didn't turn out to be pointless either).
The problem that remained: search that never feels quite right
The remote GitHub MCP Server is genuinely capable. It can fetch files from private repos without a local clone. Honestly, if you know the file path, listing your spec paths in a rules file and letting GitHub MCP read them solves most of my use case, for free.
What about search, then? Turns out that works too. GitHub MCP Server has a code search tool, and GitHub's code search indexes the private repos you have access to (official docs). If I wrote "you can't do cross-repo search with GitHub MCP," that would simply be false.
But when I map it onto the daily "where did I write that part of the spec again?" use case, a few things snag. All of these are documented behavior (official docs):
- Only the default branch is searched, and only files under 384 KB. Specs usually fit, but if you keep spec variants on different branches, those are out of scope.
- The code search API is rate-limited to 10 requests per minute, even authenticated. That's a separate, much tighter bucket than the regular API (5,000/hour). AI agents love to fire off search queries in trial-and-error loops, so you feel this limit quickly.
- Search results are mostly file metadata. (The API can hand back short highlight fragments if you ask for them, but that's about it.) To actually read the content, you need a follow-up fetch. So it's a minimum of two round trips: search, then fetch.
None of these are "it doesn't work." They're all "it never feels quite right for daily use." But "I know I wrote this somewhere" happens multiple times a day. Do I really want to step on that friction every single time?
My answer was to hand search off to a search engine (of sorts). Put the spec contents in PostgreSQL and do the search in a single DB query (eventually vector search too). Return to the AI only a snippet: the matching lines plus a few lines of context. No punishing rate limits, no extra round trips, and the only thing landing in the AI's context is the fragment it actually needs. I'm still mid-development, so it's too early to make big claims about the results — but at minimum, the "now where did I write that" hunts seem to be going away.
What I'm building: a small, read-only window onto your specs
That's what led to Repospec, which I'm building now. You register "this file in this repo is a spec" on a dashboard, and then from Cursor or Claude Code, via MCP, you get fetch and cross-repo search over just your registered specs. (Note: it's still pre-launch — only a landing page for now, where you can sign up for release notifications.)
The design principle was to strip away everything unnecessary and keep it simple. Which means there are things I deliberately did not build: editing features and version control, among others. I wanted to stay focused on my own actual problem, and if this was going to be a product, I did not want it to become "a worse GitBook." The source of truth stays in your GitHub repos; this thing is strictly read-only plumbing.
Do you actually need this?
Write your spec repo paths into .cursor/rules and let GitHub MCP Server read them. If that covers you, that's completely fine. If your project is small enough that you can remember your file paths, you don't need another tool.
This dilemma only really starts to hurt when "multiple repos" × "I can't remember where I wrote what" becomes your daily reality. At that point you have three choices: index everything, read everything, or move just the search outside. I wrote this article because I think there's value in simply knowing the options exist.
When it comes to actually "mastering" AI-assisted development, I feel like there's still a lot of room for craft. The itch is never quite scratched. But what I've gained from building this — that's turning out to be not so small.
Originally written in Japanese (https://zenn.dev/shida_dev/articles/8304bc8dc63b10). Translated with AI assistance and reviewed by the author.
Top comments (2)
The 10-requests-per-minute code-search limit is the detail that makes this more than a workspace-ergonomics debate: an agent doing trial-and-error discovery can burn through that budget before finding the right spec. I also like the read-only boundary-keeping GitHub as the source of truth while returning matching lines plus nearby context from PostgreSQL gives the model a smaller, more intentional slice of the repo. The founder lesson is to validate the "existing remote option" assumption against primary docs before building, but Repospec still has to prove that fewer round trips outweigh the cost of keeping another index fresh.
Thanks for the thoughtful comment. You've put your finger on exactly the right trade-off: whether fewer round trips actually outweigh the cost of keeping another index fresh is the open question of this design.
My current answer is that freshness must never be a manual chore — that's a design premise. The cache reacts to push events from GitHub automatically, so there's nothing for a human to do in day-to-day operation.
I also deliberately chose not to add a TTL. A file that expires out of the cache also drops out of cross-repo search, and "I searched but it didn't show up" is the one failure mode I can't accept. Weighing stale-content risk against missing-from-search risk, I sided with tolerating the former.
You're right that at this point it's a bet, not proof. I'm planning to write up the cache design in detail in a future article — it'll be a little while before it's out, but if you're interested, a follow here means you won't miss it.