Engineering

AI Onboarding Context for an Existing Codebase

Onboard AI to a codebase the way you'd onboard a new hire: what it is, how it's built, the rules that aren't written down, and the things never to assume.

Open in Project Context Builder

Overview

A new engineer gets a walkthrough; AI usually gets nothing and infers the rest. This setup writes the walkthrough for OpsConsole, an internal admin tool used by ~30 staff to inspect accounts and replay failed jobs. The Internal Tool mode keeps the principles pragmatic; you record the unwritten rules (log every destructive action, no PII in shareable URLs) and the team's vocabulary (replay, DLQ, actor). The profile becomes the onboarding doc the AI reads before touching the code — so its first contribution fits the project instead of fighting it.

How to use this resource

Write the walkthrough

Overview, mode, and stack — the orientation a new hire would get on day one.
Capture the unwritten rules

The conventions and never-assume lines that live only in people's heads.
Onboard the AI once

It reads the profile before contributing, like any new team member.

Why This Works

Internal Tool mode keeps the guidance pragmatic, not enterprise-grade overkill
The unwritten rules are the ones AI breaks first — writing them down stops that
A small, known audience means the profile can be specific and short

Best for

Existing internal tools and admin panels
Codebases with tribal knowledge
Onboarding AI assistants to a working repo

Not for

Explaining one function or file in depth — use the Code Explanation Prompt
Greenfield projects with nothing built yet

FAQ

Where does this project profile go so Cursor actually uses it?

At the repo root, saved as .cursorrules (or .cursor/rules/project.mdc) — the profile's top note says so, so Cursor loads it for every request and every teammate gets the same context. It travels with the code. The project-context-builder generates the profile for OpsConsole; you commit the file, and the AI reads it before touching the code rather than inferring your conventions.

Why capture a glossary and never-assume list instead of just the tech stack?

Because the unwritten rules are the ones AI breaks first. The Glossary defines team vocabulary — Replay, Actor, DLQ — so the model speaks your language, and Never Assume pins rules that live in people's heads: "do not expose internal IDs or PII in shareable URLs" and "reference the migrations or schema file before writing a query." The Internal Tool project type keeps it pragmatic rather than enterprise-grade overkill.

Is this the same as giving the AI a role or persona?

This is project knowledge, not behavior. The AI Usage Notes draw the line: "for a task persona (role, tone, escalation rules), build a System Prompt in the System Prompt Generator," and for continuing an in-progress task in a new chat, use the Context Handoff Builder. This profile is durable project identity — what OpsConsole is, its stack, conventions — not how the AI should act or the current work state.

Customize This Resource

Opens this project in Project Context Builder. Build to get the full context profile — then adjust the mode, stack, glossary, and output target.

Open in Project Context Builder

Prompt Template

Copy it as-is, or use Open in Project Context Builder to load it pre-filled and customize it with your own context.

# Project Context: OpsConsole

> Save this at your repo root as `.cursorrules` (or `.cursor/rules/project.mdc`) so Cursor loads it for every request.

## Project Overview
OpsConsole is an internal admin panel used by our support and operations teams to inspect accounts, issue refunds, and replay failed jobs. Audience is ~30 internal staff.

## Core Facts
- Project type: Internal Tool
- Primary stack: Vue, FastAPI, PostgreSQL, Redis, JavaScript, Python
- This is an internal tool for a known, small audience — pragmatism beats polish.

## Tech Stack
- Vue
- FastAPI
- PostgreSQL
- Redis
- JavaScript
- Python

## Team Conventions
- Every destructive action is logged with the actor and reason.
- Prefer boring, obvious code — this tool is maintained part-time.
- No new external dependencies without a quick team check.
- Use the Composition API with `<script setup>` unless a file already uses the Options API. (Vue)
- Use Pydantic models for request/response schemas and type hints throughout; let FastAPI handle validation. (FastAPI)
- Use Redis for caching/queues with explicit TTLs; never treat it as the source of truth. (Redis)
- Use `const`/`let` (never `var`) and strict equality (`===`). (JavaScript)
- Follow PEP 8 and add type hints on public functions. (Python)

## Naming Rules
- Database: snake_case for tables and columns; plural table names. (PostgreSQL)
- camelCase for variables and functions, PascalCase for classes. (JavaScript)
- snake_case for functions and variables, PascalCase for classes, UPPER_SNAKE for constants (PEP 8). (Python)

## Architecture Principles
- Optimize for the team's real workflow, not hypothetical external users.
- Favor simple, obvious solutions over scalable-but-complex ones unless scale is a stated need.
- Keep operational steps documented — the next maintainer may be a teammate with no context.

## Glossary
- **Replay** — re-running a failed background job from the dead-letter queue.
- **Actor** — the staff member performing an admin action.
- **DLQ** _(abbreviation)_ — dead-letter queue.

## Always Remember
- Refund and account-deletion actions require a second-person confirmation.
- This profile is the source of truth for project facts — prefer it over general assumptions.

## Never Assume
- Do not expose internal IDs or PII in shareable URLs.
- Do not assume the schema — reference the migrations or schema file before writing a query.
- Do not assume newer syntax is available — confirm the target Python version.
- Do not assume public-grade hardening is required — confirm the threat model before adding it, but never weaken auth on shared data.
- When a fact is missing from this profile, ask — do not invent it.

## AI Usage Notes
- Cursor reads project rules from the repo, so this travels with the code and every teammate gets the same context.
- This profile is project KNOWLEDGE, not behavior — for a task persona (role, tone, escalation rules), build a System Prompt in the System Prompt Generator.
- It is durable project identity, not work state — to continue an in-progress task in a new chat, use the Context Handoff Builder.
- Profile completeness: 100/100 (Complete) — bracketed gaps, if any, mark missing info that was never invented.

More resources from Project Context Builder

Resource

Build Project Memory for AI

Stop re-explaining your project in every new chat. Capture it once as a context profile the AI keeps across every conversation — stack-inferred conventions and all.

Prompt Engineering

Resource

Create an AI Project Profile

A reusable profile that tells AI everything constant about your project — type, stack, conventions, glossary, architecture principles, and the rules it must never guess.

Prompt Engineering

Resource

Set AI Team Conventions Everyone Shares

When every teammate explains the project differently, AI gets a different story each time. Shared team conventions give it one consistent account.

Engineering

Resources that pair well

Resource

AI Session Handoff — Shift Change for Working Sessions

End a working session like a shift change, not an abandonment: state captured, decisions logged, next step named — ready for the next session to pick up.

Prompt Engineering

Resource

Bug Triage Assistant

Convert scattered bug notes, Slack messages, or user complaints into structured engineering tasks with reproduction steps, severity, and root cause hypothesis.

Engineering

Resource

Convert a Conversation to a Prompt — the Full Anatomy

What a converged conversation contains: a rejected voice, an accepted framing, a hard constraint, a format decision, and a final-version moment — each mapped to its prompt section.

Prompt Engineering

Related tools

Tool

Project Context Builder

Define what AI should permanently know about your project — stack conventions, glossary, and never-assume rules in a profile you paste once.

Context Tools

Workflows that use this resource

Workflow

AI Codebase Onboarding Workflow

Get up to speed on an unfamiliar codebase in an afternoon — ground the AI in the project, have it explain the hard parts, and keep what you learn.

4 steps 30–60 minutes

Tip: Save time by exploring related resources and tools that integrate with this resource.