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.

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.

Workflow

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

Use cases

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

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

# 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.

Related Resources

Explore more resources that work well with this one.

Used in Playbooks

Complete workflows that include this resource as a step.

AI Codebase Onboarding Workflow Workflow · 4 steps

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

Explore all resources