Skip to content

Commit 6e0ade4

Browse files
bartstcbartstc
committed
chore: refactor Copilot instructions
1 parent 47f5b0e commit 6e0ade4

7 files changed

Lines changed: 152 additions & 226 deletions

File tree

‎.github/instructions/architecture.instructions.md‎

Lines changed: 20 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,96 +1,28 @@
11
---
2-
applyTo: "**"
2+
applyTo: "{src,e2e}/**"
33
---
44

5-
## Architecture Overview
5+
# Architecture Rules
66

7-
React SPA built with Vite using feature slice architecture with clean architecture principles.
7+
## Project Structure
88

9-
### Core Technologies
9+
- `src/features/` — feature modules using feature slice architecture
10+
- `src/lib/api/` — centralized API layer: queryOptions factories, mutations, DTOs by resource
11+
- `src/lib/` — shared utilities, components, HTTP client, i18n, routing, theme
12+
- `src/pages/` — route-level page components composing features
13+
- `src/app/` — app-level config (App.tsx, Providers.tsx)
14+
- `e2e/` — Playwright end-to-end tests
15+
- `test-lib/` — test utilities, MSW handlers, fixtures
1016

11-
- **React 19** with TypeScript
12-
- **Vite 7** for build tooling
13-
- **React Query (TanStack Query)** for data fetching
14-
- **React Router 7** for routing
15-
- **i18next** for internationalization
16-
- **MSW 2** for API mocking
17-
- **Vitest 4** for unit and component testing
18-
- **Storybook 10** for component development
19-
- **Playwright** for E2E testing
20-
- **Zustand** for state management
21-
- **Chakra UI** for components
22-
- **XState** for state machines
17+
## Feature Slice Layers
2318

24-
### Project Structure
19+
- Each feature has four layers: `components/`, `application/`, `providers/`, `models/`
20+
- `components/` imports from `application/`, `models/`, and `providers/`
21+
- `application/` imports from `models/` and `providers/` — not from `components/`
22+
- `providers/` is the data access gateway: composes query hooks, mutations, loaders from `src/lib/api/`
23+
- Library-specific code (React Query, etc.) stays inside `providers/` — never leak beyond this layer
24+
- API logic starts in `src/lib/api/` (queryOptions factories, mutations, DTOs by resource), then gets exposed through the relevant feature's `providers/`
25+
- Query files expose `queryOptions` factories — hook composition belongs in `providers/`, not in API files
26+
- Co-locate related files: component + story + test together
2527

26-
```
27-
.
28-
├── e2e/ # End-to-end tests with Playwright
29-
└── src/
30-
├── app/ # App-level configuration (App.tsx, Providers.tsx)
31-
├── features/ # Feature modules using feature slice architecture
32-
│ ├── auth/ # Authentication feature
33-
│ ├── carts/ # Shopping cart feature
34-
│ ├── products/ # Product catalog feature
35-
├── lib/ # Shared libraries and utilities
36-
│ ├── api/ # Centralized API layer (queries, commands, DTOs)
37-
│ ├── components/ # Reusable UI components
38-
│ ├── http/ # HTTP client and error handling
39-
│ ├── i18n/ # Internationalization setup
40-
│ ├── router/ # Routing utilities
41-
│ └── theme/ # Theme configuration
42-
├── pages/ # Route-level page components composing feature components & logic
43-
└── test-lib/ # Testing utilities and fixtures
44-
```
45-
46-
### Feature Architecture
47-
48-
Each feature follows feature slice architecture patterns with four layers:
49-
50-
- **components/** - UI components, presentational and decoupled from business logic (application) and router state. Data access is only through `providers/`.
51-
- **application/** - Business logic, portable state management (stores, FSMs, form validation), custom hooks. Should not depend on router state or external APIs directly (only through `providers/`).
52-
- **providers/** - Hook composition and data access gateway for the feature slice. Exposes query hooks, mutations, loaders, and DTOs sourced from `src/lib/api/`. Library-specific code (React Query, etc.) must not leak beyond this layer.
53-
- **models/** - Domain type definitions, utilities, and type mapping functions.
54-
55-
**Dependency rule:** `components/` and `application/` import from `models/` and `providers/`. `providers/` and `models/` have no internal feature dependencies.
56-
57-
### API Layer
58-
59-
`src/lib/api/` is the global home for all HTTP logic: `queryOptions` factories, loaders, mutation hooks, query keys, and DTOs, organised by resource. Query files expose `queryOptions` factories (no `useQuery` hooks — hook composition belongs in `providers/`). Feature `providers/` compose hooks on top of those factories and re-export them for feature slice. New API logic always goes in `src/lib/api/` first, then gets exposed through the relevant feature's `providers/`.
60-
61-
### Key Patterns
62-
63-
| Pattern | Description |
64-
| --------------------- | ---------------------------------------------------------------- |
65-
| Co-location | Related files (component + story + test) grouped together |
66-
| MSW handlers | API mocking centralized in `test-lib/handlers/` |
67-
| Fixture pattern | Test data generation in `test-lib/fixtures/` |
68-
| Strong typing | Comprehensive TypeScript with branded types |
69-
| Component Composition | Features export composed components for pages |
70-
| Centralized API | All API logic in `src/lib/api/` with endpoint-based organization |
71-
72-
### State Management
73-
74-
| Type | Use Case |
75-
| -------------- | ------------------------------------------------------------------------------------------------------------- |
76-
| XState | State orchestration with explicit states and constrained transitions (e.g., auth flows, multi-step processes) |
77-
| Zustand stores | Complex local state (auth, modals, etc.) |
78-
| React Query | Server state and caching |
79-
| React state | Simple component state |
80-
81-
XState is preferred for business processes where states must be explicit and transitions constrained.
82-
83-
### Routing
84-
85-
- **File-based routing** - Pages in `src/pages/` with corresponding loaders
86-
- **Strong typing** - Route paths defined in `lib/router/routes.ts`
87-
- **Lazy loading** - Components loaded on demand with error boundaries
88-
89-
### Error Handling
90-
91-
- Using `react-error-boundary` for unexpected component runtime errors
92-
93-
### Build Optimization
94-
95-
- Lazy loading and code splitting based on `react-router`
96-
- Using direct imports instead of default exports
28+
Read `docs/architecture.md` for full project structure, state management guide, and routing patterns.

‎.github/instructions/code-style.instructions.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
applyTo: "**"
3+
---
4+
5+
# Code Style
6+
7+
## File Naming
8+
9+
| Category | Convention | Example |
10+
| ------------------ | ---------- | ----------------------------------- |
11+
| React components | PascalCase | `ProductCard.tsx`, `SignInForm.tsx` |
12+
| Storybook stories | PascalCase | `ProductCard.stories.tsx` |
13+
| Page Objects (E2E) | PascalCase | `ProductListPage.ts` |
14+
| Everything else | kebab-case | `auth-store.ts`, `use-counter.ts` |
15+
16+
Test files mirror source: `use-counter.ts` → `use-counter.test.ts`.
17+
18+
## TypeScript
19+
20+
- Use `unknown` instead of `any` — refactor or use type guards instead of type assertions (`as Type`)
21+
- Prefer solving problems with TypeScript types over runtime code when possible
22+
- Use named exports exclusively
23+
24+
## React
25+
26+
- Split complex `useEffect` into smaller, focused effects
27+
- Prefer composition with `children` prop over prop drilling
28+
- Extract business logic to custom hooks or functions — keep components presentational
29+
30+
## General
31+
32+
- Prefer immutability and pure functions — return new objects/arrays instead of mutating
33+
- Follow lint/style configs (`.prettierrc`, `.eslint.config.mjs`) — do not reformat to any other style

‎.github/instructions/copilot-instructions.md‎

Lines changed: 57 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -2,66 +2,70 @@
22
applyTo: "**"
33
---
44

5-
## Golden Rules
5+
# Project
66

7-
- When unsure about implementation details, requirements, or business logic, ALWAYS consult the developer rather than making assumptions.
8-
- We optimize for maintainability over cleverness. When in doubt, choose the boring solution.
9-
- When reporting information, options, pros/cons, or summarizing changes, be extremely concise—sacrifice grammar if needed.
10-
- Keep plans and documentation concise yet detailed—prioritize information density over formatting.
7+
React SPA built with Vite using feature slice architecture with clean architecture principles.
118

12-
| # | AI _may_ do | AI _must NOT_ do |
13-
| --- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
14-
| G-0 | Ask for clarification when unsure about project-specific details | Write changes without context for a feature/decision |
15-
| G-1 | Generate code in `src/features/`, `src/lib/api/`, `src/pages/`, or explicitly pointed files | Touch files beyond `src` and `e2e` without request; modify existing tests |
16-
| G-2 | Add/update `AIDEV-NOTE:` anchor comments near non-trivial code (exception to "no comments" rule) | Delete or mangle existing `AIDEV-` comments |
17-
| G-3 | Follow lint/style configs (`.prettierrc`, `.eslint.config.mjs`) | Re-format code to any other style |
18-
| G-4 | For changes >300 LOC or >3 files, ask for confirmation | Refactor large modules without human guidance |
19-
| G-5 | Stay within current task context; inform dev if fresh start needed | Continue work from prior prompt after "new task" |
20-
| G-6 | Modify API contracts only with explicit approval and documentation | Change API contracts without approval |
21-
| G-7 | Use git commands only when explicitly requested | Stage, commit, or push without explicit request |
9+
## Stack
2210

23-
> **Note:** Rules G-3, G-4, and G-7 primarily apply to Agent mode when Copilot makes autonomous changes.
11+
TypeScript SPA. React 19, Vite 7, React Router 7, TanStack Query, Zustand, XState, Chakra UI, i18next. Testing: Vitest, Storybook, Playwright, MSW.
2412

25-
## Workflow Guidelines
13+
## Commands
2614

27-
### When working on complex tasks
15+
- `pnpm dev` — start dev server (port 5173)
16+
- `pnpm lint --fix` — lint and auto-fix
17+
- `pnpm test` — all tests (unit + storybook)
18+
- `pnpm test:e2e` — Playwright E2E (headless)
19+
- `pnpm storybook` — component dev (port 6006)
2820

29-
- Break down work into clear, incremental steps
30-
- In Plan mode, Copilot will propose an implementation plan for review
31-
- In Agent mode, follow the task incrementally with clear checkpoints
32-
- Update relevant `AIDEV-*` anchor comments as you work
21+
Package manager: PNPM only. Path alias: `@/*` → `src/`.
3322

34-
### Context Usage
23+
## Core Principles
3524

36-
- **Locate Anchors First**: Before editing code, check for existing `AIDEV-*` anchors in relevant files/subdirectories using grep. [Important]
37-
- **Handle Insufficient Information**: If context is unclear, ask: "Please provide '[specific file/detail]' or clarify expected behavior."
25+
- **Simplicity first** — make every change as simple as possible, minimize code impact, choose the boring solution
26+
- When unsure about requirements or business logic, ask the developer — never assume
27+
- For changes >300 LOC or >3 files, ask for confirmation before proceeding
28+
- Modify API contracts only with explicit approval
29+
- Use git commands only when explicitly requested
30+
- Stay within current task context — inform dev if a fresh start is needed
31+
- Keep reports, options, and summaries extremely concise — prioritize information density
3832

39-
## Commands
33+
## Workflow
34+
35+
**1. Plan Mode Default**
36+
37+
- Enter plan mode for any non-trivial task (3+ steps or architectural decisions)
38+
- If something goes wrong, STOP and re-plan immediately — do not keep pushing
39+
- For complex features, write or request a spec before implementation
40+
- Use plan mode for verification steps, not just building
41+
42+
**2. Self-Improvement Loop**
43+
44+
- After any correction, capture the pattern in `tasks/lessons.md` and write a rule to prevent recurrence
45+
- Review `tasks/lessons.md` at the start of each session
46+
- Ruthlessly iterate on lessons until the mistake rate drops
47+
48+
**3. Verification Before Done**
49+
50+
- Never mark a task complete without proving it works
51+
- Run tests, check logs, and demonstrate correctness
52+
- Ask: "Would a staff engineer approve this?"
53+
54+
**4. Demand Elegance (Balanced)**
55+
56+
- For non-trivial changes, ask: "Is there a more elegant solution?"
57+
- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
58+
- Skip this for simple fixes — do not over-engineer
59+
60+
**5. Autonomous Bug Fixing**
61+
62+
- When given a bug report: just fix it
63+
- Use logs, errors, and failing tests to diagnose — require zero context switching from the developer
64+
65+
## Conventions
66+
67+
- Use `AIDEV-NOTE:`, `AIDEV-TODO:`, `AIDEV-QUESTION:` anchors near non-trivial code (exception to no-comments rule)
68+
69+
## Reference Docs
4070

41-
**Package Manager:** PNPM only (`pnpm`, not `npm` or `yarn`)
42-
43-
### Essential Commands
44-
45-
| Command | Description |
46-
| ---------------------- | -------------------------------- |
47-
| `pnpm dev` | Start dev server (port 5173) |
48-
| `pnpm lint` | Run ESLint |
49-
| `pnpm lint --fix` | Fix lint errors |
50-
| `pnpm test` | Run all tests (unit + storybook) |
51-
| `pnpm test:unit` | Unit tests only |
52-
| `pnpm test:storybook` | Storybook tests only |
53-
| `pnpm test:e2e` | E2E tests (Playwright, headless) |
54-
| `pnpm test:e2e:ui` | E2E interactive web UI mode |
55-
| `pnpm test:e2e:headed` | E2E with visible browser |
56-
| `pnpm test:e2e:debug` | E2E debug mode |
57-
| `pnpm test:e2e:report` | Open E2E HTML report |
58-
| `pnpm test:coverage` | Tests with coverage report |
59-
| `pnpm storybook` | Storybook (port 6006) |
60-
61-
### CI Commands
62-
63-
| Command | Description |
64-
| ------------------------ | -------------------------------- |
65-
| `pnpm test:unit:ci` | Unit tests with coverage/reports |
66-
| `pnpm test:storybook:ci` | Storybook tests with reports |
67-
| `pnpm test:e2e:ci` | E2E tests with reports |
71+
- Read `docs/architecture.md` when adding features, modifying project structure, or making architectural decisions

‎.github/instructions/development.instructions.md‎

Lines changed: 0 additions & 58 deletions
This file was deleted.

0 commit comments

Comments
 (0)