codebase-onboarding · diff
git:20260314.a3b7738 to git:20260519.40bb110
80 added, 96 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: codebase-onboarding
- description: >-
- Guides the agent in rapidly understanding an unfamiliar codebase — its structure,
- conventions, dependencies, and key patterns. Use this skill when working in a new
- repository for the first time, when the agent needs to understand how a project is
- organized before making changes, when onboarding to a codebase with no documentation,
- or when the user says "look at this repo" or "understand this project."
+ description: Maps an unfamiliar repo before touching its code.
+ tier: practical
+ category: workflow
+ created_by: human
+ platforms: [windows, macos, linux]
+ tags: [onboarding, exploration, conventions]
+ author: Andreas Wasita (@andreaswasita)
---
- # Codebase Onboarding
+ # Codebase Onboarding Skill
- Understand the codebase before you change it. A 10-minute investigation prevents a 2-hour mess.
+ Builds a working mental model of an unfamiliar repository before making changes: language, framework, structure, conventions, entry points, and test pattern. Does NOT exhaustively read every file — surveys strategically, then drills in where the work demands it.
## When to Use
- - Working in a new or unfamiliar repository
- - Before making changes to code you haven't read
- - When a project lacks documentation
- - User asks you to understand a project or repo
- - When subagents need context about the codebase
-
- ## How to Use
-
- ### Step 1: Survey the Landscape
+ - Working in a new or unfamiliar repository.
+ - Before making changes to code you have not read.
+ - When a project lacks documentation.
+ - User asks you to "look at this repo" or "understand this project".
+ - Briefing a sub-agent on context before delegating.
+ - NOT when you already have a recent mental model of this repo — re-onboarding wastes turns.
- Get the big picture in 60 seconds:
+ ## Prerequisites
- ```bash
- # Project structure (top 2 levels)
- find . -maxdepth 2 -type f | head -50
- # or: tree -L 2
+ - Read access to the repository.
+ - The `view`, `grep`, and `glob` Copilot tools.
+ - The `powershell` tool to inspect files outside the source tree (lockfiles, etc.).
+ - Ability to run the project's test command (later, optional).
- # What language/framework?
- cat package.json 2>/dev/null # Node.js
- cat requirements.txt 2>/dev/null # Python
- cat go.mod 2>/dev/null # Go
- cat pom.xml 2>/dev/null # Java
- cat *.csproj 2>/dev/null # .NET
+ ## How to Run
- # README — the author's intent
- cat README.md | head -100
+ ```text
+ 1. Survey the top-level layout with `glob`.
+ 2. Read manifest files (package.json, pyproject.toml, go.mod, *.csproj, pom.xml).
+ 3. Read the README.
+ 4. Identify the architecture pattern from directory names.
+ 5. Open the entry point and one representative test.
+ 6. Note conventions: naming, imports, error handling, test layout.
+ 7. Write a short Quick Map (5–10 lines) for your future self.
```
- ### Step 2: Identify the Architecture
+ ## Quick Reference
- Look for these patterns:
+ | Survey target | Tool | Why |
+ |---|---|---|
+ | Top-level layout | `glob '*'` | Frames the project |
+ | Source layout | `glob 'src/**'` (or repo equivalent) | Spots architecture pattern |
+ | Manifests | `view package.json` / `view pyproject.toml` | Language, framework, scripts |
+ | README | `view README.md` | Author's intent |
+ | Entry point | `view src/main.*` / `view cmd/main.go` | How startup actually works |
+ | Tests | `view` one representative test | Pattern + framework |
- | Signal | What It Tells You |
- |--------|-------------------|
- | `src/controllers/` or `src/routes/` | MVC or route-based architecture |
- | `src/features/` or `src/modules/` | Feature-based / domain-driven |
+ | Directory signal | Architecture clue |
+ |---|---|
+ | `src/controllers/` or `src/routes/` | MVC / route-based |
+ | `src/features/` or `src/modules/` | Feature / domain-driven |
| `packages/` or `apps/` | Monorepo |
| `src/components/` | Component-based frontend |
| `cmd/` and `internal/` | Go standard layout |
- | `src/main/java/` | Java/Spring project |
- | `Dockerfile` + `docker-compose.yml` | Containerized services |
-
- ### Step 3: Understand the Build and Run
-
- Find the entry points:
+ | `src/main/java/` | Java / Spring |
+ | `Dockerfile` + `docker-compose.yml` | Containerized service set |
- ```bash
- # How to install
- cat Makefile 2>/dev/null
- cat package.json | grep -A5 '"scripts"' 2>/dev/null
+ ## Procedure
- # How to run
- grep -r "main\|entry" package.json tsconfig.json webpack.config.* 2>/dev/null
+ ### Step 1: Survey the Landscape
- # How to test
- grep -r "test\|spec" package.json Makefile 2>/dev/null
- ```
+ Use `glob` on `*`, then on `src/**` (or the equivalent). Note top-level files. Use `view` on the manifest file for the stack — `package.json`, `pyproject.toml`, `go.mod`, `*.csproj`, `pom.xml`.
- ### Step 4: Read the Key Files
+ ### Step 2: Read the README
- Priority reading order:
- 1. **Config files** — `.env.example`, config/, settings — understand the knobs
- 2. **Entry point** — `main.ts`, `app.py`, `cmd/main.go` — follow the startup path
- 3. **Routes/API** — How the outside world interacts with the system
- 4. **Models/Types** — The data structures that drive the domain
- 5. **Tests** — Tests tell you what the code is *supposed* to do
+ Open `README.md` with `view`. The author usually states the project's purpose, run instructions, and conventions in the first hundred lines.
- ### Step 5: Map the Conventions
+ ### Step 3: Identify Architecture
- Before making changes, note:
- - **Naming conventions** — camelCase? snake_case? How are files named?
- - **Error handling pattern** — Exceptions? Result types? Error codes?
- - **Testing pattern** — Co-located? Separate `__tests__/` directory? What framework?
- - **Import style** — Absolute? Relative? Path aliases?
- - **State management** — Where does state live? How is it shared?
+ Match the directory layout to the table above. Note any divergence — those are the "interesting" parts.
- ### Step 6: Document for Future You
+ ### Step 4: Read the Entry Point
- If the project lacks a CONTRIBUTING.md or architecture doc, create a brief mental model:
+ Open the entry file with `view`: `src/main.ts`, `src/app.py`, `cmd/main.go`, `Program.cs`. Trace the startup path one level deep. You are mapping shape, not deeply auditing logic.
- ```markdown
- ## Quick Map
+ ### Step 5: Sample One Test
- - **Language**: TypeScript (strict mode)
- - **Framework**: Next.js 14 (App Router)
- - **Testing**: Vitest, co-located test files
- - **Key patterns**: Server Components default, Server Actions for mutations
- - **Entry point**: src/app/layout.tsx
- - **API layer**: src/app/api/
- - **Data models**: src/lib/models/
- - **Build**: `npm run build`, Deploy: Vercel
- ```
+ Use `glob` to locate tests (`**/*.test.*`, `**/test_*.py`, `**/*_test.go`). Open one with `view`. Note framework, fixture style, and where tests live relative to source.
- ## Examples
+ ### Step 6: Capture the Quick Map
- **Bad — Blind Editing:**
- > User: "Add a new API endpoint to this project"
- > Agent: *Creates a file in the wrong directory, wrong naming convention, wrong framework patterns*
+ Write a 5–10 line summary for your own use (and to brief sub-agents):
- **Good — Onboard First:**
- > User: "Add a new API endpoint to this project"
- > Agent: "Let me understand the project first. This is a FastAPI app with routes in `src/api/routes/`, models in `src/models/`, and a consistent pattern of Pydantic schemas for request/response. Tests are co-located. I'll follow the existing pattern in `src/api/routes/users.py` as a template for the new endpoint."
+ ```markdown
+ ## Quick Map: <repo-name>
+ - Language: TypeScript (strict mode)
+ - Framework: Next.js 14 (App Router)
+ - Tests: Vitest, co-located `*.test.ts`
+ - Patterns: Server Components default, Server Actions for mutations
+ - Entry: `src/app/layout.tsx`
+ - API: `src/app/api/`
+ - Models: `src/lib/models/`
+ - Build: `npm run build`. Deploy: Vercel.
+ ```
- ## Guidelines
+ ## Pitfalls
- - Reading code is faster than guessing and rewriting
- - Match existing patterns even if you'd do it differently
- - When uncertain, look at 3 similar examples in the codebase before writing code
- - Use subagents for parallel codebase exploration when the project is large
+ - **DO NOT** start editing before completing the survey. You will pick the wrong directory.
+ - **DO NOT** ask the user what stack it is when the manifest answers the question.
+ - **DO NOT** read the repo linearly file by file. Survey strategically.
+ - **DO NOT** impose your preferred conventions. Match the existing style even if you would do it differently.
+ - **DO NOT** skip reading at least one existing test — tests are executable docs.
- ## Anti-Patterns
+ ## Verification
- - **Assuming project structure** — Not all Python projects use Django patterns
- - **Ignoring conventions** — Introducing camelCase into a snake_case codebase
- - **Skipping the README** — Authors usually explain the important things
- - **Reading every file** — Survey strategically, don't read the entire codebase linearly
- - **Asking the user what you could discover yourself** — "What framework is this?" when `package.json` is right there
+ - [ ] Quick Map written (language, framework, tests, entry, build).
+ - [ ] At least one existing test file was opened with `view`.
+ - [ ] Architecture pattern is named (MVC / monorepo / etc.).
+ - [ ] Run command is identified and recorded.
+ - [ ] Naming/convention rules are noted before any new file is created.