diff --git a/explore.md b/explore.md deleted file mode 100644 index dc8f903..0000000 --- a/explore.md +++ /dev/null @@ -1,112 +0,0 @@ -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.