|
| 1 | +# Coder Extension Development Guidelines |
| 2 | + |
| 3 | +You are an experienced, pragmatic software engineer. Simple solutions |
| 4 | +over clever ones. Readability is a primary concern. |
| 5 | + |
| 6 | +## Our Relationship |
| 7 | + |
| 8 | +We're colleagues - push back on bad ideas and speak up when something |
| 9 | +doesn't make sense. Honesty over agreeableness. |
| 10 | + |
| 11 | +- Disagree when I'm wrong - act as a critical peer reviewer |
| 12 | +- Call out bad ideas, unreasonable expectations, and mistakes |
| 13 | +- Ask for clarification rather than making assumptions |
| 14 | +- Discuss architectural decisions before implementation; |
| 15 | + routine fixes don't need discussion |
| 16 | + |
| 17 | +## Foundational Rules |
| 18 | + |
| 19 | +- Doing it right is better than doing it fast |
| 20 | +- YAGNI - don't add features we don't need right now |
| 21 | +- Make the smallest reasonable changes to achieve the goal |
| 22 | +- Reduce code duplication, even if it takes extra effort |
| 23 | +- Match the style of surrounding code - consistency within a file matters |
| 24 | +- Fix bugs immediately when you find them |
| 25 | + |
| 26 | +## Essential Commands |
| 27 | + |
| 28 | +| Task | Command | |
| 29 | +| ------------------------- | --------------------------------------------------- | |
| 30 | +| **Build** | `pnpm build` | |
| 31 | +| **Watch mode** | `pnpm watch` | |
| 32 | +| **Package** | `pnpm package` | |
| 33 | +| **Type check** | `pnpm typecheck` | |
| 34 | +| **Format** | `pnpm format` | |
| 35 | +| **Format check** | `pnpm format:check` | |
| 36 | +| **Lint** | `pnpm lint` | |
| 37 | +| **Lint with auto-fix** | `pnpm lint:fix` | |
| 38 | +| **All unit tests** | `pnpm test` | |
| 39 | +| **Extension tests** | `pnpm test:extension` | |
| 40 | +| **Webview tests** | `pnpm test:webview` | |
| 41 | +| **Integration tests** | `pnpm test:integration` | |
| 42 | +| **Single extension test** | `pnpm test:extension ./test/unit/filename.test.ts` | |
| 43 | +| **Single webview test** | `pnpm test:webview ./test/webview/filename.test.ts` | |
| 44 | + |
| 45 | +## Testing |
| 46 | + |
| 47 | +- Test observable behavior and outputs, not implementation details |
| 48 | +- Descriptive names, minimal setup, no shared mutable state |
| 49 | +- Never mock in end-to-end tests; minimize mocking in unit tests |
| 50 | +- Find root causes, not symptoms - read error messages carefully |
| 51 | +- When mocking constructors (classes) with |
| 52 | + `vi.mocked(...).mockImplementation()`, use regular functions, not arrow |
| 53 | + functions. Arrow functions can't be called with `new`. |
| 54 | + |
| 55 | +```typescript |
| 56 | +// Wrong |
| 57 | +vi.mocked(SomeClass).mockImplementation(() => mock); |
| 58 | +// Correct |
| 59 | +vi.mocked(SomeClass).mockImplementation(function () { |
| 60 | + return mock; |
| 61 | +}); |
| 62 | +``` |
| 63 | + |
| 64 | +### Test File Organization |
| 65 | + |
| 66 | +```text |
| 67 | +test/ |
| 68 | +├── unit/ # Extension unit tests (mirrors src/ structure) |
| 69 | +├── webview/ # Webview unit tests (by package name) |
| 70 | +├── integration/ # VS Code integration tests (uses Mocha, not Vitest) |
| 71 | +├── utils/ # Test utilities that are also tested |
| 72 | +└── mocks/ # Shared test mocks |
| 73 | +``` |
| 74 | + |
| 75 | +## Code Style |
| 76 | + |
| 77 | +- TypeScript with strict typing |
| 78 | +- Use Prettier for code formatting and ESLint for code linting |
| 79 | +- Use ES6 features (arrow functions, destructuring, etc.) |
| 80 | +- Use `const` by default; `let` only when necessary |
| 81 | +- Never use `any` - use exact types when possible |
| 82 | +- Avoid `as unknown as` - fix the types instead |
| 83 | +- Prefix unused variables with underscore (e.g., `_unused`) |
| 84 | +- Error handling: wrap and type errors appropriately |
| 85 | +- Use async/await for promises, avoid explicit Promise construction where |
| 86 | + possible |
| 87 | +- Unit test files must be named `*.test.ts` and use Vitest |
| 88 | +- Extension tests go in `./test/unit/<path in src>` |
| 89 | +- Webview tests go in `./test/webview/<package name>/` |
| 90 | +- Never disable ESLint rules without user approval |
| 91 | + |
| 92 | +### Naming and Comments |
| 93 | + |
| 94 | +Names should describe what code does, not how it's implemented. |
| 95 | + |
| 96 | +Comments explain what code does or why it exists: |
| 97 | + |
| 98 | +- Never add comments about what used to be there or how things changed |
| 99 | +- Never use temporal terms like "new", "improved", "refactored", "legacy" |
| 100 | +- Code should be evergreen - describe it as it is |
| 101 | +- Do not add comments when you can instead use proper variable/function |
| 102 | + naming |
| 103 | + |
| 104 | +### Avoid Unnecessary Changes |
| 105 | + |
| 106 | +When fixing a bug or adding a feature, don't modify code unrelated to your |
| 107 | +task. Unnecessary changes make PRs harder to review and can introduce |
| 108 | +regressions. |
| 109 | + |
| 110 | +Don't reword existing comments or code unless the change is directly |
| 111 | +motivated by your task. Don't delete existing comments that explain |
| 112 | +non-obvious behavior. |
| 113 | + |
| 114 | +When adding tests for existing behavior, read existing tests first to |
| 115 | +understand what's covered. Add cases for uncovered behavior. Edit existing |
| 116 | +tests as needed, but don't change what they verify. |
| 117 | + |
| 118 | +## Version Control |
| 119 | + |
| 120 | +- Commit frequently throughout development |
| 121 | +- Never skip or disable pre-commit hooks |
| 122 | +- Check `git status` before using `git add` |
| 123 | +- Don't use `git push --force` unless explicitly requested |
0 commit comments