@mind-fold/open-flow 0.2.11 → 0.2.13
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/dist/templates/commands/break-loop.txt +1 -1
- package/dist/templates/commands/check-cross-layer.txt +3 -3
- package/dist/templates/commands/create-command.txt +5 -5
- package/dist/templates/commands/extract-llm-docs.txt +18 -18
- package/dist/templates/commands/extract-to-rules.txt +38 -38
- package/dist/templates/commands/finish-work.txt +5 -5
- package/dist/templates/commands/generate-backend-structure.txt +27 -27
- package/dist/templates/commands/generate-frontend-structure.txt +15 -15
- package/dist/templates/commands/integrate-skill.txt +30 -30
- package/dist/templates/commands/onboard-developer.txt +257 -416
- package/dist/templates/commands/record-agent-flow.txt +4 -4
- package/dist/templates/commands/sync-from-runtime.txt +2 -2
- package/dist/templates/markdown/agent-progress-index.md.txt +9 -9
- package/dist/templates/markdown/backend-doc.md.txt +12 -12
- package/dist/templates/markdown/flow.md.txt +99 -99
- package/dist/templates/markdown/frontend-doc.md.txt +11 -11
- package/dist/templates/markdown/structure/backend/database-guidelines.md.txt +6 -6
- package/dist/templates/markdown/structure/backend/directory-structure.md.txt +28 -28
- package/dist/templates/markdown/structure/backend/index.md.txt +10 -10
- package/dist/templates/markdown/structure/backend/logging-guidelines.md.txt +4 -4
- package/dist/templates/markdown/structure/backend/quality-guidelines.md.txt +12 -12
- package/dist/templates/markdown/structure/backend/type-safety.md.txt +6 -6
- package/dist/templates/markdown/structure/flows/code-reuse-thinking-guide.md.txt +17 -17
- package/dist/templates/markdown/structure/flows/cross-layer-thinking-guide.md.txt +96 -96
- package/dist/templates/markdown/structure/flows/index.md.txt +31 -31
- package/dist/templates/markdown/structure/flows/pre-implementation-checklist.md.txt +19 -19
- package/dist/templates/markdown/structure/flows/spec-flow-template.md.txt +20 -20
- package/dist/templates/markdown/structure/frontend/component-guidelines.md.txt +12 -12
- package/dist/templates/markdown/structure/frontend/directory-structure.md.txt +61 -61
- package/dist/templates/markdown/structure/frontend/hook-guidelines.md.txt +5 -5
- package/dist/templates/markdown/structure/frontend/index.md.txt +13 -13
- package/dist/templates/markdown/structure/frontend/quality-guidelines.md.txt +21 -21
- package/dist/templates/markdown/structure/frontend/state-management.md.txt +12 -12
- package/dist/templates/markdown/structure/frontend/type-safety.md.txt +11 -11
- package/dist/templates/scripts/add-session.sh.txt +5 -5
- package/dist/templates/scripts/extract-md-headings.sh.txt +3 -3
- package/dist/templates/scripts/get-context.sh.txt +1 -1
- package/dist/templates/scripts/init-developer.sh.txt +1 -1
- package/dist/templates/scripts/update-index.sh.txt +2 -2
- package/package.json +1 -1
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
|
|
1
|
+
[!] **Prerequisite**: This command should only be used AFTER the human has tested and committed the code.
|
|
2
2
|
|
|
3
3
|
**AI must NOT execute git commit** - only read history (`git log`, `git status`, `git diff`).
|
|
4
4
|
|
|
@@ -35,9 +35,9 @@ EOF
|
|
|
35
35
|
```
|
|
36
36
|
|
|
37
37
|
**Auto-completes**:
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
-
|
|
38
|
+
- [OK] Appends session to progress-N.md
|
|
39
|
+
- [OK] Auto-detects line count, creates new file if >2000 lines
|
|
40
|
+
- [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
|
|
41
41
|
|
|
42
42
|
---
|
|
43
43
|
|
|
@@ -120,8 +120,8 @@ After sync, report:
|
|
|
120
120
|
### Synced Docs
|
|
121
121
|
| Doc | Status | Notes |
|
|
122
122
|
|-----|--------|-------|
|
|
123
|
-
| database-guidelines.md |
|
|
124
|
-
| logging-guidelines.md |
|
|
123
|
+
| database-guidelines.md | [OK] Added | Adapted from Turso to generic ORM |
|
|
124
|
+
| logging-guidelines.md | [OK] Added | No changes needed |
|
|
125
125
|
|
|
126
126
|
### Updated Files
|
|
127
127
|
- workflow/structure/backend/index.md (added links)
|
|
@@ -12,13 +12,13 @@ This directory tracks progress for all developers working with AI Agents on this
|
|
|
12
12
|
|
|
13
13
|
```
|
|
14
14
|
agent-progress/
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
15
|
+
|-- index.md # This file - main index
|
|
16
|
+
\-- {developer}/ # Per-developer directory
|
|
17
|
+
|-- index.md # Personal index with session history
|
|
18
|
+
|-- features/ # Feature files
|
|
19
|
+
| |-- *.json # Active features
|
|
20
|
+
| \-- archive/ # Archived features by month
|
|
21
|
+
\-- progress-N.md # Progress files (sequential: 1, 2, 3...)
|
|
22
22
|
```
|
|
23
23
|
|
|
24
24
|
---
|
|
@@ -106,11 +106,11 @@ Use this template when recording sessions:
|
|
|
106
106
|
|
|
107
107
|
### Testing
|
|
108
108
|
|
|
109
|
-
-
|
|
109
|
+
- [OK] {Test result}
|
|
110
110
|
|
|
111
111
|
### Status
|
|
112
112
|
|
|
113
|
-
|
|
113
|
+
[OK] **Completed** / # **In Progress** / [P] **Blocked**
|
|
114
114
|
|
|
115
115
|
### Next Steps
|
|
116
116
|
|
|
@@ -9,12 +9,12 @@
|
|
|
9
9
|
|
|
10
10
|
```
|
|
11
11
|
packages/api/modules/
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
12
|
+
|-- {module}/
|
|
13
|
+
| |-- router.ts # Route definitions
|
|
14
|
+
| |-- procedures/ # Business logic
|
|
15
|
+
| |-- types.ts # Type definitions
|
|
16
|
+
| \-- api/ # API documentation
|
|
17
|
+
| \-- *.md
|
|
18
18
|
```
|
|
19
19
|
|
|
20
20
|
@@@/section:directory-structure
|
|
@@ -28,14 +28,14 @@ packages/api/modules/
|
|
|
28
28
|
### No Non-Null Assertions
|
|
29
29
|
|
|
30
30
|
```typescript
|
|
31
|
-
//
|
|
31
|
+
// [OK] Good - use local variable
|
|
32
32
|
const user = await getUser(id);
|
|
33
33
|
if (!user) {
|
|
34
34
|
throw new Error('User not found');
|
|
35
35
|
}
|
|
36
36
|
const userName = user.name; // Safe access
|
|
37
37
|
|
|
38
|
-
//
|
|
38
|
+
// [X] Bad - non-null assertion
|
|
39
39
|
const userName = user!.name;
|
|
40
40
|
```
|
|
41
41
|
|
|
@@ -69,12 +69,12 @@ const outputSchema = z.object({
|
|
|
69
69
|
### No Await in Loops
|
|
70
70
|
|
|
71
71
|
```typescript
|
|
72
|
-
//
|
|
72
|
+
// [OK] Good - parallel execution
|
|
73
73
|
const results = await Promise.all(
|
|
74
74
|
ids.map(id => db.query.users.findFirst({ where: eq(users.id, id) }))
|
|
75
75
|
);
|
|
76
76
|
|
|
77
|
-
//
|
|
77
|
+
// [X] Bad - sequential execution
|
|
78
78
|
for (const id of ids) {
|
|
79
79
|
await db.query.users.findFirst({ where: eq(users.id, id) });
|
|
80
80
|
}
|
|
@@ -111,10 +111,10 @@ await db.insert(users).values(data).onConflictDoUpdate({
|
|
|
111
111
|
### Use Structured Logging
|
|
112
112
|
|
|
113
113
|
```typescript
|
|
114
|
-
//
|
|
114
|
+
// [OK] Good
|
|
115
115
|
logger.info('User created', { userId: user.id, email: user.email });
|
|
116
116
|
|
|
117
|
-
//
|
|
117
|
+
// [X] Bad
|
|
118
118
|
console.log('User created: ' + user.id);
|
|
119
119
|
```
|
|
120
120
|
|
|
@@ -20,51 +20,51 @@
|
|
|
20
20
|
### Core Principles
|
|
21
21
|
|
|
22
22
|
1. **Read Before Write** - Understand context before starting
|
|
23
|
-
2. **Follow Standards** -
|
|
23
|
+
2. **Follow Standards** - [!] **MUST read `workflow/structure/` guidelines before coding**
|
|
24
24
|
3. **Incremental Development** - Complete one feature at a time
|
|
25
25
|
4. **Record Promptly** - Update tracking files immediately after completion
|
|
26
|
-
5. **Document Limits** -
|
|
26
|
+
5. **Document Limits** - [!] **Max 2000 lines per agent-progress document**
|
|
27
27
|
|
|
28
28
|
### File System
|
|
29
29
|
|
|
30
30
|
```
|
|
31
31
|
workflow/
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
32
|
+
|-- .developer # Developer identity (gitignored)
|
|
33
|
+
|-- scripts/
|
|
34
|
+
| |-- init-developer.sh # Initialize developer identity
|
|
35
|
+
| |-- get-developer.sh # Get current developer name
|
|
36
|
+
| |-- feature.sh # Manage features
|
|
37
|
+
| |-- get-context.sh # Get session context
|
|
38
|
+
| |-- update-index.sh # Auto-update index.md
|
|
39
|
+
| \-- add-session.sh # One-click session recording
|
|
40
|
+
|-- agent-progress/ # AI Agent work progress records
|
|
41
|
+
| |-- index.md # Progress index + Session template
|
|
42
|
+
| \-- {developer}/ # Per-developer directories
|
|
43
|
+
| |-- index.md # Personal index (with @@@auto markers)
|
|
44
|
+
| |-- features/ # Feature tracking
|
|
45
|
+
| \-- progress-N.md # Progress files (sequential numbering)
|
|
46
|
+
|-- structure/ # [!] MUST READ before coding
|
|
47
|
+
| |-- frontend/ # Frontend guidelines (multi-doc)
|
|
48
|
+
| | |-- index.md # Start here - guidelines index
|
|
49
|
+
| | |-- directory-structure.md # Directory layout
|
|
50
|
+
| | |-- type-safety.md # TypeScript patterns
|
|
51
|
+
| | |-- hook-guidelines.md # React Query hooks
|
|
52
|
+
| | |-- component-guidelines.md # Component patterns
|
|
53
|
+
| | |-- state-management.md # State patterns
|
|
54
|
+
| | \-- quality-guidelines.md # Code standards
|
|
55
|
+
| |-- backend/ # Backend guidelines (multi-doc)
|
|
56
|
+
| | |-- index.md # Start here - guidelines index
|
|
57
|
+
| | |-- directory-structure.md # Directory layout
|
|
58
|
+
| | |-- type-safety.md # Zod, TypeScript patterns
|
|
59
|
+
| | |-- database-guidelines.md # ORM, batch operations
|
|
60
|
+
| | |-- logging-guidelines.md # Structured logging
|
|
61
|
+
| | |-- error-handling.md # Error types, handling
|
|
62
|
+
| | \-- quality-guidelines.md # Code standards
|
|
63
|
+
| \-- flows/ # Cross-layer specifications
|
|
64
|
+
| |-- index.md # Flow specs index
|
|
65
|
+
| |-- cross-layer-thinking-guide.md # Pre-implementation checklist
|
|
66
|
+
| \-- spec-flow-template.md # Template for new flows
|
|
67
|
+
\-- flow.md # This document
|
|
68
68
|
```
|
|
69
69
|
|
|
70
70
|
---
|
|
@@ -83,9 +83,9 @@ Use the unified context script:
|
|
|
83
83
|
./workflow/scripts/get-context.sh --json
|
|
84
84
|
```
|
|
85
85
|
|
|
86
|
-
### Step 2: Read Development Guidelines
|
|
86
|
+
### Step 2: Read Development Guidelines [!] REQUIRED
|
|
87
87
|
|
|
88
|
-
|
|
88
|
+
**[!] CRITICAL: MUST read guidelines before writing any code**
|
|
89
89
|
|
|
90
90
|
Based on what you'll develop (frontend/backend), read the corresponding guidelines:
|
|
91
91
|
|
|
@@ -137,46 +137,46 @@ Use the feature management script:
|
|
|
137
137
|
|
|
138
138
|
```
|
|
139
139
|
1. Create or select feature
|
|
140
|
-
|
|
140
|
+
\-> ./workflow/scripts/feature.sh create <name> or list
|
|
141
141
|
|
|
142
142
|
2. Write code according to guidelines
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
143
|
+
\-> Read workflow/structure/[frontend|backend]/ docs
|
|
144
|
+
\-> For cross-layer: read workflow/structure/flows/
|
|
145
|
+
\-> Frontend: Type safety, Hook standards, Component standards
|
|
146
|
+
\-> Backend: Directory structure, Type safety, Database, Logging
|
|
147
147
|
|
|
148
148
|
3. Self-test
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
149
|
+
\-> pnpm lint (must pass)
|
|
150
|
+
\-> pnpm type-check (must pass)
|
|
151
|
+
\-> Manual feature testing
|
|
152
152
|
|
|
153
153
|
4. Commit code
|
|
154
|
-
|
|
155
|
-
|
|
154
|
+
\-> git add <files>
|
|
155
|
+
\-> git commit -m "type(scope): description"
|
|
156
156
|
Format: feat/fix/docs/refactor/test/chore
|
|
157
157
|
|
|
158
158
|
5. Record session (one command)
|
|
159
|
-
|
|
159
|
+
\-> ./workflow/scripts/add-session.sh --title "Title" --commit "hash"
|
|
160
160
|
```
|
|
161
161
|
|
|
162
162
|
### Code Quality Checklist
|
|
163
163
|
|
|
164
164
|
**Must pass before commit**:
|
|
165
|
-
-
|
|
166
|
-
-
|
|
167
|
-
-
|
|
165
|
+
- [OK] `pnpm lint` - 0 errors
|
|
166
|
+
- [OK] `pnpm type-check` - No type errors
|
|
167
|
+
- [OK] Manual feature testing passes
|
|
168
168
|
|
|
169
169
|
**Frontend-specific checks** (see `frontend/quality-guidelines.md`):
|
|
170
|
-
-
|
|
171
|
-
-
|
|
172
|
-
-
|
|
173
|
-
-
|
|
170
|
+
- [OK] Use semantic HTML (`<button>` not `<div role="button">`)
|
|
171
|
+
- [OK] Use Next.js `<Image>` instead of `<img>`
|
|
172
|
+
- [OK] Import types from backend, don't redefine
|
|
173
|
+
- [OK] Avoid non-null assertions `!`
|
|
174
174
|
|
|
175
175
|
**Backend-specific checks** (see `backend/quality-guidelines.md`):
|
|
176
|
-
-
|
|
177
|
-
-
|
|
178
|
-
-
|
|
179
|
-
-
|
|
176
|
+
- [OK] Strictly avoid non-null assertion `!`
|
|
177
|
+
- [OK] All API inputs/outputs have Zod Schema
|
|
178
|
+
- [OK] Use structured logging (`logger`), forbidden `console.log`
|
|
179
|
+
- [OK] Database operations avoid `await` in loops
|
|
180
180
|
|
|
181
181
|
---
|
|
182
182
|
|
|
@@ -202,11 +202,11 @@ This automatically:
|
|
|
202
202
|
### Pre-end Checklist
|
|
203
203
|
|
|
204
204
|
Use `/finish-work` command to run through:
|
|
205
|
-
1.
|
|
206
|
-
2.
|
|
207
|
-
3.
|
|
208
|
-
4.
|
|
209
|
-
5.
|
|
205
|
+
1. [OK] All code committed, commit message follows convention
|
|
206
|
+
2. [OK] Session recorded via `add-session.sh`
|
|
207
|
+
3. [OK] No lint/type-check errors
|
|
208
|
+
4. [OK] Working directory clean (or WIP noted)
|
|
209
|
+
5. [OK] Structure docs updated if needed
|
|
210
210
|
|
|
211
211
|
---
|
|
212
212
|
|
|
@@ -219,17 +219,17 @@ Use `/finish-work` command to run through:
|
|
|
219
219
|
**Structure** (Multi-developer support):
|
|
220
220
|
```
|
|
221
221
|
agent-progress/
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
222
|
+
|-- index.md # Main index (Active Developers table)
|
|
223
|
+
\-- {developer}/ # Per-developer directory
|
|
224
|
+
|-- index.md # Personal index (with @@@auto markers)
|
|
225
|
+
|-- features/ # Feature files
|
|
226
|
+
\-- progress-N.md # Progress files (sequential: 1, 2, 3...)
|
|
227
227
|
```
|
|
228
228
|
|
|
229
229
|
**When to update**:
|
|
230
|
-
-
|
|
231
|
-
-
|
|
232
|
-
-
|
|
230
|
+
- [OK] End of each session
|
|
231
|
+
- [OK] Complete important feature
|
|
232
|
+
- [OK] Fix important bug
|
|
233
233
|
|
|
234
234
|
### 2. structure/ - Development Guidelines
|
|
235
235
|
|
|
@@ -238,21 +238,21 @@ agent-progress/
|
|
|
238
238
|
**Structure** (Multi-doc format):
|
|
239
239
|
```
|
|
240
240
|
structure/
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
241
|
+
|-- frontend/ # Frontend docs
|
|
242
|
+
| |-- index.md # Start here
|
|
243
|
+
| \-- *.md # Topic-specific docs
|
|
244
|
+
|-- backend/ # Backend docs
|
|
245
|
+
| |-- index.md # Start here
|
|
246
|
+
| \-- *.md # Topic-specific docs
|
|
247
|
+
\-- flows/ # Cross-layer specs
|
|
248
|
+
|-- index.md # Start here
|
|
249
|
+
\-- *.md # Flow-specific docs
|
|
250
250
|
```
|
|
251
251
|
|
|
252
252
|
**When to update**:
|
|
253
|
-
-
|
|
254
|
-
-
|
|
255
|
-
-
|
|
253
|
+
- [OK] New pattern discovered
|
|
254
|
+
- [OK] Bug fixed that reveals missing guidance
|
|
255
|
+
- [OK] New convention established
|
|
256
256
|
|
|
257
257
|
### 3. Features - Feature Tracking
|
|
258
258
|
|
|
@@ -267,14 +267,14 @@ structure/
|
|
|
267
267
|
|
|
268
268
|
## Best Practices
|
|
269
269
|
|
|
270
|
-
###
|
|
270
|
+
### [OK] DO - Should Do
|
|
271
271
|
|
|
272
272
|
1. **Before session start**:
|
|
273
273
|
- Run `./workflow/scripts/get-context.sh` for full context
|
|
274
|
-
-
|
|
274
|
+
- [!] **MUST read** relevant `workflow/structure/` docs
|
|
275
275
|
|
|
276
276
|
2. **During development**:
|
|
277
|
-
-
|
|
277
|
+
- [!] **Follow** `workflow/structure/` guidelines
|
|
278
278
|
- For cross-layer features, use `/check-cross-layer`
|
|
279
279
|
- Develop only one feature at a time
|
|
280
280
|
- Run lint and type-check frequently
|
|
@@ -285,14 +285,14 @@ structure/
|
|
|
285
285
|
- Human commits after testing passes
|
|
286
286
|
- Use `add-session.sh` to record progress
|
|
287
287
|
|
|
288
|
-
###
|
|
288
|
+
### [X] DON'T - Should Not Do
|
|
289
289
|
|
|
290
|
-
1.
|
|
291
|
-
2.
|
|
290
|
+
1. [!] **Don't** skip reading `workflow/structure/` guidelines
|
|
291
|
+
2. [!] **Don't** let agent-progress single file exceed 2000 lines
|
|
292
292
|
3. **Don't** develop multiple unrelated features simultaneously
|
|
293
293
|
4. **Don't** commit code with lint/type-check errors
|
|
294
294
|
5. **Don't** forget to update structure docs after learning something
|
|
295
|
-
6.
|
|
295
|
+
6. [!] **Don't** execute `git commit` - AI should not commit code
|
|
296
296
|
7. **Don't** write `workflow/structure/` docs in Chinese - **English only**
|
|
297
297
|
|
|
298
298
|
---
|
|
@@ -345,10 +345,10 @@ pnpm type-check # Type check
|
|
|
345
345
|
## Summary
|
|
346
346
|
|
|
347
347
|
Following this workflow ensures:
|
|
348
|
-
-
|
|
349
|
-
-
|
|
350
|
-
-
|
|
351
|
-
-
|
|
352
|
-
-
|
|
348
|
+
- [OK] Continuity across multiple sessions
|
|
349
|
+
- [OK] Consistent code quality
|
|
350
|
+
- [OK] Trackable progress
|
|
351
|
+
- [OK] Knowledge accumulation in structure docs
|
|
352
|
+
- [OK] Transparent team collaboration
|
|
353
353
|
|
|
354
354
|
**Core Philosophy**: Read before write, follow standards, record promptly, capture learnings
|
|
@@ -9,11 +9,11 @@
|
|
|
9
9
|
|
|
10
10
|
```
|
|
11
11
|
modules/
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
12
|
+
|-- {feature}/
|
|
13
|
+
| |-- components/ # UI components
|
|
14
|
+
| |-- hooks/ # Custom hooks
|
|
15
|
+
| |-- context/ # React context
|
|
16
|
+
| \-- types.ts # Type definitions
|
|
17
17
|
```
|
|
18
18
|
|
|
19
19
|
@@@/section:directory-structure
|
|
@@ -28,10 +28,10 @@ modules/
|
|
|
28
28
|
Always import types from the API package instead of redefining them:
|
|
29
29
|
|
|
30
30
|
```typescript
|
|
31
|
-
//
|
|
31
|
+
// [OK] Good
|
|
32
32
|
import type { User } from '@/packages/api';
|
|
33
33
|
|
|
34
|
-
//
|
|
34
|
+
// [X] Bad - don't redefine
|
|
35
35
|
interface User {
|
|
36
36
|
id: string;
|
|
37
37
|
name: string;
|
|
@@ -114,10 +114,10 @@ export function useUpdateExample() {
|
|
|
114
114
|
Use proper HTML elements:
|
|
115
115
|
|
|
116
116
|
```tsx
|
|
117
|
-
//
|
|
117
|
+
// [OK] Good
|
|
118
118
|
<button onClick={handleClick}>Click me</button>
|
|
119
119
|
|
|
120
|
-
//
|
|
120
|
+
// [X] Bad
|
|
121
121
|
<div role="button" onClick={handleClick}>Click me</div>
|
|
122
122
|
```
|
|
123
123
|
|
|
@@ -129,11 +129,11 @@ Use proper HTML elements:
|
|
|
129
129
|
Use Next.js Image component:
|
|
130
130
|
|
|
131
131
|
```tsx
|
|
132
|
-
//
|
|
132
|
+
// [OK] Good
|
|
133
133
|
import Image from 'next/image';
|
|
134
134
|
<Image src="/logo.png" alt="Logo" width={100} height={100} />
|
|
135
135
|
|
|
136
|
-
//
|
|
136
|
+
// [X] Bad
|
|
137
137
|
<img src="/logo.png" alt="Logo" />
|
|
138
138
|
```
|
|
139
139
|
|
|
@@ -20,7 +20,7 @@ The N+1 query problem is one of the most common performance issues.
|
|
|
20
20
|
### Problem
|
|
21
21
|
|
|
22
22
|
```typescript
|
|
23
|
-
//
|
|
23
|
+
// [X] BAD: N+1 queries (1 + N database calls)
|
|
24
24
|
const users = await db.select().from(users).all();
|
|
25
25
|
for (const user of users) {
|
|
26
26
|
const posts = await db.select().from(posts).where(eq(posts.userId, user.id)).all();
|
|
@@ -31,7 +31,7 @@ for (const user of users) {
|
|
|
31
31
|
### Solution 1: Relational Queries
|
|
32
32
|
|
|
33
33
|
```typescript
|
|
34
|
-
//
|
|
34
|
+
// [OK] GOOD: Single query with JOIN
|
|
35
35
|
const usersWithPosts = await db.query.users.findMany({
|
|
36
36
|
with: {
|
|
37
37
|
posts: true,
|
|
@@ -42,7 +42,7 @@ const usersWithPosts = await db.query.users.findMany({
|
|
|
42
42
|
### Solution 2: Batch Lookup with inArray
|
|
43
43
|
|
|
44
44
|
```typescript
|
|
45
|
-
//
|
|
45
|
+
// [OK] GOOD: Two queries total (1 for users, 1 for all posts)
|
|
46
46
|
import { inArray } from 'drizzle-orm';
|
|
47
47
|
|
|
48
48
|
const users = await db.select().from(users).all();
|
|
@@ -61,7 +61,7 @@ const postsByUser = groupBy(allPosts, 'userId');
|
|
|
61
61
|
### Solution 3: Promise.all (Use Carefully)
|
|
62
62
|
|
|
63
63
|
```typescript
|
|
64
|
-
//
|
|
64
|
+
// [!] OK for small N, but watch connection limits
|
|
65
65
|
const results = await Promise.all(
|
|
66
66
|
ids.slice(0, 10).map(id =>
|
|
67
67
|
db.query.users.findFirst({ where: eq(users.id, id) })
|
|
@@ -164,11 +164,11 @@ export const users = sqliteTable('users', {
|
|
|
164
164
|
### Common Pitfall
|
|
165
165
|
|
|
166
166
|
```typescript
|
|
167
|
-
//
|
|
167
|
+
// [X] BAD: Mixing seconds and milliseconds
|
|
168
168
|
const timestamp = Math.floor(Date.now() / 1000); // Seconds
|
|
169
169
|
new Date(timestamp); // Wrong! Expects milliseconds
|
|
170
170
|
|
|
171
|
-
//
|
|
171
|
+
// [OK] GOOD: Consistent milliseconds
|
|
172
172
|
const timestamp = Date.now(); // Milliseconds
|
|
173
173
|
new Date(timestamp); // Correct
|
|
174
174
|
```
|
|
@@ -8,34 +8,34 @@
|
|
|
8
8
|
|
|
9
9
|
```
|
|
10
10
|
server/
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
11
|
+
|-- db/ # Database layer
|
|
12
|
+
| |-- client.ts # Database client initialization
|
|
13
|
+
| |-- schema.ts # Table definitions
|
|
14
|
+
| \-- migrations/ # Migration files
|
|
15
|
+
|
|
|
16
|
+
|-- lib/ # Shared utilities
|
|
17
|
+
| |-- logger.ts # Logger setup
|
|
18
|
+
| |-- errors.ts # Custom error classes
|
|
19
|
+
| \-- utils.ts # Helper functions
|
|
20
|
+
|
|
|
21
|
+
|-- middleware/ # Middleware
|
|
22
|
+
| |-- auth.ts # Authentication
|
|
23
|
+
| |-- error-handler.ts # Error handling
|
|
24
|
+
| \-- request-context.ts # Request context
|
|
25
|
+
|
|
|
26
|
+
|-- routes/ # API routes (domain-driven)
|
|
27
|
+
| \-- {domain}/
|
|
28
|
+
| |-- types.ts # Zod schemas + TypeScript types
|
|
29
|
+
| |-- router.ts # Route definitions
|
|
30
|
+
| |-- procedures/ # One file per endpoint
|
|
31
|
+
| | |-- list.ts
|
|
32
|
+
| | |-- get.ts
|
|
33
|
+
| | |-- create.ts
|
|
34
|
+
| | |-- update.ts
|
|
35
|
+
| | \-- delete.ts
|
|
36
|
+
| \-- lib/ # Domain-specific logic
|
|
37
|
+
|
|
|
38
|
+
\-- types.ts # Shared types (AppContext, etc.)
|
|
39
39
|
```
|
|
40
40
|
|
|
41
41
|
---
|
|
@@ -41,16 +41,16 @@ This collection of guidelines covers essential patterns and best practices for b
|
|
|
41
41
|
|
|
42
42
|
```
|
|
43
43
|
server/
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
44
|
+
|-- db/ # Database (client, schema)
|
|
45
|
+
|-- lib/ # Shared utilities
|
|
46
|
+
|-- middleware/ # Middleware
|
|
47
|
+
|-- routes/ # API routes (domain-driven)
|
|
48
|
+
| \-- {domain}/
|
|
49
|
+
| |-- types.ts # Zod schemas + types
|
|
50
|
+
| |-- router.ts # Route definitions
|
|
51
|
+
| |-- procedures/ # One file per endpoint
|
|
52
|
+
| \-- lib/ # Domain-specific logic
|
|
53
|
+
\-- types.ts # Shared types
|
|
54
54
|
```
|
|
55
55
|
|
|
56
56
|
### Key Rules
|
|
@@ -29,7 +29,7 @@
|
|
|
29
29
|
### Basic Pattern
|
|
30
30
|
|
|
31
31
|
```typescript
|
|
32
|
-
//
|
|
32
|
+
// [OK] GOOD: Structured with context
|
|
33
33
|
logger.info('user_created', {
|
|
34
34
|
userId: user.id,
|
|
35
35
|
email: user.email
|
|
@@ -40,7 +40,7 @@ logger.error('payment_failed', error, {
|
|
|
40
40
|
amount: order.total
|
|
41
41
|
});
|
|
42
42
|
|
|
43
|
-
//
|
|
43
|
+
// [X] BAD: Unstructured string concatenation
|
|
44
44
|
console.log('User created: ' + user.id);
|
|
45
45
|
logger.info('Error: ' + error.message);
|
|
46
46
|
```
|
|
@@ -150,10 +150,10 @@ async function syncData(logger: Logger) {
|
|
|
150
150
|
| Session cookies | Security |
|
|
151
151
|
|
|
152
152
|
```typescript
|
|
153
|
-
//
|
|
153
|
+
// [X] BAD
|
|
154
154
|
logger.info('login_attempt', { email, password });
|
|
155
155
|
|
|
156
|
-
//
|
|
156
|
+
// [OK] GOOD
|
|
157
157
|
logger.info('login_attempt', { email });
|
|
158
158
|
```
|
|
159
159
|
|