113 lines
4.3 KiB
Markdown
113 lines
4.3 KiB
Markdown
Deeply explore the current working directory (or a path the user specifies), extract the most salient facts about the codebase, and write them to **OVERVIEW.md** in the project root.
|
||
|
||
The goal is a document a new developer could read on day one to understand *what the app does*, *how it's structured*, *what it connects to*, and *where the interesting parts are*. Be specific and factual — avoid vague summaries. If you find a concrete detail (a database URL format, an API endpoint, a notable architectural pattern), include it.
|
||
|
||
## Exploration strategy
|
||
|
||
Use the tools available to you to explore in parallel where possible. Here's what to look for:
|
||
|
||
**Start with the high-level anchors:**
|
||
- `package.json` / `Cargo.toml` / `pyproject.toml` / `go.mod` — dependencies, scripts, metadata
|
||
- `README.md` if it exists — stated purpose
|
||
- Main entry point (e.g. `src/main.tsx`, `app.py`, `cmd/main.go`, `index.js`)
|
||
- Build/config files (e.g. `vite.config.*`, `webpack.config.*`, `docker-compose.yml`, `.env.example`)
|
||
|
||
**File and directory structure:**
|
||
- Walk the top 2–3 levels of the directory tree
|
||
- Identify major groupings (e.g. `routes/`, `components/`, `api/`, `db/`, `services/`)
|
||
- Note any monorepo structure (workspaces, `packages/`, `apps/`)
|
||
|
||
**Tech stack:**
|
||
- Framework(s) and runtime
|
||
- Language(s)
|
||
- Build tooling
|
||
- Test framework
|
||
|
||
**Integrations:**
|
||
- Third-party APIs and SDKs (look for imports, env var names, config keys)
|
||
- Authentication providers
|
||
- Analytics, monitoring, feature flags
|
||
- Payment processors, messaging services, etc.
|
||
|
||
**Database and data layer:**
|
||
- ORM or query library in use
|
||
- Database type (Postgres, MySQL, SQLite, MongoDB, etc.)
|
||
- Schema files or migration directories
|
||
- Connection config (env var names, config files)
|
||
|
||
**Connectivity and configuration:**
|
||
- `.env.example` or similar — what env vars are expected
|
||
- API proxy config (e.g. Vite's `server.proxy`, nginx config)
|
||
- Port numbers, base URLs, service addresses
|
||
- Any hardcoded endpoints or service URLs in source
|
||
|
||
**Architecture patterns:**
|
||
- State management approach
|
||
- Routing strategy
|
||
- Notable design patterns (e.g. provider pattern, command/event bus, repository pattern)
|
||
- Anything non-obvious that would trip up a new developer
|
||
|
||
## OVERVIEW.md format
|
||
|
||
Write the file to the project root. Use this structure, but adapt section depth and detail to what's actually present — don't include empty sections:
|
||
|
||
```markdown
|
||
# [App/Project Name] — Overview
|
||
|
||
> One-sentence description of what this app does and who uses it.
|
||
|
||
## Purpose
|
||
|
||
2–4 sentences on the domain, user-facing purpose, and any important context
|
||
(e.g. "phase 0 of a migration from Preact to React").
|
||
|
||
## Tech Stack
|
||
|
||
| Layer | Technology |
|
||
|-------|-----------|
|
||
| ... | ... |
|
||
|
||
## Directory Structure
|
||
|
||
Brief annotated tree of the top 2–3 levels. Only include directories and files
|
||
that are meaningful — skip `node_modules`, lockfiles, build output, etc.
|
||
|
||
## Architecture
|
||
|
||
Key architectural patterns, data flow, and anything non-obvious. This section
|
||
is where you explain the *how* rather than just listing what exists.
|
||
|
||
## Integrations
|
||
|
||
For each external service or API: what it is, what it's used for, and where
|
||
in the codebase it appears.
|
||
|
||
## Database & Data Layer
|
||
|
||
ORM/library, database type, schema location, migration approach, connection config.
|
||
If there's no database, say so (e.g. "Frontend-only — no database layer").
|
||
|
||
## Connectivity & Configuration
|
||
|
||
Expected environment variables, API proxy setup, service endpoints, ports.
|
||
Use a table or list with variable name + purpose.
|
||
|
||
## Key Entry Points
|
||
|
||
The files a new developer should read first to understand how the app boots
|
||
and how requests/events flow through it.
|
||
|
||
## Notes & Gotchas
|
||
|
||
Anything that would surprise a new developer: non-standard patterns, in-progress
|
||
migrations, known tech debt worth knowing about, Preact internals being used, etc.
|
||
```
|
||
|
||
## Quality bar
|
||
|
||
- Be specific. "Uses Postgres via Drizzle ORM, schema defined in `packages/db/schema.ts`" is better than "uses a database."
|
||
- If something is unclear (e.g. you can see a dependency but can't find where it's used), say so briefly rather than omitting it.
|
||
- Keep the file readable — a developer should be able to scan it in 5 minutes.
|
||
- Don't reproduce large code blocks; reference file paths instead.
|
||
- After writing the file, confirm to the user what was created and where.
|