start-vibing 2.0.35 → 2.0.38
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/template/CLAUDE.md +889 -65
package/package.json
CHANGED
package/template/CLAUDE.md
CHANGED
|
@@ -1,6 +1,70 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Project Rules
|
|
2
2
|
|
|
3
|
-
> **
|
|
3
|
+
> **CHARACTER LIMIT**: Max 40,000 chars. Validate with `wc -m CLAUDE.md` before commit.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Last Change
|
|
8
|
+
|
|
9
|
+
**Branch:** main
|
|
10
|
+
**Date:** YYYY-MM-DD
|
|
11
|
+
**Summary:** Initial setup with start-vibing.
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## 30 Seconds Overview
|
|
16
|
+
|
|
17
|
+
UPDATE THIS WITH YOUR PROJECT DESCRIPTION
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Stack
|
|
22
|
+
|
|
23
|
+
| Component | Technology |
|
|
24
|
+
| ---------- | -------------------------- |
|
|
25
|
+
| Runtime | Bun / Node.js |
|
|
26
|
+
| Language | TypeScript **strict mode** |
|
|
27
|
+
| Validation | Zod |
|
|
28
|
+
| Database | MongoDB + Mongoose |
|
|
29
|
+
| Testing | Vitest + Playwright |
|
|
30
|
+
| UI | React + Tailwind + shadcn |
|
|
31
|
+
| Data | TanStack Query + Sonner |
|
|
32
|
+
| Forms | react-hook-form + Zod |
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Architecture
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
project-root/
|
|
40
|
+
├── CLAUDE.md # THIS FILE - project rules (40k char max)
|
|
41
|
+
├── .claude/
|
|
42
|
+
│ ├── agents/ # 82 specialized agents in 14 categories
|
|
43
|
+
│ ├── hooks/ # stop-validator, user-prompt-submit
|
|
44
|
+
│ ├── scripts/ # validation scripts
|
|
45
|
+
│ ├── skills/ # 22 skill systems
|
|
46
|
+
│ └── config/ # project configuration
|
|
47
|
+
├── src/
|
|
48
|
+
│ ├── app/ # Next.js app router
|
|
49
|
+
│ │ ├── (marketing)/ # Route group - public pages
|
|
50
|
+
│ │ ├── (app)/ # Route group - authenticated
|
|
51
|
+
│ │ │ └── dashboard/
|
|
52
|
+
│ │ │ ├── page.tsx
|
|
53
|
+
│ │ │ └── _components/ # Page-specific components
|
|
54
|
+
│ │ ├── layout.tsx # Root layout with providers
|
|
55
|
+
│ │ └── loading.tsx # Global loading skeleton
|
|
56
|
+
│ ├── components/
|
|
57
|
+
│ │ ├── ui/ # shadcn primitives
|
|
58
|
+
│ │ ├── layout/ # Header, Sidebar, Footer
|
|
59
|
+
│ │ ├── shared/ # Cross-feature components
|
|
60
|
+
│ │ └── providers.tsx # Context providers (client)
|
|
61
|
+
│ └── lib/
|
|
62
|
+
│ ├── utils.ts # cn utility (MANDATORY)
|
|
63
|
+
│ └── api/ # axios instances
|
|
64
|
+
├── types/ # ALL TypeScript interfaces (MANDATORY)
|
|
65
|
+
├── tests/ # Test files
|
|
66
|
+
└── docs/ # Documentation
|
|
67
|
+
```
|
|
4
68
|
|
|
5
69
|
---
|
|
6
70
|
|
|
@@ -11,103 +75,863 @@
|
|
|
11
75
|
1. TODO LIST → ALWAYS create detailed todo list from prompt
|
|
12
76
|
2. RESEARCH → Run research agent for NEW features (MANDATORY)
|
|
13
77
|
3. AUDIT → Check docs from last audit OR run fresh audit
|
|
14
|
-
4.
|
|
78
|
+
4. BRANCH → Create feature/ | fix/ | refactor/ | test/
|
|
15
79
|
5. IMPLEMENT → Follow project rules + analyzer approval
|
|
16
80
|
6. DOCUMENT → Document ALL modified files (MANDATORY)
|
|
17
|
-
7.
|
|
18
|
-
8.
|
|
81
|
+
7. UPDATE → Update THIS FILE (CLAUDE.md) with session changes
|
|
82
|
+
8. QUALITY → Run typecheck && lint && test (Husky enforced)
|
|
83
|
+
9. VALIDATE → RUN: npx tsx .claude/hooks/stop-validator.ts (MANDATORY)
|
|
84
|
+
10. FINISH → Only after validator shows "ALL CHECKS PASSED"
|
|
19
85
|
```
|
|
20
86
|
|
|
21
|
-
> **CRITICAL:**
|
|
22
|
-
> **CRITICAL:** All documentation must reference commit hashes for audit trail.
|
|
23
|
-
> **CRITICAL:** Stop hook BLOCKS task completion if files not documented.
|
|
24
|
-
> **FALLBACK:** If Task tool fails to invoke an agent, READ the agent file directly from `.claude/agents/[agent-name].md` and follow its instructions manually.
|
|
87
|
+
> **CRITICAL:** Stop hook BLOCKS task completion if any validation fails.
|
|
25
88
|
|
|
26
89
|
---
|
|
27
90
|
|
|
28
|
-
##
|
|
91
|
+
## MANDATORY: Run Stop Validator Before Completing
|
|
29
92
|
|
|
30
|
-
|
|
93
|
+
> **YOU MUST run the stop-validator manually BEFORE attempting to complete ANY task.**
|
|
31
94
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
| `memory` | Persistent knowledge graph | Store/recall project patterns |
|
|
37
|
-
| `playwright` | Browser automation and E2E testing | UI testing, page verification |
|
|
38
|
-
| `nextjs-devtools` | Next.js specific development tools | Next.js projects only |
|
|
39
|
-
| `mongodb` | MongoDB database operations | Database queries, schema inspection |
|
|
95
|
+
```bash
|
|
96
|
+
# RUN THIS COMMAND before saying "task complete" or finishing work:
|
|
97
|
+
npx tsx .claude/hooks/stop-validator.ts
|
|
98
|
+
```
|
|
40
99
|
|
|
41
|
-
###
|
|
100
|
+
### Why This Is Required
|
|
42
101
|
|
|
43
|
-
|
|
44
|
-
- **ALWAYS** use `playwright` for E2E tests instead of manual browser testing
|
|
45
|
-
- **ALWAYS** check `memory` for existing patterns before creating new ones
|
|
46
|
-
- **NEVER** hardcode library APIs - query `context7` for current docs
|
|
102
|
+
The stop hook runs automatically but Claude often ignores its output. **Running manually ensures you see and fix ALL issues.**
|
|
47
103
|
|
|
48
|
-
|
|
104
|
+
### Validation Workflow
|
|
49
105
|
|
|
50
|
-
|
|
106
|
+
```
|
|
107
|
+
1. Finish implementation
|
|
108
|
+
2. RUN: npx tsx .claude/hooks/stop-validator.ts
|
|
109
|
+
3. If issues found → Fix them ONE BY ONE
|
|
110
|
+
4. RUN validator again after EACH fix
|
|
111
|
+
5. Only complete task when output shows "ALL CHECKS PASSED"
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### What It Validates
|
|
51
115
|
|
|
52
|
-
|
|
116
|
+
| Check | Requirement |
|
|
117
|
+
|-------|-------------|
|
|
118
|
+
| Branch | Must be on `main` (merged) |
|
|
119
|
+
| Git tree | Must be clean (committed) |
|
|
120
|
+
| CLAUDE.md | Must be updated with session changes |
|
|
121
|
+
| Documentation | All source files must be documented |
|
|
122
|
+
| Domains | Domain files must be updated |
|
|
53
123
|
|
|
54
|
-
|
|
55
|
-
| ---------------- | ----------------------------- | -------- |
|
|
56
|
-
| orchestrator | Coordinates entire workflow | 1 |
|
|
57
|
-
| analyzer | Analyzes change impact | 2 |
|
|
58
|
-
| research | Researches best practices | 3 |
|
|
59
|
-
| documenter | Creates/updates documentation | 3 |
|
|
60
|
-
| tester | Creates unit and E2E tests | 4 |
|
|
61
|
-
| security-auditor | Audits security (VETO POWER) | 5 |
|
|
62
|
-
| ui-ux-reviewer | Reviews UI/UX patterns | 6 |
|
|
63
|
-
| quality-checker | Runs quality gates | 7 |
|
|
64
|
-
| final-validator | Final validation (VETO POWER) | 8 |
|
|
65
|
-
| domain-updater | Updates domain knowledge | 9 |
|
|
66
|
-
| commit-manager | Manages commits (FINAL step) | 10 |
|
|
124
|
+
> **IMPORTANT:** If validator shows issues, create a TODO list and fix them in order. Do NOT try to complete the task until ALL checks pass.
|
|
67
125
|
|
|
68
126
|
---
|
|
69
127
|
|
|
70
|
-
## Stop Hook
|
|
128
|
+
## Stop Hook Validations
|
|
71
129
|
|
|
72
|
-
The
|
|
130
|
+
The stop hook runs when Claude is about to finish and **BLOCKS** if:
|
|
73
131
|
|
|
74
|
-
|
|
|
75
|
-
|
|
|
76
|
-
|
|
|
77
|
-
|
|
|
78
|
-
|
|
|
132
|
+
| Validation | Condition | Action Required |
|
|
133
|
+
| ------------- | ---------------------- | ---------------------------------------------- |
|
|
134
|
+
| Branch | NOT on main | Merge branch to main, then `git checkout main` |
|
|
135
|
+
| Git Tree | Uncommitted changes | Commit, merge to main, sync remote |
|
|
136
|
+
| CLAUDE.md | Not updated | Update Last Change (ANY file change triggers) |
|
|
137
|
+
| CLAUDE.md | Missing sections | Add required sections |
|
|
138
|
+
| CLAUDE.md | Exceeds 40k chars | Compact the file |
|
|
139
|
+
| Documentation | Source files undoc | Run documenter agent |
|
|
79
140
|
|
|
80
141
|
---
|
|
81
142
|
|
|
82
|
-
##
|
|
143
|
+
## CLAUDE.md Update Rules
|
|
144
|
+
|
|
145
|
+
> **NOT just Last Change - also document FLOW changes, architecture, and feature core.**
|
|
146
|
+
|
|
147
|
+
### When to Update CLAUDE.md
|
|
148
|
+
|
|
149
|
+
| Change Type | What to Update |
|
|
150
|
+
|-------------|----------------|
|
|
151
|
+
| Any file change | Last Change section (branch, date, summary) |
|
|
152
|
+
| New feature added | Add to 30s Overview, Architecture if needed |
|
|
153
|
+
| Flow changed | Update Workflow section or add new section |
|
|
154
|
+
| New pattern established | Add to relevant section (UI, API, etc.) |
|
|
155
|
+
| Gotcha discovered | Add to NRY or FORBIDDEN sections |
|
|
156
|
+
| New config added | Update Configuration section |
|
|
157
|
+
|
|
158
|
+
### Last Change Format (MANDATORY)
|
|
159
|
+
|
|
160
|
+
```markdown
|
|
161
|
+
## Last Change
|
|
162
|
+
|
|
163
|
+
**Branch:** feature/example-feature
|
|
164
|
+
**Date:** YYYY-MM-DD
|
|
165
|
+
**Summary:** 1-2 sentences describing WHAT changed and WHY.
|
|
166
|
+
```
|
|
83
167
|
|
|
84
|
-
|
|
168
|
+
### Flow Documentation
|
|
85
169
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
| `domain-mapping.json` | File patterns to domains |
|
|
170
|
+
When implementing features that change how the app works:
|
|
171
|
+
|
|
172
|
+
1. **Document the flow** in relevant section (or create new)
|
|
173
|
+
2. **Explain what each part does** (architecture impact)
|
|
174
|
+
3. **Record gotchas** in NRY/FORBIDDEN if discovered
|
|
175
|
+
4. **Update domain docs** via domain-updater agent
|
|
93
176
|
|
|
94
177
|
---
|
|
95
178
|
|
|
96
179
|
## Critical Rules
|
|
97
180
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
181
|
+
### HTTP Requests (MANDATORY)
|
|
182
|
+
|
|
183
|
+
| Rule | Implementation |
|
|
184
|
+
|------|----------------|
|
|
185
|
+
| Use axios ONLY | Never `fetch()` or raw `axios` |
|
|
186
|
+
| `withCredentials: true` | ALWAYS for cookies/sessions |
|
|
187
|
+
| Extend base instance | Create `lib/api/axios.ts` |
|
|
188
|
+
| Type responses | `api.get<User>('/users')` |
|
|
189
|
+
| Centralize errors | Use interceptors |
|
|
190
|
+
|
|
191
|
+
> **See `.claude/CLAUDE.md`** for full axios setup template.
|
|
192
|
+
|
|
193
|
+
### Path Aliases (MANDATORY)
|
|
194
|
+
|
|
195
|
+
| Alias | Maps To | Use For |
|
|
196
|
+
| ---------- | ------------------- | ------------- |
|
|
197
|
+
| `$types/*` | `./types/*` | Type defs |
|
|
198
|
+
| `@common` | `./common/index.ts` | Logger, utils |
|
|
199
|
+
| `@db` | `./common/db/` | DB connection |
|
|
200
|
+
|
|
201
|
+
> **NEVER** use `@types/` (reserved by TypeScript)
|
|
202
|
+
|
|
203
|
+
### Types Location
|
|
204
|
+
|
|
205
|
+
- **ALL** interfaces/types MUST be in `types/` folder
|
|
206
|
+
- **NEVER** define types in `src/` files
|
|
207
|
+
- **EXCEPTION:** Zod inferred types and Mongoose Documents
|
|
208
|
+
|
|
209
|
+
### TypeScript Strict
|
|
210
|
+
|
|
211
|
+
```typescript
|
|
212
|
+
process.env['VARIABLE']; // CORRECT (bracket notation)
|
|
213
|
+
source: 'listed' as const; // CORRECT (literal type)
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## Quality Gates
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
bun run typecheck # MUST pass
|
|
222
|
+
bun run lint # MUST pass
|
|
223
|
+
bun run test # MUST pass
|
|
224
|
+
docker compose build # MUST pass
|
|
225
|
+
```
|
|
103
226
|
|
|
104
227
|
---
|
|
105
228
|
|
|
106
|
-
##
|
|
229
|
+
## Commit Format
|
|
230
|
+
|
|
231
|
+
```
|
|
232
|
+
[type]: [description]
|
|
233
|
+
|
|
234
|
+
- Detail 1
|
|
235
|
+
- Detail 2
|
|
236
|
+
|
|
237
|
+
Generated with Claude Code
|
|
238
|
+
Co-Authored-By: Claude <noreply@anthropic.com>
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
Types: `feat`, `fix`, `refactor`, `docs`, `chore`
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
## FORBIDDEN Actions
|
|
246
|
+
|
|
247
|
+
| Action | Reason |
|
|
248
|
+
| ------------------------------ | ---------------------------- |
|
|
249
|
+
| Skip stop-validator | MUST run `npx tsx .claude/hooks/stop-validator.ts` before completing |
|
|
250
|
+
| Write in non-English | ALL code/docs MUST be in EN |
|
|
251
|
+
| Skip typecheck | Catches runtime errors |
|
|
252
|
+
| Relative imports (shared) | Breaks when files move |
|
|
253
|
+
| Use `@types/` alias | Reserved by TypeScript |
|
|
254
|
+
| Use `any` type | Defeats strict mode |
|
|
255
|
+
| Skip docker build test | May fail in production |
|
|
256
|
+
| Define types in `src/` | Must be in `types/` |
|
|
257
|
+
| Skip research for new features | Leads to outdated patterns |
|
|
258
|
+
| Skip todo list creation | Loses track of tasks |
|
|
259
|
+
| Make responsive UI only | Must be separate UIs |
|
|
260
|
+
| Commit directly to main | Stop hook will BLOCK |
|
|
261
|
+
| Skip documenter agent | Stop hook will BLOCK |
|
|
262
|
+
| Leave files undocumented | Stop hook will BLOCK |
|
|
263
|
+
| Finish on feature branch | Stop hook will BLOCK |
|
|
264
|
+
| Stack Last Change entries | Keep only the LATEST |
|
|
265
|
+
| Use Cards on mobile | Waste space in flex-col |
|
|
266
|
+
| Edit JSX without UI agents | MUST run ui-mobile/tablet/desktop |
|
|
267
|
+
| Skip planning for features | Use EnterPlanMode first |
|
|
268
|
+
| Skip domain documentation | MUST update domains/*.md |
|
|
269
|
+
| Only update CLAUDE.md | Domains are detail, CLAUDE.md is summary |
|
|
270
|
+
| Skip flow documentation | Document architecture changes in CLAUDE.md |
|
|
271
|
+
| Use MUI/Chakra | Use shadcn/ui + Radix for personality control |
|
|
272
|
+
| Neumorphism on forms | Accessibility issues, use Glassmorphism |
|
|
273
|
+
| Scroll animations on dashboard | Use only on landing/marketing pages |
|
|
274
|
+
| 3D elements on mobile | Performance issues, use sparingly |
|
|
275
|
+
| Masonry grid on mobile | Use vertical lists instead |
|
|
276
|
+
| Mix animation libraries | Pick one primary (Framer or GSAP) |
|
|
277
|
+
| Wildcard icon imports | Use named imports (`import { X } from 'lucide-react'`) |
|
|
278
|
+
| React Icons in production | Use Lucide + Simple Icons directly |
|
|
279
|
+
| Files > 400 lines | MUST split into smaller components |
|
|
280
|
+
| Page components in /components | Use `app/[page]/_components/` |
|
|
281
|
+
| Skip cn utility | MUST use clsx + tailwind-merge |
|
|
282
|
+
| 'use client' at top level | Push to leaf components only |
|
|
283
|
+
| Waterfall data fetching | Use Promise.all() for parallel |
|
|
284
|
+
| Skip loading.tsx | Add skeleton loaders for data pages |
|
|
285
|
+
|
|
286
|
+
---
|
|
287
|
+
|
|
288
|
+
## UI Architecture (MANDATORY)
|
|
289
|
+
|
|
290
|
+
> Web apps MUST have **separate UIs** for each platform, NOT just "responsive design".
|
|
291
|
+
|
|
292
|
+
| Platform | Layout |
|
|
293
|
+
| ----------------- | ------------------------------------------- |
|
|
294
|
+
| Mobile (375px) | Full-screen modals, bottom nav, touch-first |
|
|
295
|
+
| Tablet (768px) | Condensed dropdowns, hybrid nav |
|
|
296
|
+
| Desktop (1280px+) | Sidebar left, top navbar with search |
|
|
297
|
+
|
|
298
|
+
### JSX Editing = UI Agents (MANDATORY)
|
|
299
|
+
|
|
300
|
+
ANY task that edits `.tsx` or `.jsx` files MUST invoke UI agents:
|
|
301
|
+
|
|
302
|
+
```
|
|
303
|
+
ui-mobile + ui-tablet + ui-desktop (run in PARALLEL)
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
---
|
|
307
|
+
|
|
308
|
+
## UI/UX Design Rules
|
|
309
|
+
|
|
310
|
+
### Mobile FORBIDDEN Patterns
|
|
311
|
+
|
|
312
|
+
| Pattern | Problem | Use Instead |
|
|
313
|
+
|---------|---------|-------------|
|
|
314
|
+
| Cards in flex-col | Waste vertical space, poor scanning | Compact lists with dividers |
|
|
315
|
+
| Card grids | Too cramped, hard to tap | Full-width list items |
|
|
316
|
+
| Nested cards | Confusing hierarchy | Flat structure |
|
|
317
|
+
| Multiple CTAs per card | Touch confusion | Single primary action |
|
|
318
|
+
|
|
319
|
+
### Design Principles
|
|
320
|
+
|
|
321
|
+
| Platform | Density | Navigation | Actions |
|
|
322
|
+
|----------|---------|------------|---------|
|
|
323
|
+
| Mobile | LOW - space for touch | Bottom tab bar | Bottom sheet |
|
|
324
|
+
| Tablet | MEDIUM - hybrid | Side + top | Context menus |
|
|
325
|
+
| Desktop | HIGH - data dense | Fixed sidebar | Inline + hover |
|
|
326
|
+
|
|
327
|
+
### Component Choices
|
|
328
|
+
|
|
329
|
+
```
|
|
330
|
+
Mobile: Lists > Cards, Sheets > Modals, Tabs > Dropdowns
|
|
331
|
+
Tablet: Collapsible cards, Split views, Floating actions
|
|
332
|
+
Desktop: Data tables, Multi-column forms, Keyboard shortcuts
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
---
|
|
336
|
+
|
|
337
|
+
## Design System Reference
|
|
338
|
+
|
|
339
|
+
> **Full docs in**: `.claude/skills/research-cache/cache/` (after research agent runs)
|
|
340
|
+
|
|
341
|
+
### Required Libraries
|
|
342
|
+
|
|
343
|
+
```bash
|
|
344
|
+
# Core utilities (MANDATORY)
|
|
345
|
+
bun add clsx tailwind-merge class-variance-authority
|
|
346
|
+
bun add -D tailwindcss-animate
|
|
347
|
+
|
|
348
|
+
# Animation & feedback
|
|
349
|
+
bun add @formkit/auto-animate framer-motion sonner
|
|
350
|
+
|
|
351
|
+
# Skeleton loaders
|
|
352
|
+
bun add react-loading-skeleton
|
|
353
|
+
|
|
354
|
+
# Copy-paste from: magicui.design, ui.aceternity.com, hover.dev
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
### The `cn` Utility (MANDATORY)
|
|
358
|
+
|
|
359
|
+
```typescript
|
|
360
|
+
// lib/utils.ts - MUST HAVE in every project
|
|
361
|
+
import { clsx, type ClassValue } from 'clsx';
|
|
362
|
+
import { twMerge } from 'tailwind-merge';
|
|
363
|
+
|
|
364
|
+
export const cn = (...inputs: ClassValue[]) => twMerge(clsx(inputs));
|
|
365
|
+
|
|
366
|
+
// Usage
|
|
367
|
+
<div className={cn('base', condition && 'conditional', userClassName)} />
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
---
|
|
371
|
+
|
|
372
|
+
## Icon Libraries (MANDATORY)
|
|
373
|
+
|
|
374
|
+
| Library | Use For | Icons | Import |
|
|
375
|
+
|---------|---------|-------|--------|
|
|
376
|
+
| **Lucide React** | UI icons (shadcn default) | 1,600+ | `import { Camera } from 'lucide-react'` |
|
|
377
|
+
| **Simple Icons** | Brand logos ONLY | 3,150+ | `import { SiReact } from '@icons-pack/react-simple-icons'` |
|
|
378
|
+
| **Heroicons** | Tailwind projects | 290+ | `import { BeakerIcon } from '@heroicons/react/24/outline'` |
|
|
379
|
+
|
|
380
|
+
### Icon Rules
|
|
381
|
+
|
|
382
|
+
```typescript
|
|
383
|
+
// ✅ CORRECT: Named imports (tree-shakable, ~1KB per icon)
|
|
384
|
+
import { Camera, User, Settings } from 'lucide-react';
|
|
385
|
+
|
|
386
|
+
// ❌ FORBIDDEN: Wildcard imports (bundles ALL icons, +30KB)
|
|
387
|
+
import * as Icons from 'lucide-react';
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
### Icon Styling
|
|
391
|
+
|
|
392
|
+
```tsx
|
|
393
|
+
<Camera size={24} /> // Size prop
|
|
394
|
+
<User className="w-6 h-6 text-blue-500" /> // Tailwind classes
|
|
395
|
+
<Settings strokeWidth={1.5} /> // Stroke width
|
|
396
|
+
<button aria-label="Take photo"><Camera /></button> // Accessibility
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
---
|
|
400
|
+
|
|
401
|
+
## Aesthetic Libraries
|
|
402
|
+
|
|
403
|
+
| Library | Purpose | When |
|
|
404
|
+
|---------|---------|------|
|
|
405
|
+
| **clsx + tailwind-merge** | className management | ALWAYS |
|
|
406
|
+
| **class-variance-authority** | Component variants | Reusable components |
|
|
407
|
+
| **tailwindcss-animate** | Micro-interactions | Animations |
|
|
408
|
+
| **react-loading-skeleton** | Loading states | Data fetching |
|
|
409
|
+
| **Magic UI** | Animated components | Landing pages |
|
|
410
|
+
|
|
411
|
+
### CVA for Component Variants
|
|
412
|
+
|
|
413
|
+
```typescript
|
|
414
|
+
import { cva, type VariantProps } from 'class-variance-authority';
|
|
415
|
+
|
|
416
|
+
const buttonVariants = cva('rounded font-medium transition-colors', {
|
|
417
|
+
variants: {
|
|
418
|
+
variant: {
|
|
419
|
+
default: 'bg-primary text-white hover:bg-primary/90',
|
|
420
|
+
destructive: 'bg-red-500 text-white hover:bg-red-600',
|
|
421
|
+
outline: 'border border-input bg-transparent hover:bg-accent',
|
|
422
|
+
},
|
|
423
|
+
size: {
|
|
424
|
+
sm: 'h-8 px-3 text-sm',
|
|
425
|
+
md: 'h-10 px-4',
|
|
426
|
+
lg: 'h-12 px-6 text-lg',
|
|
427
|
+
},
|
|
428
|
+
},
|
|
429
|
+
defaultVariants: { variant: 'default', size: 'md' },
|
|
430
|
+
});
|
|
431
|
+
|
|
432
|
+
type ButtonProps = VariantProps<typeof buttonVariants>;
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
---
|
|
436
|
+
|
|
437
|
+
## Component Organization (MANDATORY)
|
|
438
|
+
|
|
439
|
+
### File Structure
|
|
440
|
+
|
|
441
|
+
```
|
|
442
|
+
src/
|
|
443
|
+
├── app/
|
|
444
|
+
│ ├── (auth)/ # Route group
|
|
445
|
+
│ │ ├── login/
|
|
446
|
+
│ │ │ ├── page.tsx
|
|
447
|
+
│ │ │ └── _components/ # Page-specific components
|
|
448
|
+
│ │ │ ├── login-form.tsx
|
|
449
|
+
│ │ │ └── social-buttons.tsx
|
|
450
|
+
│ │ └── layout.tsx
|
|
451
|
+
│ ├── dashboard/
|
|
452
|
+
│ │ ├── page.tsx
|
|
453
|
+
│ │ └── _components/ # Page-specific
|
|
454
|
+
│ └── layout.tsx # Root layout with providers
|
|
455
|
+
├── components/
|
|
456
|
+
│ ├── ui/ # shadcn primitives (Button, Input, etc.)
|
|
457
|
+
│ ├── layout/ # Header, Sidebar, Footer
|
|
458
|
+
│ └── shared/ # Reusable across features
|
|
459
|
+
└── lib/
|
|
460
|
+
└── utils.ts # cn utility
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
### Component Location Rules
|
|
464
|
+
|
|
465
|
+
| Question | Location |
|
|
466
|
+
|----------|----------|
|
|
467
|
+
| Used in ONE page only? | `app/[page]/_components/` |
|
|
468
|
+
| Used across 2+ features? | `components/shared/` |
|
|
469
|
+
| UI primitive (Button, Input)? | `components/ui/` |
|
|
470
|
+
| Layout element (Header, Footer)? | `components/layout/` |
|
|
471
|
+
|
|
472
|
+
### File Size Rules (MANDATORY)
|
|
473
|
+
|
|
474
|
+
| Lines | Action |
|
|
475
|
+
|-------|--------|
|
|
476
|
+
| < 200 | Keep in single file |
|
|
477
|
+
| 200-400 | Consider splitting |
|
|
478
|
+
| > 400 | **MUST split** into smaller components |
|
|
479
|
+
|
|
480
|
+
> **Rule:** When a file exceeds 200 lines, extract logical pieces into `_components/` folder.
|
|
481
|
+
|
|
482
|
+
### Naming Conventions
|
|
483
|
+
|
|
484
|
+
```
|
|
485
|
+
components/
|
|
486
|
+
├── ui/
|
|
487
|
+
│ ├── button.tsx # kebab-case files
|
|
488
|
+
│ └── data-table.tsx
|
|
489
|
+
├── shared/
|
|
490
|
+
│ └── user-avatar.tsx
|
|
491
|
+
└── layout/
|
|
492
|
+
└── main-header.tsx
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
---
|
|
496
|
+
|
|
497
|
+
## Next.js App Router Patterns (MANDATORY)
|
|
498
|
+
|
|
499
|
+
### Server vs Client Components
|
|
500
|
+
|
|
501
|
+
```tsx
|
|
502
|
+
// ✅ DEFAULT: Server Component (no directive needed)
|
|
503
|
+
export default async function Page({ params }) {
|
|
504
|
+
const data = await fetch('...'); // Server-side fetch
|
|
505
|
+
return <ClientButton data={data} />; // Pass to client
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
// ✅ Client Component (push to leaves)
|
|
509
|
+
'use client';
|
|
510
|
+
export function ClientButton({ data }) {
|
|
511
|
+
const [state, setState] = useState();
|
|
512
|
+
return <button onClick={() => setState(!state)}>{data}</button>;
|
|
513
|
+
}
|
|
514
|
+
```
|
|
515
|
+
|
|
516
|
+
### When to Use 'use client'
|
|
517
|
+
|
|
518
|
+
| Need | Directive |
|
|
519
|
+
|------|-----------|
|
|
520
|
+
| useState, useEffect, useContext | `'use client'` |
|
|
521
|
+
| onClick, onChange, onSubmit | `'use client'` |
|
|
522
|
+
| Browser APIs (localStorage, window) | `'use client'` |
|
|
523
|
+
| Data fetching only | Server Component (default) |
|
|
524
|
+
| Static rendering | Server Component (default) |
|
|
525
|
+
|
|
526
|
+
> **Rule:** Keep `'use client'` at the LEAVES of component tree, not at the top.
|
|
527
|
+
|
|
528
|
+
### Layout Context Pattern (MANDATORY)
|
|
529
|
+
|
|
530
|
+
```tsx
|
|
531
|
+
// app/layout.tsx - Root layout with providers
|
|
532
|
+
import { Providers } from '@/components/providers';
|
|
533
|
+
|
|
534
|
+
export default function RootLayout({ children }) {
|
|
535
|
+
return (
|
|
536
|
+
<html lang="en">
|
|
537
|
+
<body>
|
|
538
|
+
<Providers>{children}</Providers>
|
|
539
|
+
</body>
|
|
540
|
+
</html>
|
|
541
|
+
);
|
|
542
|
+
}
|
|
543
|
+
|
|
544
|
+
// components/providers.tsx
|
|
545
|
+
'use client';
|
|
546
|
+
import { QueryClientProvider } from '@tanstack/react-query';
|
|
547
|
+
import { ThemeProvider } from 'next-themes';
|
|
548
|
+
import { Toaster } from 'sonner';
|
|
549
|
+
|
|
550
|
+
export function Providers({ children }) {
|
|
551
|
+
return (
|
|
552
|
+
<QueryClientProvider client={queryClient}>
|
|
553
|
+
<ThemeProvider attribute="class" defaultTheme="system">
|
|
554
|
+
{children}
|
|
555
|
+
<Toaster position="top-right" />
|
|
556
|
+
</ThemeProvider>
|
|
557
|
+
</QueryClientProvider>
|
|
558
|
+
);
|
|
559
|
+
}
|
|
560
|
+
```
|
|
561
|
+
|
|
562
|
+
### Route Groups & Private Folders
|
|
563
|
+
|
|
564
|
+
```
|
|
565
|
+
app/
|
|
566
|
+
├── (marketing)/ # Route group (no URL impact)
|
|
567
|
+
│ ├── page.tsx # / (home)
|
|
568
|
+
│ └── about/page.tsx # /about
|
|
569
|
+
├── (app)/ # Route group for authenticated
|
|
570
|
+
│ ├── dashboard/page.tsx # /dashboard
|
|
571
|
+
│ └── layout.tsx # Shared app layout
|
|
572
|
+
├── _components/ # Private folder (NOT a route)
|
|
573
|
+
└── _lib/ # Private folder (NOT a route)
|
|
574
|
+
```
|
|
575
|
+
|
|
576
|
+
### Parallel Data Fetching
|
|
577
|
+
|
|
578
|
+
```tsx
|
|
579
|
+
// ✅ CORRECT: Parallel fetches
|
|
580
|
+
export default async function Page() {
|
|
581
|
+
const [user, posts, comments] = await Promise.all([
|
|
582
|
+
getUser(),
|
|
583
|
+
getPosts(),
|
|
584
|
+
getComments(),
|
|
585
|
+
]);
|
|
586
|
+
return <Dashboard user={user} posts={posts} comments={comments} />;
|
|
587
|
+
}
|
|
588
|
+
|
|
589
|
+
// ❌ AVOID: Waterfall (sequential)
|
|
590
|
+
export default async function Page() {
|
|
591
|
+
const user = await getUser();
|
|
592
|
+
const posts = await getPosts(); // Waits for user
|
|
593
|
+
const comments = await getComments(); // Waits for posts
|
|
594
|
+
}
|
|
595
|
+
```
|
|
596
|
+
|
|
597
|
+
### Dynamic Imports (Heavy Components)
|
|
598
|
+
|
|
599
|
+
```tsx
|
|
600
|
+
import dynamic from 'next/dynamic';
|
|
601
|
+
|
|
602
|
+
// ✅ For modals, charts, admin panels
|
|
603
|
+
const HeavyChart = dynamic(() => import('@/components/charts/heavy-chart'), {
|
|
604
|
+
loading: () => <Skeleton className="h-96" />,
|
|
605
|
+
ssr: false, // Client-only if needed
|
|
606
|
+
});
|
|
607
|
+
|
|
608
|
+
// ❌ DON'T dynamic import above-the-fold content (hurts LCP)
|
|
609
|
+
```
|
|
610
|
+
|
|
611
|
+
### Skeleton Loading Pattern
|
|
612
|
+
|
|
613
|
+
```tsx
|
|
614
|
+
// loading.tsx - Automatic loading UI
|
|
615
|
+
import { Skeleton } from '@/components/ui/skeleton';
|
|
616
|
+
|
|
617
|
+
export default function Loading() {
|
|
618
|
+
return (
|
|
619
|
+
<div className="space-y-4">
|
|
620
|
+
<Skeleton className="h-12 w-full" />
|
|
621
|
+
<Skeleton className="h-64 w-full" />
|
|
622
|
+
</div>
|
|
623
|
+
);
|
|
624
|
+
}
|
|
625
|
+
```
|
|
626
|
+
|
|
627
|
+
---
|
|
628
|
+
|
|
629
|
+
## Grid Layouts (Choose by Context)
|
|
630
|
+
|
|
631
|
+
| Grid Type | Use For | Mobile |
|
|
632
|
+
|-----------|---------|--------|
|
|
633
|
+
| **Bento Grid** | Landing, features, portfolios | Stacks vertically |
|
|
634
|
+
| **12-Column** | Dashboards, admin panels | Collapse to 1-2 cols |
|
|
635
|
+
| **Masonry** | Galleries, Pinterest-style | Use vertical list |
|
|
636
|
+
| **Card Grid** | Products, team, blog archive | Stack to single col |
|
|
637
|
+
| **Split Grid** | Hero sections, auth pages | Stack vertically |
|
|
638
|
+
| **Kanban** | Project management, tasks | Horizontal scroll |
|
|
639
|
+
|
|
640
|
+
---
|
|
641
|
+
|
|
642
|
+
## Modal/Dialog Patterns (Choose by Action)
|
|
643
|
+
|
|
644
|
+
| Modal Type | Use For | Mobile |
|
|
645
|
+
|------------|---------|--------|
|
|
646
|
+
| **Centered Dialog** | Confirmations, short forms | Full-screen |
|
|
647
|
+
| **Slide-over/Drawer** | Filters, settings, details | Bottom sheet |
|
|
648
|
+
| **Bottom Sheet** | Actions, sharing, quick forms | Native feel |
|
|
649
|
+
| **Command Palette** | CMD+K, power users | Full-screen |
|
|
650
|
+
| **Wizard/Stepper** | Multi-step forms, onboarding | Full-screen |
|
|
651
|
+
| **Lightbox** | Images, videos | Full-screen |
|
|
652
|
+
|
|
653
|
+
---
|
|
654
|
+
|
|
655
|
+
## List Patterns (Choose by Data)
|
|
656
|
+
|
|
657
|
+
| List Type | Use For | Key Feature |
|
|
658
|
+
|-----------|---------|-------------|
|
|
659
|
+
| **Simple List** | Basic items, settings | Dividers |
|
|
660
|
+
| **Avatar List** | Users, contacts | Profile images |
|
|
661
|
+
| **Expandable/Accordion** | FAQs, nested content | Collapse/expand |
|
|
662
|
+
| **Swipeable List** | Mobile actions | Left/right swipe |
|
|
663
|
+
| **Drag & Drop** | Reordering | dnd-kit (NOT react-beautiful-dnd) |
|
|
664
|
+
| **Virtualized** | 1000+ items | react-window or react-virtuoso |
|
|
665
|
+
| **Timeline** | Activity feed, history | Vertical line |
|
|
666
|
+
| **Chat/Messages** | Conversations | Bubbles left/right |
|
|
667
|
+
|
|
668
|
+
---
|
|
669
|
+
|
|
670
|
+
## Multi-Step Forms (MANDATORY for complex forms)
|
|
671
|
+
|
|
672
|
+
| Pattern | Use For | Progress |
|
|
673
|
+
|---------|---------|----------|
|
|
674
|
+
| **Horizontal Stepper** | Onboarding, checkout | Numbers at top |
|
|
675
|
+
| **Card-based Steps** | Settings, profiles | Expandable cards |
|
|
676
|
+
| **Slide Animation** | Typeform-style | Left/right slide |
|
|
677
|
+
| **Accordion Steps** | Long forms | Collapsible sections |
|
|
678
|
+
|
|
679
|
+
### Form Stack (MANDATORY)
|
|
680
|
+
|
|
681
|
+
```typescript
|
|
682
|
+
// react-hook-form + Zod + per-step validation
|
|
683
|
+
const { trigger } = useForm<FormData>({ resolver: zodResolver(schema) });
|
|
684
|
+
|
|
685
|
+
const nextStep = async () => {
|
|
686
|
+
const isValid = await trigger(currentStepFields);
|
|
687
|
+
if (!isValid) return;
|
|
688
|
+
setStep(step + 1);
|
|
689
|
+
};
|
|
690
|
+
```
|
|
691
|
+
|
|
692
|
+
---
|
|
693
|
+
|
|
694
|
+
## Toast Notifications (MANDATORY: Sonner)
|
|
695
|
+
|
|
696
|
+
```typescript
|
|
697
|
+
// Install: pnpm dlx shadcn@latest add sonner
|
|
698
|
+
import { toast } from "sonner";
|
|
699
|
+
|
|
700
|
+
// Promise-based (loading → success/error)
|
|
701
|
+
toast.promise(saveData(), {
|
|
702
|
+
loading: 'Saving...',
|
|
703
|
+
success: 'Saved!',
|
|
704
|
+
error: 'Failed to save',
|
|
705
|
+
});
|
|
706
|
+
|
|
707
|
+
// With action button
|
|
708
|
+
toast('File deleted', {
|
|
709
|
+
action: { label: 'Undo', onClick: () => restoreFile() },
|
|
710
|
+
});
|
|
711
|
+
```
|
|
712
|
+
|
|
713
|
+
> **Duration**: 4s info, 7s+ errors. Max 3-5 visible toasts.
|
|
714
|
+
|
|
715
|
+
---
|
|
716
|
+
|
|
717
|
+
## Optimistic UI (MANDATORY for mutations)
|
|
718
|
+
|
|
719
|
+
> **ALWAYS show instant feedback, rollback on error.**
|
|
720
|
+
|
|
721
|
+
### Pattern 1: useOptimistic (React 19)
|
|
722
|
+
|
|
723
|
+
```typescript
|
|
724
|
+
const [optimisticItems, addOptimistic] = useOptimistic(
|
|
725
|
+
items,
|
|
726
|
+
(state, newItem) => [...state, { ...newItem, pending: true }]
|
|
727
|
+
);
|
|
728
|
+
|
|
729
|
+
async function addItem(data: ItemData) {
|
|
730
|
+
addOptimistic(data); // Instant UI update
|
|
731
|
+
try {
|
|
732
|
+
await api.post('/items', data);
|
|
733
|
+
} catch {
|
|
734
|
+
toast.error('Failed to add');
|
|
735
|
+
// State auto-reverts
|
|
736
|
+
}
|
|
737
|
+
}
|
|
738
|
+
```
|
|
739
|
+
|
|
740
|
+
### Pattern 2: TanStack Query
|
|
741
|
+
|
|
742
|
+
```typescript
|
|
743
|
+
useMutation({
|
|
744
|
+
mutationFn: updateItem,
|
|
745
|
+
onMutate: async (newData) => {
|
|
746
|
+
await queryClient.cancelQueries({ queryKey: ['items'] });
|
|
747
|
+
const previous = queryClient.getQueryData(['items']);
|
|
748
|
+
queryClient.setQueryData(['items'], (old) =>
|
|
749
|
+
old.map(item => item.id === newData.id ? { ...item, ...newData } : item)
|
|
750
|
+
);
|
|
751
|
+
return { previous };
|
|
752
|
+
},
|
|
753
|
+
onError: (err, vars, context) => {
|
|
754
|
+
queryClient.setQueryData(['items'], context.previous); // Rollback
|
|
755
|
+
toast.error('Update failed');
|
|
756
|
+
},
|
|
757
|
+
onSettled: () => queryClient.invalidateQueries({ queryKey: ['items'] }),
|
|
758
|
+
});
|
|
759
|
+
```
|
|
760
|
+
|
|
761
|
+
---
|
|
762
|
+
|
|
763
|
+
## Data Display Patterns
|
|
764
|
+
|
|
765
|
+
### Tables
|
|
766
|
+
|
|
767
|
+
| Style | Use For |
|
|
768
|
+
|-------|---------|
|
|
769
|
+
| **Striped rows** | Long lists, scanning |
|
|
770
|
+
| **Sticky header** | Scrollable data |
|
|
771
|
+
| **Expandable rows** | Details on demand |
|
|
772
|
+
| **Sortable columns** | Data comparison |
|
|
773
|
+
| **Virtualized** | 1000+ rows (TanStack Virtual) |
|
|
774
|
+
|
|
775
|
+
### Cards
|
|
776
|
+
|
|
777
|
+
| Style | Use For |
|
|
778
|
+
|-------|---------|
|
|
779
|
+
| **Stats/KPI Card** | Metrics with trends |
|
|
780
|
+
| **Product Card** | E-commerce listings |
|
|
781
|
+
| **Profile Card** | User information |
|
|
782
|
+
| **Interactive Card** | Hover effects, animations |
|
|
783
|
+
|
|
784
|
+
---
|
|
785
|
+
|
|
786
|
+
## Navigation Patterns
|
|
787
|
+
|
|
788
|
+
| Type | Desktop | Mobile |
|
|
789
|
+
|------|---------|--------|
|
|
790
|
+
| **Header** | Fixed top navbar | Hamburger menu |
|
|
791
|
+
| **Sidebar** | Fixed left, collapsible | Overlay drawer |
|
|
792
|
+
| **Tabs** | Horizontal tabs | Bottom tab bar |
|
|
793
|
+
| **Breadcrumbs** | Path navigation | Simplified |
|
|
794
|
+
|
|
795
|
+
---
|
|
796
|
+
|
|
797
|
+
## Animation Libraries
|
|
798
|
+
|
|
799
|
+
| Library | Use When | Bundle |
|
|
800
|
+
|---------|----------|--------|
|
|
801
|
+
| **AutoAnimate** | 90% of UI (lists, tabs, dropdowns) | Minimal |
|
|
802
|
+
| **Framer Motion** | Page transitions, gestures, layouts | 32KB |
|
|
803
|
+
| **GSAP** | Scroll-driven, complex timelines | 23KB |
|
|
804
|
+
| **Magic UI** | Landing pages, marketing | Copy-paste |
|
|
805
|
+
| **Aceternity UI** | Portfolios, 3D effects | Copy-paste |
|
|
806
|
+
|
|
807
|
+
---
|
|
808
|
+
|
|
809
|
+
## Design Trends (2025)
|
|
810
|
+
|
|
811
|
+
| Trend | Use For | Avoid |
|
|
812
|
+
|-------|---------|-------|
|
|
813
|
+
| **Glassmorphism** | Modals, overlays, dark mode | Light backgrounds |
|
|
814
|
+
| **Minimalism** | Mobile, SaaS, accessibility | Marketing sites |
|
|
815
|
+
| **Bold Typography** | Landing hero, brands | Data dashboards |
|
|
816
|
+
|
|
817
|
+
---
|
|
818
|
+
|
|
819
|
+
## Mandatory Planning
|
|
820
|
+
|
|
821
|
+
> **ALWAYS use `EnterPlanMode` for non-trivial tasks BEFORE implementing.**
|
|
822
|
+
|
|
823
|
+
### When to Plan
|
|
824
|
+
|
|
825
|
+
| Task Type | Plan Required |
|
|
826
|
+
|-----------|---------------|
|
|
827
|
+
| New feature | YES |
|
|
828
|
+
| UI changes (any JSX) | YES |
|
|
829
|
+
| Multi-file changes | YES |
|
|
830
|
+
| Bug fix (simple) | NO |
|
|
831
|
+
| Single-line fix | NO |
|
|
832
|
+
|
|
833
|
+
### Plan Format
|
|
834
|
+
|
|
835
|
+
```
|
|
836
|
+
1. Analyze current state
|
|
837
|
+
2. Identify affected files
|
|
838
|
+
3. Design approach (with alternatives)
|
|
839
|
+
4. Get user approval
|
|
840
|
+
5. THEN implement
|
|
841
|
+
```
|
|
842
|
+
|
|
843
|
+
---
|
|
844
|
+
|
|
845
|
+
## MCP Servers
|
|
846
|
+
|
|
847
|
+
| Server | Purpose | When to Use |
|
|
848
|
+
| --------------------- | ----------------------- | ------------------------------------ |
|
|
849
|
+
| `context7` | Library documentation | Before implementing with ANY library |
|
|
850
|
+
| `sequential-thinking` | Complex problem-solving | Multi-step tasks, planning |
|
|
851
|
+
| `memory` | Persistent knowledge | Store/recall project patterns |
|
|
852
|
+
| `playwright` | Browser automation | UI testing, page verification |
|
|
853
|
+
|
|
854
|
+
---
|
|
855
|
+
|
|
856
|
+
## Agent System
|
|
857
|
+
|
|
858
|
+
82 specialized agents in 14 categories. Key agents:
|
|
859
|
+
|
|
860
|
+
| Agent | Purpose |
|
|
861
|
+
| ---------------- | ------------------------------------------------------ |
|
|
862
|
+
| orchestrator | Coordinates development flow |
|
|
863
|
+
| research-web | Researches best practices (MANDATORY for new features) |
|
|
864
|
+
| documenter | Maps files to domains, tracks what exists where |
|
|
865
|
+
| domain-updater | Records problems, solutions, learnings in domains |
|
|
866
|
+
| security-auditor | Audits security (CAN VETO) |
|
|
867
|
+
| final-validator | Last check before commit (CAN VETO) |
|
|
868
|
+
| commit-manager | Manages commits and merges to main |
|
|
869
|
+
|
|
870
|
+
---
|
|
871
|
+
|
|
872
|
+
## Domain Documentation
|
|
873
|
+
|
|
874
|
+
> Domain docs prevent Claude from re-exploring the codebase every session.
|
|
875
|
+
|
|
876
|
+
### Location
|
|
877
|
+
|
|
878
|
+
```
|
|
879
|
+
.claude/skills/codebase-knowledge/domains/
|
|
880
|
+
├── authentication.md
|
|
881
|
+
├── api.md
|
|
882
|
+
├── ui-components.md
|
|
883
|
+
└── ...
|
|
884
|
+
```
|
|
885
|
+
|
|
886
|
+
### Domain Mapping (domain-mapping.json)
|
|
887
|
+
|
|
888
|
+
| Domain | File Patterns |
|
|
889
|
+
|--------|---------------|
|
|
890
|
+
| authentication | `**/auth/**`, `**/*auth*.ts` |
|
|
891
|
+
| api | `**/api/**`, `**/routers/**` |
|
|
892
|
+
| database | `**/models/**`, `**/*.model.ts` |
|
|
893
|
+
| ui-components | `**/components/**/*.tsx` |
|
|
894
|
+
| pages | `**/app/**/page.tsx` |
|
|
895
|
+
|
|
896
|
+
### Documentation Agents
|
|
897
|
+
|
|
898
|
+
| Agent | Role | When |
|
|
899
|
+
|-------|------|------|
|
|
900
|
+
| **documenter** | Maps files to domains, creates/updates domain files | AFTER implementation |
|
|
901
|
+
| **domain-updater** | Records problems, solutions, gotchas | BEFORE commit |
|
|
902
|
+
|
|
903
|
+
### Domain File Sections
|
|
904
|
+
|
|
905
|
+
Every domain file MUST have:
|
|
906
|
+
- **Last Update** - Date, commit, summary
|
|
907
|
+
- **Files** - All files in this domain
|
|
908
|
+
- **Connections** - Links to other domains
|
|
909
|
+
- **Recent Commits** - Commit history
|
|
910
|
+
- **Attention Points** - Gotchas and rules
|
|
911
|
+
|
|
912
|
+
---
|
|
913
|
+
|
|
914
|
+
## NRY (Never Repeat Yourself)
|
|
915
|
+
|
|
916
|
+
Common Claude mistakes to avoid:
|
|
917
|
+
|
|
918
|
+
- Multi-line bash with `\` continuations (breaks permissions)
|
|
919
|
+
- Relative paths in permission patterns
|
|
920
|
+
- Executing agent logic manually (use Task tool)
|
|
921
|
+
- Using bash for file operations (use Read/Write/Edit)
|
|
922
|
+
- Ignoring context size (use `/compact`)
|
|
923
|
+
|
|
924
|
+
---
|
|
925
|
+
|
|
926
|
+
## Configuration
|
|
927
|
+
|
|
928
|
+
Project-specific settings in `.claude/config/`:
|
|
107
929
|
|
|
108
|
-
-
|
|
109
|
-
-
|
|
110
|
-
-
|
|
930
|
+
- `project-config.json` - Stack, structure, commands
|
|
931
|
+
- `domain-mapping.json` - File-to-domain mapping
|
|
932
|
+
- `quality-gates.json` - Quality check commands
|
|
933
|
+
- `testing-config.json` - Test framework config
|
|
934
|
+
- `security-rules.json` - Security audit rules
|
|
111
935
|
|
|
112
936
|
---
|
|
113
937
|
|