Skip to content

Commit 5492517

Browse files
bartstcbartstc
authored
Merge pull request #45 from bartstc/chore/refactor-instructions
chore: refactor AI instruction files into modular documentation
2 parents 94f5ccf + f3c80c8 commit 5492517

10 files changed

Lines changed: 382 additions & 355 deletions

‎.claude/docs/architecture.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Architecture
2+
3+
## Core Technologies
4+
5+
- **React 19** with TypeScript
6+
- **Vite 7** for build tooling
7+
- **React Query (TanStack Query)** for data fetching
8+
- **React Router 7** for routing
9+
- **i18next** for internationalization
10+
- **MSW 2** for API mocking
11+
- **Vitest 4** for unit and component testing
12+
- **Storybook 10** for component development
13+
- **Playwright** for E2E testing
14+
- **Zustand** for state management
15+
- **Chakra UI** for components
16+
17+
## Project Structure
18+
19+
```
20+
.
21+
├── e2e/ # End-to-end tests with Playwright
22+
└── src/
23+
├── app/ # App-level configuration (App.tsx, Providers.tsx)
24+
├── features/ # Feature modules using feature slice architecture
25+
│ ├── auth/ # Authentication feature
26+
│ ├── carts/ # Shopping cart feature
27+
│ ├── products/ # Product catalog feature
28+
├── lib/ # Shared libraries and utilities
29+
│ ├── api/ # Centralized API layer (queries, commands, DTOs)
30+
│ ├── components/ # Reusable UI components
31+
│ ├── http/ # HTTP client and error handling
32+
│ ├── i18n/ # Internationalization setup
33+
│ ├── router/ # Routing utilities
34+
│ └── theme/ # Theme configuration
35+
├── pages/ # Route-level page components composing feature components & logic
36+
└── test-lib/ # Testing utilities and fixtures
37+
```
38+
39+
## Feature Architecture
40+
41+
Each feature follows feature slice architecture patterns with three layers:
42+
43+
- **presentation/** - UI components, UI-wise hooks
44+
- **application/** - Business logic, state management, logic-wise hooks
45+
- **infrastructure/** - Data fetching, external APIs, contracts, DTOs
46+
- **types/** - Type definitions
47+
48+
## Key Patterns
49+
50+
| Pattern | Description |
51+
| --------------------- | ---------------------------------------------------------------- |
52+
| Co-location | Related files (component + story + test) grouped together |
53+
| MSW handlers | API mocking centralized in `test-lib/handlers/` |
54+
| Fixture pattern | Test data generation in `test-lib/fixtures/` |
55+
| Strong typing | Comprehensive TypeScript with branded types |
56+
| Component Composition | Features export composed components for pages |
57+
| Centralized API | All API logic in `src/lib/api/` with endpoint-based organization |
58+
59+
## State Management
60+
61+
| Type | Use Case |
62+
| -------------- | ------------------------------------------------------------------------------------------------------------- |
63+
| XState | State orchestration with explicit states and constrained transitions (e.g., auth flows, multi-step processes) |
64+
| Zustand stores | Complex local state (auth, modals, etc.) |
65+
| React Query | Server state and caching |
66+
| React state | Simple component state |
67+
68+
XState is preferred for business processes where states must be explicit and transitions constrained.
69+
70+
## Routing
71+
72+
- **File-based routing** - Pages in `src/pages/` with corresponding loaders
73+
- **Strong typing** - Route paths defined in `lib/router/routes.ts`
74+
- **Lazy loading** - Components loaded on demand with error boundaries
75+
76+
## Error Handling
77+
78+
- Using `react-error-boundary` for unexpected component runtime errors
79+
80+
## Build Optimization
81+
82+
- Lazy loading and code splitting based on `react-router`
83+
- Using direct imports instead of default exports

‎.claude/docs/code-style.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Code Style
2+
3+
## General
4+
5+
- Preserve original structure and formatting of referenced files
6+
- Follow existing patterns in the codebase
7+
- Follow functional programming principles - prefer immutability and pure functions
8+
- Treat data as immutable - return new objects/arrays instead of mutating
9+
10+
## TypeScript
11+
12+
- Avoid `any` type - use `unknown` if necessary
13+
- Avoid type assertions (`value as Type`) - prefer type guards or refactoring
14+
- Prefer solving problems with TypeScript types over runtime code when possible
15+
16+
## React
17+
18+
- Split complex `useEffect` into smaller, focused effects
19+
- Prefer composition over prop drilling - use `children` prop and component composition
20+
- Isolate business logic from presentation - extract logic to custom hooks or separate functions

‎.claude/docs/testing.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Testing
2+
3+
## Testing Strategy
4+
5+
| Type | Location | Tool |
6+
| --------------- | ----------------------------------------- | ---------- |
7+
| Unit tests | `.test.ts` / `.test.tsx` alongside source | Vitest |
8+
| Storybook tests | `.stories.tsx` alongside components | Storybook |
9+
| E2E tests | `e2e/` directory | Playwright |
10+
| API mocking | `test-lib/handlers/` | MSW |
11+
| Test fixtures | `test-lib/fixtures/` | Custom |
12+
13+
## AI Boundaries
14+
15+
| What | AI CAN Do | AI MUST NOT Do |
16+
| -------------- | ----------------------- | ------------------------ |
17+
| Implementation | Generate business logic | Touch test files |
18+
| Test Planning | Suggest test scenarios | Write test code |
19+
| Debugging | Analyze test failures | Modify test expectations |
20+
21+
## Test Case Scenarios
22+
23+
**Prioritize tests for:**
24+
25+
- Happy path scenarios with realistic data
26+
- Error conditions users might encounter
27+
- Edge cases that affect business logic (not just coverage)
28+
29+
**Avoid redundant edge cases:**
30+
31+
- Empty arrays when "not found" is already tested
32+
- `undefined` collections when type system prevents this
33+
- Multiple variations of the same error condition
34+
35+
Each test should verify **distinct behavior**, not different ways to trigger the same code path.

‎.claude/docs/workflow.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Workflow
2+
3+
## Plan & Review
4+
5+
### Before Starting Work
6+
7+
1. Always start with planning (unless requested not to)
8+
2. Write plan to `.claude/tasks/TASK_NAME.md` - never present in chat
9+
3. Plan should include: detailed implementation steps, reasoning, broken-down tasks
10+
4. Research external knowledge/packages if needed (use Task tool)
11+
5. Think MVP - don't over-plan
12+
6. Ask for review before implementation
13+
14+
### While Implementing
15+
16+
- Update `.claude/tasks/TASK_NAME.md` as you work
17+
- After completing tasks, append detailed change descriptions for handover
18+
- Use `pnpm lint --fix` for lint errors/warnings
19+
20+
## Scanning Repository
21+
22+
- **Use Only Referenced Files**: Analyze using only files mentioned in the prompt
23+
- **Locate Anchors First**: Check for `AIDEV-*` anchors in relevant subdirectories before scanning
24+
- **No Broad Scans**: Avoid scanning unreferenced files unless explicitly permitted
25+
- **Handle Insufficient Information**: State "Insufficient information in provided files" and suggest specific files needed
26+
27+
## Anchor Comments
28+
29+
Use `AIDEV-NOTE:`, `AIDEV-TODO:`, or `AIDEV-QUESTION:` for inline knowledge that can be grep'd.
30+
31+
**Rules:**
32+
33+
- Keep concise (≤ 120 chars)
34+
- Grep for existing anchors before scanning files
35+
- Update anchors when modifying associated code
36+
- Never remove without explicit human instruction
37+
38+
**Add anchors when code is:**
39+
40+
- Too complex
41+
- Very important
42+
- Confusing
43+
- Could have a bug
44+
45+
**Note:** Anchor comments are an explicit exception to the "no comments unless requested" rule.

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

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
applyTo: "**"
3+
---
4+
5+
## Architecture Overview
6+
7+
React SPA built with Vite using feature slice architecture with clean architecture principles.
8+
9+
### Core Technologies
10+
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
23+
24+
### Project Structure
25+
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 three layers:
49+
50+
- **presentation/** - UI components, UI-wise hooks
51+
- **application/** - Business logic, state management, logic-wise hooks
52+
- **infrastructure/** - Data fetching, external APIs, contracts, DTOs
53+
- **types/** - Type definitions
54+
55+
### Key Patterns
56+
57+
| Pattern | Description |
58+
| --------------------- | ---------------------------------------------------------------- |
59+
| Co-location | Related files (component + story + test) grouped together |
60+
| MSW handlers | API mocking centralized in `test-lib/handlers/` |
61+
| Fixture pattern | Test data generation in `test-lib/fixtures/` |
62+
| Strong typing | Comprehensive TypeScript with branded types |
63+
| Component Composition | Features export composed components for pages |
64+
| Centralized API | All API logic in `src/lib/api/` with endpoint-based organization |
65+
66+
### State Management
67+
68+
| Type | Use Case |
69+
| -------------- | ------------------------------------------------------------------------------------------------------------- |
70+
| XState | State orchestration with explicit states and constrained transitions (e.g., auth flows, multi-step processes) |
71+
| Zustand stores | Complex local state (auth, modals, etc.) |
72+
| React Query | Server state and caching |
73+
| React state | Simple component state |
74+
75+
XState is preferred for business processes where states must be explicit and transitions constrained.
76+
77+
### Routing
78+
79+
- **File-based routing** - Pages in `src/pages/` with corresponding loaders
80+
- **Strong typing** - Route paths defined in `lib/router/routes.ts`
81+
- **Lazy loading** - Components loaded on demand with error boundaries
82+
83+
### Error Handling
84+
85+
- Using `react-error-boundary` for unexpected component runtime errors
86+
87+
### Build Optimization
88+
89+
- Lazy loading and code splitting based on `react-router`
90+
- Using direct imports instead of default exports

0 commit comments

Comments
 (0)