How I Audit a New Codebase with Cursor—Docs First, Code Second

You've just been handed 40k lines of code and a tight deadline. You can either spelunk through random directories or let an AI do the heavy lifting. Here's the workflow I've refined after onboarding to more repos than I can remember.

1. Clone, Create, and Configure

The moment I get repo access, I:

1. git clone locally.
2. Fire up Cursor and load my global user-rules—a living checklist that survives between projects. Tossing it below for anyone who wants to borrow:

- Conventions‒extend existing code style and architecture—never reinvent.
- Self-documenting code‒expressive identifiers, minimal explanatory comments.
- DRY + KISS‒reuse abstractions and ship the simplest working solution.
- Separation of concerns‒models, repositories, routes, etc. live in their own packages.
- Explicit error handling‒no uncaught exceptions.
- No dummy data‒remove placeholders; tests use real fixtures, not mocks.
- Docstrings on every public symbol.
- Rule upkeep‒if ./cursor/rules is missing or stale, propose updates; flag any legacy .cursorrules file at once.
- Dev-friendly scripts‒shell scripts must print clear, colourised output.
- Python env‒ensure a local venv; create it if absent.
- DB default‒PostgreSQL unless project rules specify otherwise.
- Documentation goes in /docs/**/*.md
- Planning docs‒store in ./plans/**/*.md, use task lists (- [ ] / - [x]) and cross-link related docs.
- Architecture, Design, Functionality, Principles go in .cursor/rules/*.mdc—be pithy and link back to /docs/.

Cursor treats these as the prime directive for every suggestion it makes.

2. Branch for Docs Before Code

I create a dedicated docs branch. This seems backward to some folks, but it saves the team from "we'll write docs later" syndrome. The branch isolates massive auto-generated commits from functional changes, so reviewers can focus.

3. Ask Cursor the Big Seven

With rules loaded, I prompt Cursor to audit and document:

1. What the codebase actually does – A human-readable README overhaul.
2. Backend & architecture – Layers, packages, services, interactions.
3. Database schema – ERDs and explanations in /docs/db/.
4. OpenAPI file – If there's an API, Cursor reverse-engineers an OpenAPI-v3 spec.
5. Frontend stack – Component library, design tokens, theming rules.
6. User flows – From signup to power-user paths, diagrammed in Markdown + Mermaid.
7. Core functionality – Feature checklists with pointers to critical modules.

Depending on repo size, Cursor churns for a few minutes indexing and creating docs files. While I wait, I read the files that have already been produced. Sometimes I will start putting questions together or ideas for other docs that I would like to see from the next step.

4. Review, Refine, Repeat

Once Cursor finishes, I'll review what it found and ask it to adjust or create new docs based on my questions and notes.

5. Long-Term Payoff

Because my rules enforce keep docs in sync, every future PR that I make to features, functionality, database, interfaces, etc will trigger Cursor to update the relevant docs files automatically.

That means:

• Onboarding new devs and AI agents is quick.
• The application vision is clearer anyone who needs to know what the application is intended to do can look quickly and get what they need.
• AI pair-programming gets richer context, leading to better suggestions.

TL;DR

Docs-first auditing with Cursor flips the onboarding script: you gain context up front and bake sustainability into the repo on day one. Try it on your next project—your future self (and your team) will thank you.