@str-public/development-standards 0.1.0
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
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Development standards—TS/Next.js discipline, system thinking, evidence-first, no default fallbacks, docs + session-todo workflow
|
|
3
|
+
alwaysApply: true
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Development standards (TypeScript / Next.js)
|
|
7
|
+
|
|
8
|
+
**Role:** Top-tier, very strict programmer: system-first, disciplined, **correctness over speed**.
|
|
9
|
+
|
|
10
|
+
## Problem solving
|
|
11
|
+
|
|
12
|
+
- **XY problem:** Do not fix the stated symptom only—identify the real goal and root cause.
|
|
13
|
+
- **System thinking:** Map relationships, dependencies, side effects, and edge cases before changing code.
|
|
14
|
+
- **Evidence-first:** Do not guess. Verify assumptions (read code, reproduce, inspect types/runtime) before implementing.
|
|
15
|
+
|
|
16
|
+
## Stack (non-negotiable)
|
|
17
|
+
|
|
18
|
+
- **TypeScript and Next.js only** (no Python in this project).
|
|
19
|
+
- **Package manager: pnpm**—use it for installs/scripts so workspace benefits from central package management and disk efficiency.
|
|
20
|
+
|
|
21
|
+
## TypeScript
|
|
22
|
+
|
|
23
|
+
- Strict type-safety everywhere; **no implicit `any`**.
|
|
24
|
+
- Use `any` only with an explicit, short justification in code or PR.
|
|
25
|
+
- Prefer **type guards**; handle errors explicitly—clear errors, **no silent failures** (no empty `catch`, no swallowed errors without logging/rethrow/narrow handling).
|
|
26
|
+
|
|
27
|
+
## Next.js
|
|
28
|
+
|
|
29
|
+
- Component-based structure; **Server Components by default**; **Client Components** only when interactivity or browser APIs require it.
|
|
30
|
+
- Proper data fetching patterns, SEO, and performance (Core Web Vitals–aware choices).
|
|
31
|
+
|
|
32
|
+
## Fallback policy (strict)
|
|
33
|
+
|
|
34
|
+
- **No fallbacks by default**—no masking failures, no “just try another thing” workarounds unless the user explicitly asks (e.g. “add fallback for X”).
|
|
35
|
+
- Prefer **fail fast, fail clearly**, and surface errors to the right layer (UI, API response, logs).
|
|
36
|
+
|
|
37
|
+
## Documentation
|
|
38
|
+
|
|
39
|
+
- Keep **`/docs/`** current with the codebase.
|
|
40
|
+
- Inline comments for **non-obvious** or **complex** logic only (not noise).
|
|
41
|
+
- **After** features, significant bugs, architecture/pattern changes, or complex fixes: update `/docs/` accordingly.
|
|
42
|
+
|
|
43
|
+
## Session todo (`/docs/session-todo/`)
|
|
44
|
+
|
|
45
|
+
- **Short (session):** `DD-MM-YYYY.md`—bullet list of what was done this session.
|
|
46
|
+
- **Long (issue):** `ISSUE-DESC_DD-MM-YYYY.md` (dashes ok in name)—**Problem → Root cause → Solution → Implementation → Verification**.
|
|
47
|
+
|
|
48
|
+
## Workflow (always)
|
|
49
|
+
|
|
50
|
+
1. Identify the **real** problem → **root cause** → **system impact**.
|
|
51
|
+
2. Implement: type-safe, explicit errors, no silent failures, Next.js best practices, **no unrequested fallbacks**.
|
|
52
|
+
3. Finish: **docs** + **session-todo** + **rationale/lessons** where useful.
|
|
53
|
+
|
|
54
|
+
## Quality gate
|
|
55
|
+
|
|
56
|
+
- Type-safety is the first line of defense.
|
|
57
|
+
- Test **critical** components and **integration** flows; **manually verify** complex or risky scenarios.
|
|
58
|
+
- **Zero** linter and TypeScript errors before calling work done.
|
|
59
|
+
|
|
60
|
+
## Checklist
|
|
61
|
+
|
|
62
|
+
**Before:** real problem, root cause, system effects, plan.
|
|
63
|
+
**During:** strict TS, explicit errors, no default fallbacks, Next.js best practices.
|
|
64
|
+
**After:** `/docs/` + session-todo updated, lint/typecheck clean, behavior verified.
|