Component Inspector Generator
기술지정된 React/Next.js 구성요소에 대해 격리된 개발 검사 경로와 실시간 상태 디버거를 스캐폴딩하고 생성합니다. 상태를 수정 가능, 속성, 계산됨 카테고리로 나누고, 즉시 고정 로더가 있는 일반 영어 테스트 확인 고정을 포함하고, 고정된 '최종 업데이트' 타임스탬프 칩을 삽입하고, 트리 셰이킹 동적 가져오기를 사용하여 번들 크기가 0인 프로덕션 제외를 적용합니다.
이 스킬을 사용하려면 로그인하세요.
Google 개발자 프로필로 로그인하여 Build It! 시리즈에 사용된 전체 기술을 확인하고 복사하세요.
개발자 프로필 필요
개발자 프로필을 사용할 수 없습니다. Workspace 관리자에게 이 기능을 사용 설정하도록 요청하세요.
개발자 프로필 만들기
무료 Google 개발자 프로필을 만들어 모든 Build It! 기술, 규칙, 프롬프트, 아티팩트를 활용하세요.
Builder Central에 가입하여 활용하기
클릭 한 번으로 무료 빌더 멤버십 배지를 신청하여 모든 Build It! 기술, 규칙, 프롬프트, 아티팩트를 활용해 보세요.
Google Antigravity에서 설치 및 사용하는 방법
AI 코딩 에이전트가 요청 시 모든 React/Next.js 구성요소에 대해 격리된 개발 전용 구성요소 검사기 경로를 스캐폴딩할 수 있도록 이 기술을 Google Antigravity 작업공간에 추가하세요.
- 프로젝트 작업공간에
.agents/skills/component-inspector-generator/폴더를 만듭니다(또는 Google Antigravity 맞춤설정 > 기술을 열어 작업공간 기술을 추가합니다). - 아래의 전체 마크다운 정의를 해당 폴더 내에
SKILL.md로 저장합니다. - 구성요소를 격리하고 싶을 때마다 호출합니다. 예를 들면 다음과 같습니다. "component-inspector-generator 스킬을 사용하여 DailyWorkoutProposalCard의 개발 검사기를 만듭니다."
- 이 스킬을 Component Inspector Updater 및 세션 범위 Inspector Editing Mode 규칙과 함께 사용하면 구성요소가 발전함에 따라 검사기를 자동으로 동기화할 수 있습니다.
구성요소 검사기 생성기 스킬 정의
이 전체 스킬 정의를 작업공간에 SKILL.md로 복사합니다.
SKILL.md (.agents/skills/component-inspector-generator/SKILL.md)
---
name: component-inspector-generator
description: >-
Scaffolds and generates an isolated development inspection route and live state debugger
for any specified React/Next.js component. Divides state into Editable, Props, and Computed
categories, includes plain-English test verification fixtures with instant fixture loaders,
embeds a fixed 'Last Updated' timestamp chip, and enforces zero-bundle-size production
exclusion using tree-shaken dynamic imports.
---
# Component Inspector Generator Skill
Use this skill whenever you need to create a dedicated, isolated development inspection route and live state workbench for a component in this application (similar to `/dev/current-set-card`).
---
## 1. Core Principles & Architecture
Every component inspector created with this skill MUST satisfy four core architectural rules:
1. **Standalone Canvas**: The component is rendered on its own without global navigation bars, headers, or distracting app shells. It lives inside a mobile-constrained preview viewport (~400px width).
2. **Three-Tier State Division**:
- **Editable State (Interactive)**: State that changes during active user operation (e.g. input fields, checkboxes, toggles). Can be changed both directly inside the component and via the inspector controls (two-way sync).
- **State from Props (Configurable)**: Static/parent configuration passed into the component (e.g. titles, counts, entity arrays). The inspector provides interactive controls and collection modifiers (add/delete items) to test different configurations.
- **Computed State (Read-Only / Derived)**: Values derived reactively using `useMemo` from Editable and Prop state (e.g. volumes, percentages, 1RM estimates, status badges). Marked with lock icons and cannot be directly mutated.
3. **Plain-English Test Fixtures**:
- Every relevant test case from the test suites or specifications is represented as a test card with clear, plain-English user descriptions (no code jargon or raw test IDs in the description).
- Each test card displays a live active status indicator (`● ACTIVE PASSING` vs `IDLE`).
- Each test card has an interactive `[Load Test Fixture]` button that instantly updates the inspector's state to recreate that test scenario in the live canvas.
4. **Zero Production Bundle Footprint (Tree-Shaking)**:
- The heavy inspector component lives in `src/dev/inspectors/[ComponentName]Inspector.tsx` outside the Next.js routing tree.
- The App Router page in `src/app/dev/[component-slug]/page.tsx` is a lightweight tree-shaken stub that conditionally dynamic-imports the inspector only when `process.env.NODE_ENV === 'development'`, and calls `notFound()` in production.
- The bundler completely removes the inspector code, mock fixtures, and test data from production builds (`npm run build`).
5. **Fixed Generation Timestamp Chip**:
- Because inspector pages do not rely on runtime introspection, they reflect a manual snapshot at a fixed point in time.
- A constant `const GENERATED_AT = 'YYYY-MM-DD HH:MM [TIMEZONE]';` must be defined at the top of the inspector file and rendered in the header as a `data-testid="last-updated-chip"` badge.
6. **Expandable Hierarchy Navigator Drawer**:
- Every inspector renders `<InspectorNavigationDrawer activeSlug="[component-slug]" />` on the left of its header.
- Provides an expandable slide-out drawer organized by the application's component hierarchy for instant navigation between created inspectors.
- **Only Created Components**: The drawer and registry ONLY display components that actually have an active inspector created. Never pre-populate speculative uncreated components or placeholders.
- **Scaffold Shared Dev Files if Missing**: If `src/dev/registry.ts` or `src/dev/components/InspectorNavigationDrawer.tsx` do not already exist, create them first.
- Any new component scaffolded with this skill must be registered in `src/dev/registry.ts`.
7. **No Automatic Page-Level Scrolling**:
- The inspector page and preview components must NEVER trigger automatic window- or page-level scrolling (e.g. via `element.scrollIntoView()` or viewport jumping) when settings change, presets are loaded, or test fixtures are activated.
- Any internal list auto-scrolling (e.g. chat feeds, exercise logs) must be strictly confined to that element's own container using `containerRef.current.scrollTop = containerRef.current.scrollHeight`. The outer browser viewport must remain stationary so the user's focus on the controls is never disrupted.
8. **Inspector Directory Home (`/dev`) & Floating Dev Trigger**:
- A central directory route at `/dev` (`src/app/dev/page.tsx` and `src/dev/inspectors/DevInspectorHome.tsx`) provides an expanded dashboard of all created components organized by hierarchy, with search, domain filtering, and launch links.
- A floating pill button (`src/dev/components/DevModeFloatingTrigger.tsx`) is mounted in `src/app/layout.tsx` strictly in development (`process.env.NODE_ENV === 'development'`) to allow jumping into the inspector directory from normal application views.
- If missing, both the home route and floating button must be created on-demand during component generation, with zero production bundle impact.
> **Skill Maintenance Policy**: Updates to this skill must reflect generic architectural standards that apply to all component inspectors across the app. Do not update this skill for one-off requests for individual components (e.g. adding a specific preset or scenario to a single component).
---
## 2. Step-by-Step Generation Workflow
When requested to create an inspection page for a target component:
### Step 1: Analyze the Component
1. Read the target component file (e.g., `src/components/[category]/[ComponentName].tsx`).
2. Catalog all props accepted by `interface [ComponentName]Props`.
3. Categorize all state variables into:
- **Editable State**: User inputs and mutable interactions (e.g. weights, reps, form fields, toggle flags).
- **Props State**: External configuration (e.g. title, step count, target values, history lists).
- **Computed State**: Derived metrics and calculations (e.g. volume, progress percentage, completion status).
4. Identify all test cases from existing test suites (e.g. in `scripts/` or `docs/architecture/client_architecture_spec.md`) relevant to this component.
### Step 2: Create the Heavy Inspector Component
Path: `src/dev/inspectors/[ComponentName]Inspector.tsx`
Use the standard layout template below. Ensure it includes:
- Top sticky header with `<InspectorNavigationDrawer activeSlug="[component-slug]" />`, `DEV INSPECTOR` tag, `<code><[ComponentName] /></code>`, the `Last Updated` chip, and quick scenario presets (e.g. *Standard*, *Completed*, *Fresh*).
- 2-Column main grid:
- Left column (`lg:col-span-5`): Standalone Component Canvas wrapped in mobile width container (`max-w-md`), plus a guidance tip box.
- Right column (`lg:col-span-7`): 3-Category State Inspector Dashboard:
- **1. Editable State** (inputs, `+`/`-` steppers, status toggle button)
- **2. State from Props** (text/numeric inputs, plus collection managers with `[Add Item]` and `[Delete]` buttons)
- **3. Computed State** (grid of read-only derived value cards with lock badges)
- Full-width bottom row (`lg:col-span-12`): Plain-English Component Test & Verification Suite with `[Load Test Fixture]` buttons.
### Step 3: Register in Component Hierarchy & Ensure Shared Dev Infrastructure
Files:
- `src/dev/registry.ts`
- `src/dev/components/InspectorNavigationDrawer.tsx`
- `src/dev/inspectors/DevInspectorHome.tsx` & `src/app/dev/page.tsx`
- `src/dev/components/DevModeFloatingTrigger.tsx` & `src/app/layout.tsx`
1. **If `src/dev/registry.ts` does not exist**: Create it with the base TypeScript interfaces (`InspectorComponentItem`, `InspectorCategory`) and export `INSPECTOR_HIERARCHY: InspectorCategory[] = []`.
2. **If `src/dev/components/InspectorNavigationDrawer.tsx` does not exist**: Create it so that `<InspectorNavigationDrawer />` is available to import in every inspector header.
3. **If `src/dev/inspectors/DevInspectorHome.tsx` or `src/app/dev/page.tsx` does not exist**: Create the central directory home route listing created components from `INSPECTOR_HIERARCHY`.
4. **If `src/dev/components/DevModeFloatingTrigger.tsx` or its integration in `src/app/layout.tsx` does not exist**: Create the trigger button and dynamically import it into `RootLayout` guarded by `process.env.NODE_ENV === 'development'`.
5. **Register the target component**: Add an entry for this newly created component under its domain category in `INSPECTOR_HIERARCHY` (create the category entry if it doesn't already exist):
```ts
{
id: '[component-slug]',
name: '[ComponentName]',
slug: '[component-slug]',
type: 'component', // or 'view'
routePath: '/dev/[component-slug]',
description: 'Plain-English summary of what this component renders and does',
}
```
> **CRITICAL**: Only include components that have actually been created. Never include uncreated, planned, or placeholder components in the registry.
### Step 4: Create the Route Stub
Path: `src/app/dev/[component-slug]/page.tsx`
(Optionally create alias re-export at `src/app/inspect/[component-slug]/page.tsx`):
```tsx
import { notFound } from 'next/navigation';
import dynamic from 'next/dynamic';
const [ComponentName]Inspector =
process.env.NODE_ENV === 'development'
? dynamic(() => import('@/dev/inspectors/[ComponentName]Inspector'), {
loading: () => (
<div className="min-h-screen bg-[#0a0b0e] flex items-center justify-center text-gray-400">
Loading Dev Inspector...
</div>
),
})
: null;
export default function [ComponentName]DevPage() {
if (process.env.NODE_ENV !== 'development' || ![ComponentName]Inspector) {
notFound();
}
return <[ComponentName]Inspector />;
}
```
### Step 5: Verification
1. Run `npx tsc --noEmit` to verify TypeScript types compile with 0 errors.
2. **Dev Server Safe Build Verification**:
- For routine iterations, rely on `npx tsc --noEmit`.
- Never run raw `npm run build` while a local `next dev` server is active, because `next build` overwrites `.next/` with production bundles and wipes out active development chunks (causing `MODULE_NOT_FOUND` / 500 errors on the user's dev server).
- If full production tree-shaking verification is needed, run in an isolated directory:
```bash
NEXT_DIST_DIR=.next-build npx next build && rm -rf .next-build
```
---
## 3. Template Reference for `[ComponentName]Inspector.tsx`
```tsx
'use client';
import React, { useState, useMemo } from 'react';
import Link from 'next/link';
import {
Lock,
Edit3,
Sliders,
Plus,
Trash2,
CheckCircle2,
Dumbbell,
Info,
Clock,
} from 'lucide-react';
import { [ComponentName] } from '@/components/.../[ComponentName]';
import { InspectorNavigationDrawer } from '@/dev/components/InspectorNavigationDrawer';
// Fixed generation timestamp for manual static tracking
const GENERATED_AT = 'YYYY-MM-DD HH:MM EDT';
export default function [ComponentName]Inspector() {
// 1. PROPS STATE
const [propA, setPropA] = useState<string>('Sample Value');
// ... other props
// 2. EDITABLE STATE
const [editableVal, setEditableVal] = useState<number>(100);
const [isCompleted, setIsCompleted] = useState<boolean>(false);
// 3. COMPUTED STATE (Derived & Read-Only)
const computedState = useMemo(() => {
return {
// calculations
};
}, [editableVal, isCompleted, propA]);
return (
<div className="min-h-screen bg-[#0a0b0e] text-gray-100 flex flex-col">
{/* Sticky Header */}
<header className="border-b border-[#262930] bg-[#111317] px-6 py-3.5 sticky top-0 z-40">
<div className="max-w-7xl mx-auto flex flex-wrap items-center justify-between gap-3">
<div className="flex items-center gap-3">
<InspectorNavigationDrawer activeSlug="[component-slug]" />
<span className="px-2.5 py-1 rounded bg-[#a3e635]/15 border border-[#a3e635]/40 text-[#a3e635] text-xs font-mono font-bold tracking-wider uppercase">
DEV INSPECTOR
</span>
<h1 className="text-base font-bold text-white flex items-center gap-2">
<code><[ComponentName] /></code>
</h1>
<span
data-testid="last-updated-chip"
className="flex items-center gap-1.5 px-2.5 py-1 rounded-full bg-[#181a20] border border-[#262930] text-[11px] font-mono text-gray-300 shadow-sm"
title="Manual snapshot generation timestamp"
>
<Clock className="w-3.5 h-3.5 text-amber-400" />
<span className="text-gray-500 font-medium">Last Updated:</span>
<span className="font-bold text-gray-200">{GENERATED_AT}</span>
</span>
</div>
{/* Quick Presets */}
<div className="flex items-center gap-2 text-xs">
<span className="text-gray-400 font-medium">Quick Presets:</span>
{/* preset buttons */}
</div>
</div>
</header>
{/* Main Grid */}
<main className="max-w-7xl mx-auto w-full p-6 grid grid-cols-1 lg:grid-cols-12 gap-8 flex-1">
{/* Left: Component Canvas */}
<section className="lg:col-span-5 flex flex-col gap-4">
<div className="bg-[#0e0f12] p-5 rounded-2xl border border-[#262930] shadow-2xl relative flex flex-col justify-center min-h-[380px]">
<div className="max-w-md mx-auto w-full">
<[ComponentName] {...props} />
</div>
</div>
</section>
{/* Right: 3-Category State Inspector */}
<section className="lg:col-span-7 flex flex-col gap-6">
{/* Category 1: Editable State */}
{/* Category 2: Props State */}
{/* Category 3: Computed State */}
</section>
{/* Bottom: Plain-English Test Cases */}
<section className="lg:col-span-12 bg-[#121418] border border-[#262930] rounded-2xl p-6 shadow-xl flex flex-col gap-6">
{/* Grid of test fixture cards with [Load Test Fixture] buttons */}
</section>
</main>
</div>
);
}
```