@zmice/zc 0.2.5 → 0.2.7

package/vendor/packages/toolkit/src/content/skills/performance-optimization/body.md

@@ -1,345 +1,75 @@
 # Performance Optimization
 
-## Overview
+## 角色定位
 
-Measure before optimizing. Performance work without measurement is guessing — and guessing leads to premature optimization that adds complexity without improving what matters. Profile first, identify the actual bottleneck, fix it, measure again. Optimize only what measurements prove matters.
+性能优化必须从测量开始。这个 skill 用于定位真实瓶颈、做最小修复、再次测量，并补回归保护；不用于凭感觉提前复杂化实现。
 
-## When to Use
+## 何时使用
 
-- Performance requirements exist in the spec (load time budgets, response time SLAs)
-- Users or monitoring report slow behavior
-- Core Web Vitals scores are below thresholds
-- You suspect a change introduced a regression
-- Building features that handle large datasets or high traffic
+- 规格里有明确性能目标或预算。
+- 用户、监控或日志报告慢。
+- Core Web Vitals、接口延迟、吞吐、内存或 CPU 有异常。
+- 怀疑一次变更造成性能回归。
+- 功能会处理大数据量、高并发或关键首屏路径。
 
-**When NOT to use:** Don't optimize before you have evidence of a problem. Premature optimization adds complexity that costs more than the performance it gains.
+不适用：没有性能证据，只是担心未来可能慢。
 
-## Core Web Vitals Targets
+## 快速路径
 
-| Metric | Good | Needs Improvement | Poor |
-|--------|------|-------------------|------|
-| **LCP** (Largest Contentful Paint) | ≤ 2.5s | ≤ 4.0s | > 4.0s |
-| **INP** (Interaction to Next Paint) | ≤ 200ms | ≤ 500ms | > 500ms |
-| **CLS** (Cumulative Layout Shift) | ≤ 0.1 | ≤ 0.25 | > 0.25 |
+1. 写清性能症状和目标指标。
+2. 建立 baseline：真实数据或可复现 synthetic 测量。
+3. 定位瓶颈：前端、后端、数据库、网络、渲染、内存或外部依赖。
+4. 只修当前证据指向的瓶颈。
+5. 再次测量，确认指标改善。
+6. 评估复杂度代价，避免为了小收益引入长期维护成本。
+7. 加 guard：监控、benchmark、预算或回归测试。
 
-## The Optimization Workflow
+## 指标选择
 
-```
-1. MEASURE  → Establish baseline with real data
-2. IDENTIFY → Find the actual bottleneck (not assumed)
-3. FIX      → Address the specific bottleneck
-4. VERIFY   → Measure again, confirm improvement
-5. GUARD    → Add monitoring or tests to prevent regression
-```
-
-### Step 1: Measure
-
-Two complementary approaches — use both:
-
-- **Synthetic (Lighthouse, DevTools Performance tab):** Controlled conditions, reproducible. Best for CI regression detection and isolating specific issues.
-- **RUM (web-vitals library, CrUX):** Real user data in real conditions. Required to validate that a fix actually improved user experience.
-
-**Frontend:**
-```bash
-# Synthetic: Lighthouse in Chrome DevTools (or CI)
-# Chrome DevTools → Performance tab → Record
-# Chrome DevTools MCP → Performance trace
-
-# RUM: Web Vitals library in code
-import { onLCP, onINP, onCLS } from 'web-vitals';
-
-onLCP(console.log);
-onINP(console.log);
-onCLS(console.log);
-```
-
-**Backend:**
-```bash
-# Response time logging
-# Application Performance Monitoring (APM)
-# Database query logging with timing
-
-# Simple timing
-console.time('db-query');
-const result = await db.query(...);
-console.timeEnd('db-query');
-```
-
-### Where to Start Measuring
-
-Use the symptom to decide what to measure first:
-
-```
-What is slow?
-├── First page load
-│   ├── Large bundle? --> Measure bundle size, check code splitting
-│   ├── Slow server response? --> Measure TTFB in DevTools Network waterfall
-│   │   ├── DNS long? --> Add dns-prefetch / preconnect for known origins
-│   │   ├── TCP/TLS long? --> Enable HTTP/2, check edge deployment, keep-alive
-│   │   └── Waiting (server) long? --> Profile backend, check queries and caching
-│   └── Render-blocking resources? --> Check network waterfall for CSS/JS blocking
-├── Interaction feels sluggish
-│   ├── UI freezes on click? --> Profile main thread, look for long tasks (>50ms)
-│   ├── Form input lag? --> Check re-renders, controlled component overhead
-│   └── Animation jank? --> Check layout thrashing, forced reflows
-├── Page after navigation
-│   ├── Data loading? --> Measure API response times, check for waterfalls
-│   └── Client rendering? --> Profile component render time, check for N+1 fetches
-└── Backend / API
-    ├── Single endpoint slow? --> Profile database queries, check indexes
-    ├── All endpoints slow? --> Check connection pool, memory, CPU
-    └── Intermittent slowness? --> Check for lock contention, GC pauses, external deps
-```
-
-### Step 2: Identify the Bottleneck
-
-Common bottlenecks by category:
-
-**Frontend:**
-
-| Symptom | Likely Cause | Investigation |
-|---------|-------------|---------------|
-| Slow LCP | Large images, render-blocking resources, slow server | Check network waterfall, image sizes |
-| High CLS | Images without dimensions, late-loading content, font shifts | Check layout shift attribution |
-| Poor INP | Heavy JavaScript on main thread, large DOM updates | Check long tasks in Performance trace |
-| Slow initial load | Large bundle, many network requests | Check bundle size, code splitting |
-
-**Backend:**
-
-| Symptom | Likely Cause | Investigation |
-|---------|-------------|---------------|
-| Slow API responses | N+1 queries, missing indexes, unoptimized queries | Check database query log |
-| Memory growth | Leaked references, unbounded caches, large payloads | Heap snapshot analysis |
-| CPU spikes | Synchronous heavy computation, regex backtracking | CPU profiling |
-| High latency | Missing caching, redundant computation, network hops | Trace requests through the stack |
-
-### Step 3: Fix Common Anti-Patterns
-
-#### N+1 Queries (Backend)
-
-```typescript
-// BAD: N+1 — one query per task for the owner
-const tasks = await db.tasks.findMany();
-for (const task of tasks) {
-  task.owner = await db.users.findUnique({ where: { id: task.ownerId } });
-}
-
-// GOOD: Single query with join/include
-const tasks = await db.tasks.findMany({
-  include: { owner: true },
-});
-```
-
-#### Unbounded Data Fetching
-
-```typescript
-// BAD: Fetching all records
-const allTasks = await db.tasks.findMany();
-
-// GOOD: Paginated with limits
-const tasks = await db.tasks.findMany({
-  take: 20,
-  skip: (page - 1) * 20,
-  orderBy: { createdAt: 'desc' },
-});
-```
-
-#### Missing Image Optimization (Frontend)
-
-```html
-<!-- BAD: No dimensions, no format optimization -->
-<img src="/hero.jpg" />
-
-<!-- GOOD: Hero / LCP image — art direction + resolution switching, high priority -->
-<!--
-  Two techniques combined:
-  - Art direction (media): different crop/composition per breakpoint
-  - Resolution switching (srcset + sizes): right file size per screen density
--->
-<picture>
-  <!-- Mobile: portrait crop (8:10) -->
-  <source
-    media="(max-width: 767px)"
-    srcset="/hero-mobile-400.avif 400w, /hero-mobile-800.avif 800w"
-    sizes="100vw"
-    width="800"
-    height="1000"
-    type="image/avif"
-  />
-  <source
-    media="(max-width: 767px)"
-    srcset="/hero-mobile-400.webp 400w, /hero-mobile-800.webp 800w"
-    sizes="100vw"
-    width="800"
-    height="1000"
-    type="image/webp"
-  />
-  <!-- Desktop: landscape crop (2:1) -->
-  <source
-    srcset="/hero-800.avif 800w, /hero-1200.avif 1200w, /hero-1600.avif 1600w"
-    sizes="(max-width: 1200px) 100vw, 1200px"
-    width="1200"
-    height="600"
-    type="image/avif"
-  />
-  <source
-    srcset="/hero-800.webp 800w, /hero-1200.webp 1200w, /hero-1600.webp 1600w"
-    sizes="(max-width: 1200px) 100vw, 1200px"
-    width="1200"
-    height="600"
-    type="image/webp"
-  />
-  <img
-    src="/hero-desktop.jpg"
-    width="1200"
-    height="600"
-    fetchpriority="high"
-    alt="Hero image description"
-  />
-</picture>
-
-<!-- GOOD: Below-the-fold image — lazy loaded + async decoding -->
-<img
-  src="/content.webp"
-  width="800"
-  height="400"
-  loading="lazy"
-  decoding="async"
-  alt="Content image description"
-/>
-```
-
-#### Unnecessary Re-renders (React)
-
-```tsx
-// BAD: Creates new object on every render, causing children to re-render
-function TaskList() {
-  return <TaskFilters options={{ sortBy: 'date', order: 'desc' }} />;
-}
-
-// GOOD: Stable reference
-const DEFAULT_OPTIONS = { sortBy: 'date', order: 'desc' } as const;
-function TaskList() {
-  return <TaskFilters options={DEFAULT_OPTIONS} />;
-}
-
-// Use React.memo for expensive components
-const TaskItem = React.memo(function TaskItem({ task }: Props) {
-  return <div>{/* expensive render */}</div>;
-});
-
-// Use useMemo for expensive computations
-function TaskStats({ tasks }: Props) {
-  const stats = useMemo(() => calculateStats(tasks), [tasks]);
-  return <div>{stats.completed} / {stats.total}</div>;
-}
-```
-
-#### Large Bundle Size
-
-```typescript
-// Modern bundlers (Vite, webpack 5+) handle named imports with tree-shaking automatically,
-// provided the dependency ships ESM and is marked `sideEffects: false` in package.json.
-// Profile before changing import styles — the real gains come from splitting and lazy loading.
-
-// GOOD: Dynamic import for heavy, rarely-used features
-const ChartLibrary = lazy(() => import('./ChartLibrary'));
-
-// GOOD: Route-level code splitting wrapped in Suspense
-const SettingsPage = lazy(() => import('./pages/Settings'));
-
-function App() {
-  return (
-    <Suspense fallback={<Spinner />}>
-      <SettingsPage />
-    </Suspense>
-  );
-}
-```
-
-#### Missing Caching (Backend)
-
-```typescript
-// Cache frequently-read, rarely-changed data
-const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
-let cachedConfig: AppConfig | null = null;
-let cacheExpiry = 0;
-
-async function getAppConfig(): Promise<AppConfig> {
-  if (cachedConfig && Date.now() < cacheExpiry) {
-    return cachedConfig;
-  }
-  cachedConfig = await db.config.findFirst();
-  cacheExpiry = Date.now() + CACHE_TTL;
-  return cachedConfig;
-}
-
-// HTTP caching headers for static assets
-app.use('/static', express.static('public', {
-  maxAge: '1y',           // Cache for 1 year
-  immutable: true,        // Never revalidate (use content hashing in filenames)
-}));
-
-// Cache-Control for API responses
-res.set('Cache-Control', 'public, max-age=300'); // 5 minutes
-```
-
-## Performance Budget
-
-Set budgets and enforce them:
-
-```
-JavaScript bundle: < 200KB gzipped (initial load)
-CSS: < 50KB gzipped
-Images: < 200KB per image (above the fold)
-Fonts: < 100KB total
-API response time: < 200ms (p95)
-Time to Interactive: < 3.5s on 4G
-Lighthouse Performance score: ≥ 90
+| 场景 | 优先指标 |
+|---|---|
+| 首屏慢 | LCP、TTFB、bundle size、network waterfall |
+| 交互卡顿 | INP、long task、render count、main thread profile |
+| 布局跳动 | CLS、图片尺寸、字体加载、late content |
+| API 慢 | p95/p99 latency、query time、cache hit、payload size |
+| 资源异常 | CPU、memory、GC、connection pool、queue depth |
+
+默认使用能复现症状的最小指标。不要同时优化所有指标。
+
+## 常见定位方向
+
+- 前端首屏：大图片、render-blocking CSS/JS、bundle 过大、慢 TTFB。
+- 前端交互：长任务、重复渲染、过大 DOM、同步计算。
+- 数据加载：瀑布请求、N+1、过大 payload、缺少分页。
+- 后端接口：缺索引、锁等待、连接池耗尽、重复计算。
+- 内存/CPU：无界缓存、泄漏、正则回溯、同步重计算。
+
+## 修复纪律
+
+- 先证明瓶颈，再改代码。
+- 一次只优化一个瓶颈。
+- 保留 before / after 数字。
+- 小收益大复杂度的优化要默认拒绝。
+- 性能关键路径改动要补 benchmark、监控或预算门禁。
+
+## 输出契约
+
+```text
+Performance evidence:
+- Symptom:
+- Target:
+- Baseline:
+- Bottleneck:
+- Change:
+- After:
+- Regression guard:
+- Trade-off:
 ```
 
-**Enforce in CI:**
-```bash
-# Bundle size check
-npx bundlesize --config bundlesize.config.json
+推荐结论：
 
-# Lighthouse CI
-npx lhci autorun
+```text
+Recommendation: <optimize / monitor / defer / revert> because <baseline, measured impact, complexity cost, and rejected alternative>.
 ```
 
-## See Also
-
-For detailed performance checklists, optimization commands, and anti-pattern reference, see `references/performance-checklist.md`.
-
-
-## Common Rationalizations
-
-| Rationalization | Reality |
-|---|---|
-| "We'll optimize later" | Performance debt compounds. Fix obvious anti-patterns now, defer micro-optimizations. |
-| "It's fast on my machine" | Your machine isn't the user's. Profile on representative hardware and networks. |
-| "This optimization is obvious" | If you didn't measure, you don't know. Profile first. |
-| "Users won't notice 100ms" | Research shows 100ms delays impact conversion rates. Users notice more than you think. |
-| "The framework handles performance" | Frameworks prevent some issues but can't fix N+1 queries or oversized bundles. |
-
-## Red Flags
-
-- Optimization without profiling data to justify it
-- N+1 query patterns in data fetching
-- List endpoints without pagination
-- Images without dimensions, lazy loading, or responsive sizes
-- Bundle size growing without review
-- No performance monitoring in production
-- `React.memo` and `useMemo` everywhere (overusing is as bad as underusing)
-
-## Verification
-
-After any performance-related change:
-
-- [ ] Before and after measurements exist (specific numbers)
-- [ ] The specific bottleneck is identified and addressed
-- [ ] Core Web Vitals are within "Good" thresholds
-- [ ] Bundle size hasn't increased significantly
-- [ ] No N+1 queries in new data fetching code
-- [ ] Performance budget passes in CI (if configured)
-- [ ] Existing tests still pass (optimization didn't break behavior)
+没有 baseline 和 after 数据，不要声明性能优化成立。

package/vendor/packages/toolkit/src/content/skills/planning-and-task-breakdown/body.md

@@ -28,18 +28,53 @@
    - Files likely touched
 5. 排出顺序，并设置阶段性检查点
 
+## 提问纪律
+
+- 能从规格、代码、配置、测试或用户原话判断的，不问。
+- 只有缺失信息会改变架构、数据模型、任务顺序、破坏性操作或并行边界时才问。
+- 一轮最多问 1-3 个关键问题，问题要说明选择会避免什么风险或解锁什么能力。
+- 用户已经给出偏好时，把它写进计划假设；不要把偏好扩展成长期配置或跨会话记忆授权。
+
+## 计划产物要求
+
+计划不是任务名列表，至少要包含：
+
+- `decision log`：关键取舍和采用原因
+- `evidence`：读取过的规格、代码、配置、测试或上游证据
+- `open risks`：尚未证明的风险和验证方式
+- `fan-out eligibility`：是否能并行、按哪些文件或模块拆、是否需要 `zc team plan`
+- `fan-in gate`：实现后如何合流、审查、验证和清理
+
+## 决策日志格式
+
+每个关键取舍都要写成可审查的推荐，而不是只写“建议这样做”：
+
+```text
+Recommendation: <chosen action> because <evidence and trade-off>.
+- Chosen:
+- Rejected alternative:
+- Evidence:
+- Cost / risk:
+- Verification gate:
+```
+
+理由必须说明被放弃的替代方案，以及当前选择为什么更适合本任务。不能只写“更稳”“更简单”“更符合最佳实践”。
+
 ## 成功标准
 
 - 每个任务都能独立实现、测试和验证
 - 任务粒度足够小，不会一次触碰过多文件
 - 依赖顺序和可并行项是显式的
 - 人类看完计划后能明确判断“方案对不对”
+- 计划中的问题和风险都能落到后续验证命令或审查项
+- 并行任务必须有明确文件所有权或隔离理由
 
 ## 相关原则
 
 - 计划服务实现，不是形式化文档
 - 先控制复杂度，再讨论并行度
 - 任务必须能验证，不能只写动作名
+- 计划阶段发现的问题要进入计划本身，不能只留在聊天里
 
 ## 与其他技能的衔接