Grounding AI With Your Project Context

By NTh Hai - 8 min read

Ask a generic model “how should I structure auth?” and you get a blog-post answer. Ask it “how does auth work in this repo?” without context and you get a confident fiction. The difference is grounding: connecting AI to the facts of your project.

This post explains the concept of project context for AI-in-coding — from IDE rules to retrieval-augmented generation (RAG).

Generic Knowledge vs. Project Truth

Models know a lot about public patterns. Your project has private truth:

  • Folder conventions and naming
  • Which libraries you actually use (and which you banned)
  • Domain language (“Account” ≠ “User” in your schema)
  • Operational constraints (multi-tenant, offline mode, EU data residency)
  • Historical landmines (“never touch legacy/billing without a feature flag”)

Without those, AI optimizes for the average GitHub repo — not yours.

Layers of Grounding

1. Manual context (always available)

Paste files, error logs, and short architecture notes into the chat. Simple, reliable, and enough for many tasks. The limit is your attention and the context window.

2. Standing instructions

Many tools support project rules or system notes: “prefer functional components,” “use Zod for validation,” “tests live next to source.” These are always-on constraints. Keep them short and current; stale rules are worse than none.

3. Repo-aware tools

Agents that can search, open files, and run commands ground themselves by reading the tree. Your job is to point them at the right entry points and verify their navigation.

4. Retrieval (RAG)

Index docs, ADRs, runbooks, and sometimes code into a search layer. At query time, pull the top relevant chunks into the prompt. Conceptually:

Query → retrieve relevant project text → generate answer constrained by that text.

RAG does not make the model omniscient. It makes answers citeable against sources you control.

What to Index (and What Not To)

Good candidates: README onboarding, architecture decision records, API contracts, runbooks, style guides, glossary of domain terms.

Risky or low value: Huge generated lockfiles, binary assets, secrets, raw production data, every historical commit message.

Code can be indexed, but search quality depends on chunking and embeddings. Often docs + selected modules beat “embed the whole monorepo.”

Designing Context Like an API

Treat the context pack as a deliberate interface:

  • Budget: how many tokens for rules vs. retrieved docs vs. the user question
  • Freshness: when was this index last updated?
  • Authority: which sources override others when they conflict?
  • Citation: can the answer point back to a file or doc section?

If two retrieved chunks disagree, the model will blend them. Prefer a single source of truth and mark deprecated docs clearly.

Practical Patterns for Teams

Onboarding pack. A living AI.md or rules file that explains how the app boots, where features live, and how to run tests. New humans and new agents both benefit.

Task-scoped retrieval. For a billing bug, retrieve billing docs and modules — not the marketing site content.

Verify then act. Ask the assistant to quote the project rule or file path it is following before it edits. Hallucinated grounding is still hallucination.

Human-curated snippets. For critical domains, maintain short “golden” excerpts the team trusts more than vector search noise.

Failure Modes of Ungrounded AI

  • Reinventing utilities that already exist
  • Introducing a second HTTP client or state library
  • Ignoring multi-tenancy and leaking data across orgs
  • “Fixing” flaky tests by weakening assertions
  • Writing docs that contradict the code

Most of these look like competence until you zoom out to the whole repository.

Closing Thought

AI becomes useful on a real project when it stops answering from the internet average and starts answering from your rules, docs, and code. Grounding — whether by pasting files, standing instructions, agent search, or RAG — is the conceptual bridge between a general model and a specific codebase. Invest in that bridge, and integrating AI stops feeling random and starts feeling like part of the engineering system.