Giving the Assistant the Right Context

The problem

You ask: "Add an endpoint to get a user's orders." The assistant writes a Flask route with raw SQL. Your project uses FastAPI, SQLAlchemy and a services/ layer, returns money as integer cents, and every endpoint needs an auth dependency. Fixing the result takes longer than writing it yourself.

Real-world analogy

A new contractor joins your team for a day. If you only say "add an endpoint", they will build it the way they usually do. If you give them the style guide, show them an existing endpoint and explain the house rules, their first attempt fits.

The idea

Give the assistant three kinds of context:

• Standing project context: a project instructions file (for example CLAUDE.md or AGENTS.md) with the stack, commands to run tests, folder layout and conventions. Tools load it automatically every session.
• Task context: point at the relevant files ("follow routers/invoices.py"), the data model, and any constraints.
• Acceptance criteria: what "done" means: the tests to pass, the behaviour, the error cases.

The code

A small check that compares a request against the project's must-know conventions, showing which context a vague request leaves out:

conventions = {
    "framework": ["fastapi"], "data access": ["sqlalchemy", "service"],
    "auth": ["auth", "current_user"], "money": ["cents"], "tests": ["test"],
}

def coverage(request):
    text = request.lower()
    return {name: any(word in text for word in words) for name, words in conventions.items()}

vague = "Add an endpoint to get a user's orders."
specific = ("Add GET /users/{id}/orders in FastAPI, following routers/invoices.py: use OrderService "
            "(SQLAlchemy), require current_user via the auth dependency, return amounts in cents, "
            "and add tests like tests/test_invoices.py.")
for name, request in [("vague", vague), ("specific", specific)]:
    missing = [k for k, ok in coverage(request).items() if not ok]
    print(f"{name:8} missing context: {missing or 'none'}")

vague    missing context: ['framework', 'data access', 'auth', 'money', 'tests']
specific missing context: none

A minimal project instructions file:

# Project notes for AI assistants
- Stack: Python 3.12, FastAPI, SQLAlchemy 2 (async), PostgreSQL. Tests: `pytest -q`.
- Endpoints live in app/routers/, business logic in app/services/. Routers never query the DB directly.
- Money is stored and returned as integer cents. Every endpoint uses `Depends(current_user)`.
- Before finishing: run `pytest -q` and `ruff check .`.

Common mistakes

• Expecting the assistant to infer conventions it cannot see.
• Pasting huge amounts of irrelevant code, which buries what matters.
• Letting the instructions file go stale; outdated rules cause consistent mistakes.
• Forgetting to say how to verify the work (which tests or commands to run).

Key points

• Keep a short, current project instructions file for standing context.
• Point to example files and constraints for each task.
• State acceptance criteria, including how to run the checks.

Further reading: Claude Code: manage memory (CLAUDE.md) · AGENTS.md · Claude Code best practices