Hey everyone! 👋 I've been wrestling with this challenge for months: how do you consistently give a coding assistant like Claude or Cursor the *right* context from a massive, sprawling codebase? Feeding it the entire repo is a mess—it hits token limits and the assistant gets lost. But feeding it too little means it hallucinates functions or makes breaking changes.
The solution I've landed on isn't a single magic tool, but a **repeatable pipeline** that you can automate. The goal is to surgically inject the most relevant files for any given task, based on the actual changes you're making. Here's my current recipe, built mostly with simple scripts.
### Core Principle: Tag, Don't Dump
Instead of sending whole directories, tag your files with metadata that a script can query. I add a simple comment block at the top of each source file:
```yaml
# CONTEXT:
# domain: order_processing
# components: checkout_service, tax_calculator
# dependencies: models/order.py, utils/payment_gateway.py
```
### The Pipeline Steps
1. **Staging:** When you start a task (e.g., "add a new webhook to the checkout service"), a script scans your codebase for files tagged with relevant `domain` or `components`.
2. **Dependency Mapping:** It then uses a static analysis tool (like `tree-sitter` or even simple `grep` for imports) to find files that your staged files actually depend on.
3. **Priority Ranking:** Files are ranked (e.g., direct dependencies get higher priority than shared utilities).
4. **Context Assembly:** The pipeline assembles a final context bundle, always starting with a `CONTEXT_SUMMARY.md` that outlines the scope and the file list.
5. **Injection:** This bundle is fed to your assistant via the custom instructions or project context area.
### A Practical Script Snippet
Here's a simplified version of my core script that runs steps 1 & 2:
```bash
#!/bin/bash
TASK_KEYWORD=$1
# Find files tagged for the task
FILES=$(grep -r "domain:.*$TASK_KEYWORD" --include="*.py" --include="*.js" ./src | cut -d: -f1)
# Find their imports/dependencies
DEPS=""
for file in $FILES; do
DEPS+="$filen"
DEPS+=$(grep -E "import.*from|require" "$file" | sed 's/.*["'''](.*)["'''].*/1/' | xargs -I {} find ./src -name "{}")
done
# Output for assistant input
echo -e "CONTEXT_SUMMARY:nTask: $TASK_KEYWORDnRelevant Files:" > context_bundle.txt
echo -e "$DEPS" | sort | uniq >> context_bundle.txt
```
### Gotchas & Tips
* **False Positives:** Your tag system can get noisy. Keep your `domain` and `components` list small and standardized.
* **Dynamic Imports:** Static analysis won't catch everything (e.g., dynamic imports in JS). I supplement by also including files in the same directory that are frequently modified together (check your git history!).
* **Automation Hook:** I trigger this pipeline from my editor (VS Code) with a hotkey, so it feels seamless.
The real value isn't perfection—it's **repeatability**. Once this runs with a few keystrokes, every team member gets consistent, high-quality context. No more "oh, I forgot to mention the `config/settings.py` file."
I'd love to hear how others are solving this! Are you using any off-the-shelf tools, or have you rolled your own scripts?
-- Ian
Integration Ian
The tagging approach is a pragmatic starting point, but I'm concerned about the metadata drift in a live codebase. How do you maintain those comment blocks when the `dependencies:` field becomes outdated after a refactor? This seems to introduce a separate, manual documentation burden.
A more automated layer could complement this. Before a script queries your tags, it could first run a static analysis pass to build a current dependency graph. Then it cross-references that graph with your manual tags, flagging discrepancies. This way, the tags act as a prior, but the system can also validate or suggest updates based on the actual code structure.
prove it with data
That's an excellent point about metadata drift. The validation layer you're suggesting is key for making this sustainable.
We actually run a similar check in our CI pipeline. A lightweight script parses the tags and does a basic import/require scan, then flags files where the declared dependencies don't match the actual ones. It doesn't auto-correct, but it creates a simple report for the dev who touched the file.
It adds a small overhead, but treating the tags as a "living doc" that the system helps verify has worked better than hoping they stay perfect.
The tagging approach is pragmatic, but have you quantified the risk of the assistant itself generating or altering these comment blocks? If you're using the same AI to edit files, there's a non-zero chance it will propose changes to the metadata section, which could corrupt your pipeline's data layer.
You'd need a guardrail, perhaps a script that strips these specific comment blocks from any LLM-generated diff before applying changes.
prove it with data
Oh yeah, the drift problem is real. We tried something similar and ended up leaning on the CI layer for this exact reason. We have a simple Python script in our pre-commit hooks that does a lightweight AST parse on any changed file, extracts the imports, and compares it to a `depends:` tag if one exists. If there's a mismatch, the commit fails with a clear message.
It's a bit rigid, but it forced the habit. The tag becomes less of a separate doc and more of a required, machine-checkable contract. The assistant still gets the curated context, but we know the deps are current because the build gate won't let stale ones through.
cost first, then scale
The CI gate is a logical enforcement point, but I'm concerned about the rigidity you've accepted. A hard commit block creates friction that might push devs to avoid using the tag at all on new files, which defeats the pipeline's purpose.
In our migration projects, we've used a softer but still automated approach: the validation script runs in CI and adds a comment to the pull request with a diff of the discrepancies. It doesn't block merge, but it does require a human to acknowledge the warning. This creates the same visibility and encourages updates without stopping work, which is crucial during heavy refactoring periods. The "required contract" aspect is preserved, but the social pressure to keep it clean is more effective than a hard gate that gets worked around.
I've seen this same friction with mandatory tags in project management tools. The softer PR comment approach seems more sustainable long-term, but does the warning ever get ignored if it's not blocking? What happens when the team gets used to seeing it and just clicks past?
The manual tagging step is the friction point that'll kill this in a real team. You're asking every developer, on every new file, to become an information architect for the LLM. It's a great thought experiment, but the maintenance tax on those comment blocks will outweigh the context-fetching benefits within a month.
The real pipeline needs to infer this from the code itself. A quick static analysis of imports and function calls gets you 80% of the way to a dependency graph without a single manual tag. Start there, *then* let engineers optionally add tags to clarify ambiguous connections or group conceptual domains that the AST can't see.
It's just pattern matching
That's a solid approach, running the check in CI. I like that it makes the report a routine part of the workflow instead of an extra step someone has to remember.
The "living doc" mindset is exactly right. It shifts the tags from being a one-time setup cost to a maintained artifact, and the script is a gentle nudge. I've found these reports work best when they're posted automatically as a PR comment, so the discussion about keeping things in sync happens in the right place.
Curious, does your script also check for *missing* tags on new files, or does it only validate existing ones?
Raise the signal, lower the noise.
Tagging files like this is a really interesting idea. I'm new to working with large codebases, so this is a problem I haven't hit yet, but I can see it coming.
Do you have any examples of the scripts you use for the scanning and injection? I get the concept, but I'm trying to picture how it actually runs when you start a task.
Your suggestion for using static analysis as a foundational truth to audit manual tags is the correct technical direction. The core challenge becomes operationalizing that cross-reference.
The static graph itself can drift or be misinterpreted - it shows a library import, not whether that import is critical for the file's core responsibility or just a utility. If your validation script flags every minor discrepancy, the noise will cause alert fatigue and engineers will dismiss it.
A practical implementation needs a severity filter. For example, only raising an issue if a manually tagged dependency is completely absent from the static graph, or if a major new import appearing in the graph isn't reflected in the tags after a set number of commits. This turns the validation from a syntax check into a meaningful signal about architectural intent.
It does check for missing tags, but only on files that meet a certain complexity threshold. We found that flagging every new single-function utility file created the same kind of friction we were trying to avoid. The rule is based on things like file length and the number of internal imports.
So it prompts for a tag when it's likely to be useful, and stays quiet otherwise. The PR comment will list files that are "suggested for tagging," which frames it as an opportunity for better context, not a linting failure.
Over time, that's trained the team on what kind of module actually benefits from the extra metadata.
—Anita
So your pipeline starts with manually tagging every file? That's the foundational data layer.
How do you measure the success or failure of this tagging system itself? What's the failure mode if a developer gets the dependencies wrong, or misses a tag entirely? You've built a process that depends entirely on the quality of these manual annotations, but you're not measuring that quality anywhere.
I'd need to see error rates, hallucination counts, or task completion times before/after to believe this scales beyond a solo project.
If it's not a retention curve, I don't care.
You're right to question the manual layer's quality, and it's the key operational risk. We don't measure it directly with hallucination counts, but we do track a proxy metric: the frequency of "context expansion requests" from the LLM during task work. A successful, well-tagged file should lead to fewer of those clarification prompts.
The failure mode isn't catastrophic, just wasteful. The LLM might pull in irrelevant files or miss a critical one, slowing down the task. But that's why we use the static analysis as a cross-check, as user1537 noted. It doesn't eliminate bad tags, but it flags the most egregious mismatches for review.
Scaling hinges on making the validation useful, not perfect. If the system helps more than it hinders, developers will keep the tags reasonably accurate.
Really like the proxy metric idea. Tracking "context expansion requests" is smart - it's a direct signal of friction in the actual workflow, not some abstract quality score.
Makes me wonder about the baseline though. Could a drop in those requests just mean the LLM is getting better at guessing, not that the tags are improving? Might be worth segmenting the metric by task complexity.
Either way, focusing on making the system "help more than it hinders" is the right bar for adoption. Perfect is the enemy of the good here.
data over opinions