|
1 | 1 | --- |
2 | | -description: Review the codebase and suggest (then implement) concrete improvements |
| 2 | +description: Review the codebase and suggest improvements |
| 3 | +argument-hint: additional optional context |
3 | 4 | --- |
4 | 5 |
|
5 | | -You are doing an improvement review of this codebase. The goal is to find **concrete, actionable improvements** — not a wishlist. Think like an experienced senior engineer or architect who respects the existing style and doesn't over-engineer. |
| 6 | +Find concrete improvements and flag things worth tracking for future work. Respect the existing style; don't over-engineer. Report findings only — do not make edits. The user will choose which suggestions to implement. |
6 | 7 |
|
7 | | -## What to read first |
| 8 | +## Steps |
8 | 9 |
|
9 | | -Get a broad picture of the project before forming any opinions. Use `#codebase` to survey the whole workspace — pay particular attention to: |
10 | | -- Package/dependency manifests (`package.json`, `Cargo.toml`, `pyproject.toml`, etc.) |
11 | | -- Compiler/type-checker config (`tsconfig.json`, `mypy.ini`, etc.) |
12 | | -- Runtime/bundler config (`bunfig.toml`, `vite.config.*`, etc.) |
13 | | -- Build and tooling scripts |
14 | | -- The README — how the project presents itself and what it's for |
15 | | - |
16 | | ---- |
| 10 | +1. Read `AGENTS.md` to understand the project structure. |
| 11 | +2. Survey the codebase, paying particular attention to: |
| 12 | + - Package/dependency manifests (`package.json`, etc.) |
| 13 | + - Compiler/type-checker config (`tsconfig.json`, etc.) |
| 14 | + - Runtime/bundler config (`bunfig.toml`, etc.) |
| 15 | + - Build and tooling scripts |
| 16 | + - `README` — how the project presents itself |
17 | 17 |
|
18 | 18 | ## Categories to evaluate |
19 | 19 |
|
20 | | -For each category below, look for real issues and note them. Skip categories where things look fine — don't invent problems. |
21 | | - |
22 | | -**Correctness / bugs** |
23 | | -- Are there any scripts or config values that are plainly wrong? (e.g. calling `npm run` in a Bun-only project) |
24 | | -- Any TypeScript errors or implicit `any` types? |
25 | | -- Any typos in user-facing strings (error messages, log output)? |
| 20 | +Skip categories where things look fine. Don't invent problems. |
26 | 21 |
|
27 | | -**TypeScript quality** |
28 | | -- Are types as precise as they should be? (e.g. `String[]` vs `string[]`, missing type annotations on parameters) |
29 | | -- Are there untyped third-party modules that need a `.d.ts` declaration? |
30 | | -- Are there `tsconfig.json` options enabled that don't apply to this project? |
| 22 | +**Correctness / Bugs** — wrong config values, broken scripts, typos in user-facing output |
31 | 23 |
|
32 | | -**Runtime / tooling overlap** |
33 | | -- Does the project use Node.js APIs where a Bun-native equivalent exists and is simpler? (e.g. `node:fs` vs `Bun.file()`) |
34 | | -- Are there npm/yarn artifacts in the scripts that should use `bun`? |
35 | | -- Are there dependencies that Bun now handles natively (e.g. a test runner, a bundler)? |
| 24 | +**Code Quality** — outdated practices, duplicated logic, unnecessary indirection, misleading comments, obvious simplifications |
36 | 25 |
|
37 | | -**Dev experience** |
38 | | -- Is there a fast linter+formatter that would be easy to add? (Biome is a good fit for Bun projects — one tool, zero config, very fast) |
39 | | -- Are there missing or misleading `package.json` scripts? |
40 | | -- Is the `.gitignore` / `.gitattributes` complete and correct? |
| 26 | +**Performance** — unnecessary looping, extra copies, redundant calls, known slow browser APIs |
41 | 27 |
|
42 | | -**Code clarity** |
43 | | -- Are there comments that are outdated or misleading? |
44 | | -- Are there any obvious simplifications (not refactors — just noise removal)? |
| 28 | +**TypeScript** — imprecise types, overuse of `any`/`unknown`, untyped third-party modules, irrelevant `tsconfig.json` options |
45 | 29 |
|
46 | | ---- |
| 30 | +**Testing** — coverage gaps, tests that don't actually verify what they claim |
47 | 31 |
|
48 | | -## How to respond |
| 32 | +**Runtime / tooling** — `node:*` APIs where Bun-native equivalents exist, `npm`/`yarn` artifacts in scripts, dependencies Bun now handles natively |
49 | 33 |
|
50 | | -1. **Group findings by category.** Within each category, distinguish between: |
51 | | - - 🔴 Real issues (bugs, broken things) — implement the fix immediately |
52 | | - - 🟡 Improvements (best practices, clarity) — implement unless non-trivial |
53 | | - - 💡 Suggestions (optional tools, bigger changes) — describe but don't implement; let the user decide |
| 34 | +**Developer Experience** — missing or misleading `package.json` scripts, incomplete `.gitignore`/`.gitattributes`, missing docs or source comments |
54 | 35 |
|
55 | | -2. **Be direct and brief.** One sentence per finding is usually enough. Don't pad. |
| 36 | +**Architecture / Technical Debt** — signs that complexity is accumulating: growing god-objects, framework or library choices that are becoming a liability, inconsistent patterns across similar code, coupling that makes changes harder than they should be, conventions the project has outgrown |
56 | 37 |
|
57 | | -3. **Implement the 🔴 and 🟡 items** using file edits. Verify there are no new TypeScript errors afterward. |
| 38 | +## How to respond |
58 | 39 |
|
59 | | -4. **Do not over-engineer.** A bug fix doesn't need surrounding code cleaned up. A simple improvement doesn't need extra configurability. Only change what needs changing. |
| 40 | +Group findings by category. Number each suggestion sequentially across all categories (1, 2, 3…) so the user can refer to them by number. For each finding: |
| 41 | +- 🔥 Actionable issue (bug, broken) — should be fixed soon |
| 42 | +- 👉 Improvement (best practice, clarity) — worth doing |
| 43 | +- 💡 Suggestion (optional, bigger change) — idea to track for future work |
0 commit comments