diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6f29b6b..1e4c317 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -897,6 +897,26 @@ "subagent" ] }, + { + "name": "fe-rail", + "source": "./plugins/fe-rail", + "description": "Harness dedicated to frontend projects. Supports Next.js App Router / Vite SPA + TypeScript, Tailwind v3/v4, shadcn/ui. Automates the spec→build→review→PR cycle.", + "version": "1.14.1", + "author": { + "name": "Seungho", + "email": "seungho5623@gmail.com" + }, + "category": "Development Engineering", + "homepage": "https://github.com/ccplugins/awesome-claude-code-plugins/tree/main/plugins/fe-rail", + "keywords": [ + "frontend", + "nextjs", + "vite", + "typescript", + "harness", + "workflow" + ] + }, { "name": "enterprise-onboarding-specialist", "source": "./plugins/enterprise-onboarding-specialist", @@ -1672,4 +1692,4 @@ ] } ] -} \ No newline at end of file +} diff --git a/README.md b/README.md index e4de615..819fee1 100644 --- a/README.md +++ b/README.md @@ -123,6 +123,7 @@ Install or disable them dynamically with the `/plugin` command — enabling you - [code-architect](./plugins/code-architect) - [desktop-app-dev](./plugins/desktop-app-dev) - [enterprise-integrator-architect](./plugins/enterprise-integrator-architect) +- [fe-rail](./plugins/fe-rail) - [flutter-mobile-app-dev](./plugins/flutter-mobile-app-dev) - [frontend-developer](./plugins/frontend-developer) - [mobile-app-builder](./plugins/mobile-app-builder) diff --git a/plugins/fe-rail/.claude-plugin/marketplace.json b/plugins/fe-rail/.claude-plugin/marketplace.json new file mode 100644 index 0000000..aa53405 --- /dev/null +++ b/plugins/fe-rail/.claude-plugin/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "fe-rail-market", + "description": "Claude Code plugin marketplace for frontend projects — fe-rail", + "owner": { + "name": "Seungho", + "email": "seungho5623@gmail.com" + }, + "plugins": [ + { + "name": "fe-rail", + "description": "Harness dedicated to frontend projects. Supports Next.js App Router / Vite SPA + TypeScript, Tailwind v3/v4, shadcn/ui. Automates the spec→build→review→PR cycle.", + "category": "engineering", + "tags": ["frontend", "nextjs", "typescript", "harness", "workflow"], + "source": { + "source": "github", + "repo": "sh5623/fe-rail" + } + } + ] +} diff --git a/plugins/fe-rail/.claude-plugin/plugin.json b/plugins/fe-rail/.claude-plugin/plugin.json new file mode 100644 index 0000000..da77038 --- /dev/null +++ b/plugins/fe-rail/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "fe-rail", + "description": "Harness dedicated to frontend projects. Supports Next.js App Router / Vite SPA + TypeScript, Tailwind v3/v4, shadcn/ui. Automates the spec→build→review→PR cycle.", + "version": "1.14.1", + "author": { + "name": "Seungho", + "email": "seungho5623@gmail.com" + }, + "homepage": "https://github.com/sh5623/fe-rail", + "repository": "https://github.com/sh5623/fe-rail", + "license": "MIT" +} diff --git a/plugins/fe-rail/.github/CODE_OF_CONDUCT.md b/plugins/fe-rail/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..d86f035 --- /dev/null +++ b/plugins/fe-rail/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,67 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior: + +- The use of sexualized language or imagery, and sexual attention or advances + of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, + without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Project maintainers are responsible for clarifying and enforcing our standards +of acceptable behavior and will take appropriate and fair corrective action in +response to any behavior they deem inappropriate, threatening, offensive, or +harmful. + +## Scope + +This Code of Conduct applies within all community spaces (issues, pull +requests, discussions) and also applies when an individual is officially +representing the community in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the maintainer at **seungho5623@gmail.com**. All complaints will +be reviewed and investigated promptly and fairly. + +All maintainers are obligated to respect the privacy and security of the +reporter of any incident. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html diff --git a/plugins/fe-rail/.github/CONTRIBUTING.md b/plugins/fe-rail/.github/CONTRIBUTING.md new file mode 100644 index 0000000..5868ef8 --- /dev/null +++ b/plugins/fe-rail/.github/CONTRIBUTING.md @@ -0,0 +1,76 @@ +# Contributing to fe-rail + +Thanks for considering a contribution. `fe-rail` is a Claude Code plugin (harness) for +frontend projects — not an application itself. Changes here affect every consumer project +that installs the plugin, so please read this before opening a PR. + +## Before you start + +- Skim `CLAUDE.md` for the harness architecture (agents / hooks / skills layers) and the + model-tier policy. +- Check open issues and PRs first to avoid duplicate work. +- For anything non-trivial (new agent, new hook, changed workflow), open an issue to + discuss the approach before writing code. + +## Development setup + +```bash +git clone https://github.com/sh5623/fe-rail +cd fe-rail +``` + +There's no build step — agents/skills/hooks are plain Markdown + shell. Install the +plugin locally in a test project to exercise changes end to end: + +```bash +/plugin marketplace add /path/to/your/local/fe-rail +/plugin install fe-rail@fe-rail-market +``` + +Hooks only load at session start — restart your Claude Code session after installing +or editing a hook for the change to take effect. + +## Testing your change + +Run the deterministic regression suite before opening a PR — it checks hook behavior, +profile toggles, and self-lint (agent model aliases, skill frontmatter, `hooks.json` +integrity): + +```bash +bash eval/run.sh +``` + +A failing run blocks the PR. If you added a new hook or agent, extend `eval/run.sh` +with coverage for it. + +## Making changes + +- **Agents** (`agents/*.md`): keep `model` as an alias (`opus`/`sonnet`/`haiku`), never + a pinned version. Respect the tier policy in `CLAUDE.md` — don't upgrade an agent to + `opus` without a judgment/gate justification. +- **Hooks** (`hooks/`): blocking hooks (exit 2) must have a clear, low-false-positive + trigger. Prefer warning (stderr) over blocking when uncertain. Wire new hooks into + `hooks/hooks.json` and the profile logic in `hooks/scripts/profile-lib.sh`. +- **Skills** (`skills/*/SKILL.md`): keep `allowed-tools` scoped to what the skill + actually needs. If a skill delegates to sub-agents, its `allowed-tools` must include + `Task`/`Agent`. +- **Docs**: `README.md` is the canonical (English) doc; keep `README.ko.md` in sync. + `CLAUDE.md` targets the agent, not humans — update both when behavior changes. + +## Commit / PR style + +- Conventional-ish prefixes are used in this repo's history (`fix:`, `feat:`, `chore:`, + `docs:`) — follow the existing log (`git log --oneline`) for tone. +- Keep PRs scoped to one concern. Don't bundle unrelated agent/hook/doc changes. +- Fill out the PR template checklist, including the `eval/run.sh` result. + +## Reporting bugs / requesting features + +Use the issue templates (Bug report / Feature request). Include which consumer project +type you're testing against (Next.js App Router, Vite + TanStack Router, Vite + React +Router 7, monorepo) — behavior is framework-detected and can diverge. + +## Code of Conduct + +This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). By participating +you agree to abide by it. diff --git a/plugins/fe-rail/.github/ISSUE_TEMPLATE/bug_report.md b/plugins/fe-rail/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..6940251 --- /dev/null +++ b/plugins/fe-rail/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,54 @@ +--- +name: Bug report +about: Something in the harness (agent, hook, skill) isn't behaving as documented +title: "[Bug] " +labels: bug +assignees: '' +--- + +## Describe the bug + +A clear description of what went wrong (e.g. a hook blocked something it shouldn't +have, an agent used the wrong model tier, a skill failed to trigger). + +## Which layer is affected? + +- [ ] Agent (which one: ) +- [ ] Hook (which one: ) +- [ ] Skill (which one: ) +- [ ] Docs (CLAUDE.md / README) + +## Consumer project type + +- [ ] Next.js App Router +- [ ] Vite + React (TanStack Router) +- [ ] Vite + React (React Router 7) +- [ ] Monorepo +- [ ] Other: + +## Steps to reproduce + +1. +2. +3. + +## Expected behavior + +What you expected to happen. + +## Actual behavior + +What actually happened. Paste relevant stderr/stdout from the hook or agent output if +available. + +## Environment + +- fe-rail version: +- Claude Code version: +- OS: +- Package manager (npm/pnpm/yarn/bun): + +## Additional context + +`FE_RAIL_HOOK_PROFILE` / `FE_RAIL_DISABLED_HOOKS` values if non-default, and anything +else relevant. diff --git a/plugins/fe-rail/.github/ISSUE_TEMPLATE/feature_request.md b/plugins/fe-rail/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..7ce83fa --- /dev/null +++ b/plugins/fe-rail/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,40 @@ +--- +name: Feature request +about: Suggest a new agent, hook, skill, or workflow improvement +title: "[Feature] " +labels: enhancement +assignees: '' +--- + +## Problem + +What's missing or painful in the current spec → build → review → PR workflow? Describe +the gap, not the solution yet. + +## Proposed solution + +What you'd like to see added or changed. If this maps to a specific harness layer, +say which: + +- [ ] New agent +- [ ] New/changed hook +- [ ] New/changed skill +- [ ] Workflow change (e.g. `fe-start` sequencing) +- [ ] MCP integration +- [ ] Other: + +## Alternatives considered + +Any other approaches you thought about, and why you didn't go with them. + +## Consumer project type this targets + +- [ ] Next.js App Router +- [ ] Vite + React (TanStack Router) +- [ ] Vite + React (React Router 7) +- [ ] Monorepo +- [ ] Framework-agnostic + +## Additional context + +Links, examples, or references (e.g. a similar pattern in another Claude Code plugin). diff --git a/plugins/fe-rail/.github/PULL_REQUEST_TEMPLATE.md b/plugins/fe-rail/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..cd4a17b --- /dev/null +++ b/plugins/fe-rail/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,35 @@ +## Summary + +What does this PR change and why? (1-3 bullets) + +- + +## Layer(s) touched + +- [ ] Agent (`agents/*.md`) +- [ ] Hook (`hooks/*.sh`, `hooks/hooks.json`) +- [ ] Skill (`skills/*/SKILL.md`) +- [ ] Docs (`CLAUDE.md`, `docs/*.md`, `README*.md`) +- [ ] Eval (`eval/run.sh`) + +## Checklist + +- [ ] `bash eval/run.sh` passes (hook behavior, profile toggles, self-lint) +- [ ] Agent `model` fields use aliases (`opus`/`sonnet`/`haiku`), not pinned versions +- [ ] New/changed hooks are wired into `hooks/hooks.json` and, if blocking, justified + (low false-positive trigger — see `CLAUDE.md` hook profile policy) +- [ ] Skill `allowed-tools` stays scoped to what the skill needs (includes `Task`/`Agent` + only if it delegates) +- [ ] `README.md` and `README.ko.md` updated together if user-facing behavior changed +- [ ] `CLAUDE.md` updated if agent/hook/skill structure changed +- [ ] `.claude-plugin/plugin.json` version bumped if this PR changes agent/hook/skill + runtime behavior (so consumers detect the update) — not needed for docs-only changes + +## Test plan + +How did you verify this? (e.g. installed in a local test project, ran a specific +workflow end to end, `eval/run.sh` output) + +## Related issue + +Closes # diff --git a/plugins/fe-rail/.gitignore b/plugins/fe-rail/.gitignore new file mode 100644 index 0000000..4fe3e20 --- /dev/null +++ b/plugins/fe-rail/.gitignore @@ -0,0 +1,3 @@ +.claude/ + +.DS_Store \ No newline at end of file diff --git a/plugins/fe-rail/CLAUDE.md b/plugins/fe-rail/CLAUDE.md new file mode 100644 index 0000000..82d62dd --- /dev/null +++ b/plugins/fe-rail/CLAUDE.md @@ -0,0 +1,279 @@ +# fe-rail — Claude 에이전트 컨텍스트 + +> **하네스 엔지니어링 원칙**: Agent = Model + Harness +> 이 저장소는 프론트엔드 프로젝트 전용 Claude Code 플러그인이다. +> 다른 프로젝트에 설치하여 사용하는 **하네스(Harness)** 이지, 그 자체가 애플리케이션 프로젝트가 아니다. + +--- + +## 이 저장소의 목적 + +`fe-rail`은 프론트엔드 개발 워크플로우를 표준화하는 Claude Code 플러그인이다. +React + TypeScript 환경(Next.js App Router / Vite SPA 모두)을 대상으로 하며, +**spec → build → review → PR** 사이클을 강제하여 에이전트 출력 품질을 일관되게 유지한다. + +--- + +## 하네스 구조 (Harness Layers) + +``` +fe-rail/ +├── CLAUDE.md ← 에이전트 컨텍스트 (이 파일) +├── agents/ ← 15개 서브에이전트 (spec·build·review·PR 단계별) +│ ├── fe-analyst.md ← spec: 요구사항 갭 분석 +│ ├── fe-deck-reader.md ← spec: PPT 기획서 분해 (정책·화면·흐름) +│ ├── fe-vision.md ← spec: 화면 분석 · verify: 시각 충실도 대조(visual-verdict) +│ ├── fe-researcher.md ← spec: 외부 문서 조사 +│ ├── fe-architect.md ← spec: 아키텍처 자문 +│ ├── fe-explorer.md ← build: 코드베이스 탐색 +│ ├── fe-test-author.md ← build: BDD·TDD 테스트 작성 +│ ├── fe-build-fixer.md ← build: tsc·린터(ESLint/Biome) 오류 수정 +│ ├── fe-reviewer.md ← review: 4축 코드 리뷰 +│ ├── fe-a11y-auditor.md ← review: a11y 정밀 감사 +│ ├── fe-perf-auditor.md ← review: 성능 정밀 감사 +│ ├── fe-test-runner.md ← review: 테스트 실행·분류 +│ ├── fe-refactor-advisor.md ← review: 리팩토링 분석 +│ ├── fe-git-operator.md ← PR: 커밋 분리·스테이징·커밋 본문 작성 (fix=증상·원인·해결 / feat=추가·핵심·영향) +│ └── fe-pr-author.md ← PR: PR 본문 작성 (성격별 🐛/✨ 블록 + 리뷰 포인트) + `gh pr create` +├── hooks/ ← SessionStart·Pre/PostToolUse·Stop·Notification 훅 (hooks.json 배선) +│ ├── session-init.sh ← SessionStart: 원격 버전 체크(하루 1회, GitHub raw) + 권장 권한 미설정 안내 +│ ├── guard·write-guard·task-guard·config-protection ← 차단(exit 2): 위험명령·민감파일·인젝션·설정 약화 +│ ├── read-guard·lint-fix·nextjs-guard·design-nudge·quality-gate·doc-sync-check ← 경고(stderr) +│ ├── notify.sh ← Notification(옵션): terminal-notifier 배너 (setup-notifier.sh 로 활성화, hooks.json 미배선) +│ └── scripts/ ← profile-lib(프로파일/토글)·setup-permissions(권장 Bash 권한 → settings.local.json)·setup-notifier(notify 활성화) +├── skills/ +│ ├── fe-spec/ ← 기획 → 스펙 변환 +│ ├── fe-build/ ← 스펙 → 코드 구현 +│ ├── fe-review/ ← 4축 코드 리뷰 +│ ├── fe-start/ ← 원스톱 자동화 (spec→PR) +│ └── fe-doc-sync/ ← 설치된 사용자 프로젝트 스캔 → 그 프로젝트의 CLAUDE.md·README.md 동기화 +├── eval/ +│ └── run.sh ← 회귀 eval (훅 동작·프로파일·self-lint, 결정적·CI용) +├── docs/ ← framework-rules.md · monorepo.md (CLAUDE.md 가 @import) +└── .claude-plugin/ ← plugin.json · marketplace.json (플러그인 메타데이터) +``` + +> 권한(Bash 화이트리스트)은 **소비자 프로젝트의 `.claude/settings.json`** 에서 설정한다 — 이 플러그인은 권한 파일을 배포하지 않는다(아래 "권한 및 보안" 참조). + +### 레이어별 역할 + +| 레이어 | 파일 | 역할 | +|--------|------|------| +| **CLAUDE.md** | 이 파일 | 에이전트가 프로젝트를 이해하는 최우선 컨텍스트 | +| **Skills** | `skills/*/SKILL.md` | 작업 유형별 전문화된 지침 (도구 제한 포함) | +| **Agents** | `agents/*.md` | spec·build·review·PR 단계별 격리 서브에이전트 (15개) | +| **Hooks** | `hooks/hooks.json` | SessionStart·Pre/PostToolUse·Stop·Notification 이벤트 자동 실행 사이드이펙트 | +| **Permissions** | 소비자 `.claude/settings.json` | Bash 화이트리스트로 PR 단계 권한 프롬프트 축소 (플러그인엔 미포함) | + +### 훅 프로파일 · 회귀 eval + +- **프로파일**: `FE_RAIL_HOOK_PROFILE`(`minimal` | `standard`(기본) | `strict`) + `FE_RAIL_DISABLED_HOOKS="a,b"` 로 소비자 환경에서 훅 강도를 조절한다(플러그인 파일 수정 없이). `minimal`=안전 차단기만(guard·write-guard·task-guard·config-protection), `standard`=+품질 경고 전부. **프로파일 하향으로는 차단기가 꺼지지 않으며**, 끄려면 `DISABLED_HOOKS`에 이름을 명시해야 한다. 공유 로직: `hooks/scripts/profile-lib.sh`. 린터·타입체크(tsc) npx 폴백은 기본 꺼짐 — 로컬 바이너리만 쓰고, 필요 시 `FE_RAIL_ALLOW_NPX=1` 로 옵트인한다(자동 훅의 네트워크·미고정 최신버전 부작용 방지). 단 `package.json` 에 `typecheck` 스크립트가 있으면 프로젝트 자신의 lockfile 로 실행되므로 이 옵트인과 무관하게 항상 허용. +- **회귀 eval**: `bash eval/run.sh` — 라이브 모델 없이 훅 동작(차단 사유가 stdout이 아닌 stderr로 전달되는지, 비차단 훅 5개의 안내도 동일하게 stderr로 나가는지 포함)·프로파일·self-lint(agent `model` 별칭·skill frontmatter·`hooks.json` 무결성·위임을 지시하는 스킬의 `allowed-tools`에 Task/Agent 포함 여부·bun `PX` 감지 일관성·`typecheck` 분기의 `references`(tsc -b) 폴백 동반 여부·바이너리+플래그 실행이 `$PM exec` 아닌 `$PX`인지·bare `$PM lint`/`$PM tsc` 금지(→`$PM run lint`/`$PX tsc`)·fe-researcher Context7 이중 접두사(plugin+직접))를 결정적으로 검증(실패 시 exit 1). + +--- + +## 지원 MCP 플러그인 + +하네스가 최적으로 동작하려면 다음 MCP 플러그인이 설치되어 있어야 한다. +각 플러그인은 특정 에이전트의 `tools` 목록에 등록되어 있으며, 없으면 해당 에이전트가 fallback 동작으로 전환된다. + +| MCP | 설치 형태 | 연결 에이전트 | 도구 접두사 | 없을 때 fallback | +|-----|----------|-------------|-----------|----------------| +| **Figma** | claude.ai 계정 커넥터 (`/mcp` → "claude.ai Figma", OAuth) | `fe-vision` | `mcp__claude_ai_Figma__get_design_context`
`mcp__claude_ai_Figma__get_screenshot` (외 get_metadata·get_variable_defs) | 로컬 스크린샷(PNG/JPG)만 분석 | +| **Context7** | Claude Code 플러그인 | `fe-researcher` | `mcp__plugin_context7_context7__resolve-library-id`
`mcp__plugin_context7_context7__query-docs`
(+ `.mcp.json` 등록 대비 `mcp__context7__*` 도 등록) | WebSearch + WebFetch로 문서 조회 | +| **Chrome DevTools** | Claude Code 플러그인 (`ChromeDevTools/chrome-devtools-mcp`) | `fe-perf-auditor`·`fe-a11y-auditor` | `mcp__plugin_chrome-devtools-mcp_chrome-devtools__performance_start_trace`
`mcp__plugin_chrome-devtools-mcp_chrome-devtools__lighthouse_audit` (외 performance_stop_trace·performance_analyze_insight·list_console_messages·list_network_requests·take_snapshot·navigate_page) | 정적 분석(grep 기반 추정치)만 수행 — `--live` 호출 시에만 실측 시도, 미설치면 정적 결과만 | + +> Microsoft 365 (선택 보조): OneDrive/SharePoint 의 PPT 기획서를 가져오는 용도. 단 인터랙티브 OAuth 인증이 필요하고 슬라이드를 시각적으로 렌더해 주지 않을 수 있어, 화면 분석에는 PDF 변환이 더 안전하다. 특정 에이전트에 직접 연결하지 않으며, 가져온 파일은 부모 세션이 PDF/이미지로 변환해 fe-deck-reader 에 전달한다. + +> 도구 접두사는 설치 형태에 따라 달라진다. 플러그인으로 설치하면 `mcp__plugin_<플러그인>_<서버>__*`, 사용자/프로젝트 `.mcp.json`으로 등록하면 `mcp__<서버>__*`, claude.ai 계정 커넥터(OAuth)는 `mcp__claude_ai_<서버>__*` 형식이다. 에이전트 `tools` 목록의 접두사가 실제 설치 형태와 일치해야 도구가 인식되며, 불일치 시 fallback으로만 동작한다. (Figma·Context7 의 플러그인 접두사는 직접 검증됨. Context7 은 `.mcp.json`/`claude mcp add` 등록 대비 `mcp__context7__*` 도 함께 등록해 뒀는데, 이 형태와 Chrome DevTools 행은 명명 규칙 기반 예상 접두사이므로 최초 사용 시 실제 등록된 도구 이름과 대조 확인 권장.) + +### 설치 + +- **Context7** (플러그인): `/plugin install context7@` → `/reload-plugins`. 도구는 `mcp__plugin_context7_context7__*` 로 등록된다. +- **Figma** (claude.ai 계정 커넥터): `/mcp` 실행 → "claude.ai Figma" 선택 → OAuth 인증. 공식 Figma MCP(mcp.figma.com)를 claude.ai가 프록시하며, 도구는 `mcp__claude_ai_Figma__*` 로 등록된다. (Dev Mode 계열 도구는 Dev/Full seat 필요) +- **Chrome DevTools** (플러그인, 스킬 포함): `/plugin marketplace add ChromeDevTools/chrome-devtools-mcp` → `/plugin install chrome-devtools-mcp@chrome-devtools-plugins`. MCP만 필요하면 `claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest` 로도 등록 가능(이 경우 접두사는 `mcp__chrome-devtools__*`). Chromium 기반 브라우저 실행 환경이 필요하다. + +--- + +## 모델 티어 정책 + +각 에이전트의 `model`은 **별칭**(`opus`/`sonnet`/`haiku`)으로 지정한다. 풀 버전 ID를 고정하지 않는다. + +| 티어 | 에이전트 | 기준 | +|------|---------|------| +| **opus** | fe-analyst · fe-architect · fe-reviewer · fe-refactor-advisor | 추론·판단 집약, 게이트 역할 (오탐/누락 비용 큼) | +| **sonnet** | 위·아래를 제외한 실행·도구 계열 전부 | 구현·수정·실행 등 | +| **haiku** | fe-explorer | 단순 코드 탐색, 비용 효율 우선 | + +- **별칭의 의미**: 모델 패밀리 업데이트(예: Opus 4.7 → 4.8) 시 자동으로 최신 티어를 사용한다. 별도 수정 없이 개선이 반영되지만, 플러그인 버전이 같아도 동작이 변동될 수 있다. +- **재현성 점검**: 안정성이 중요한 경우 릴리스마다 현재 별칭 해상도 기준으로 회귀를 확인한다 (`bash eval/run.sh` 로 훅·self-lint 회귀를 자동 검사). +- **티어 변경 원칙**: "전부 opus화" 금지. 고판단 게이트만 선별 상향하고, 탐색·기계적 작업은 저비용 티어를 유지한다. + +--- + +## 워크플로우 + +``` +사용자 요청 + │ + ▼ +fe-spec → feature.md 생성 (사용자 승인 필요) + └─ 에이전트: fe-analyst·fe-deck-reader·fe-vision·fe-researcher·fe-architect + │ + ▼ +fe-build → 타입 → 비즈니스 로직 분리 → 컴포넌트 → 테스트 순서로 구현 + └─ 에이전트: fe-explorer·fe-test-author·fe-build-fixer + │ + ▼ +fe-review → 4축 검토 (타입·성능·a11y·품질) + └─ 에이전트: fe-reviewer·fe-a11y-auditor·fe-perf-auditor·fe-test-runner·fe-refactor-advisor + │ + ▼ +커밋 & PR → git + gh CLI (사용자 승인 필요) + └─ 에이전트: fe-git-operator·fe-pr-author +``` + +**원스톱 자동화**: `fe-start` 스킬이 위 전체 흐름을 자동으로 처리한다. +사람 개입은 "구현할까요?"와 "커밋할까요?" 두 번뿐이다. + +fe-spec → fe-start 핸드오프: fe-spec 의 "다음 단계" 게이트에서 "풀 자동"을 고르면 fe-start 로 이어진다. 이때 "구현할까요?"는 fe-spec 게이트가 대신하므로 fe-start 는 "커밋할까요?"만 묻는다(전체 승인 2회 유지). + +--- + +## 다른 프로젝트에 적용하기 + +### 설치 방법 + +```bash +# Claude Code 내에서 +/plugin marketplace add sh5623/fe-rail +/plugin install fe-rail@fe-rail-market +``` + +### 스킬 호출 + +```bash +/fe-rail:fe-spec # 기능 요구사항 → feature.md +/fe-rail:fe-build # feature.md → 코드 구현 +/fe-rail:fe-review # 코드 리뷰 +/fe-rail:fe-start feature.md # 원스톱 자동화 +/fe-rail:fe-doc-sync # 설치된 프로젝트 스캔 → 그 프로젝트의 CLAUDE.md·README.md 동기화 +``` + +### 설치 후 권장 설정 (소비자 프로젝트) + +에이전트는 **소비자 프로젝트의 컨텍스트를 읽어** 추론한다. 설치 직후 아래를 갖추면 출력 품질이 크게 올라간다. + +1. **프로젝트 CLAUDE.md 생성** — `fe-analyst`·`fe-architect`는 소비자 프로젝트의 CLAUDE.md에서 스택·규칙을 읽는다. 이 플러그인의 CLAUDE.md는 소비자 세션에 로드되지 않으므로, 소비자가 자체 CLAUDE.md를 두지 않으면 에이전트가 빈손으로 분석한다. → `/init` 또는 `/fe-rail:fe-doc-sync` 실행. +2. **Bash 권한 허용 (권장: 자동)** — 소비자 프로젝트 루트에서 `bash /hooks/scripts/setup-permissions.sh` 실행 → 호스트(GitHub/CodeCommit)를 감지해 `Bash(git *)`·PR 명령 권한을 `.claude/settings.local.json`의 `permissions.allow`에 병합한다(확인 1회, 기존 키·값 보존). 미설정이면 PR 단계 에이전트가 매번 권한 프롬프트를 띄운다. 세션 시작 시 미설정이면 안내가 뜬다(끄기: `FE_RAIL_SKIP_SETUP_NUDGE=1`). 수동으로는 `.claude/settings.json`의 `permissions.allow`에 직접 추가. (위험 git 명령은 `guard.sh`가 계속 차단하므로 광범위 allow 라도 안전.) +3. **MCP (선택)** — Figma·Context7·Chrome DevTools 미설치 시 `fe-vision`·`fe-researcher`·`fe-perf-auditor`·`fe-a11y-auditor`는 각각 fallback(로컬 이미지·WebSearch·정적 분석)으로 동작한다. 미리 다 설치할 필요 없이, 각 에이전트가 폴백할 때 **그 자리에서 활성화 명령을 안내(JIT)**하므로 필요할 때 설치하면 된다. 위 "지원 MCP 플러그인" 참조. + +### 대상 프로젝트 유형 + +이 플러그인은 다음 환경에서 동작한다: + +| 환경 | 지원 여부 | 비고 | +|------|----------|------| +| Next.js + TypeScript | ✅ | App Router 기준, RSC 최적화 포함 | +| Vite + React (TanStack Router) | ✅ | 라우트 loader·Zustand 규칙 내장 | +| Vite + React (React Router 7) | ✅ | react-router/react-router-dom 둘 다 인식 · 라우팅/레이아웃 전용 — 서버 데이터는 TanStack Query 단독 소유 | +| Tailwind CSS v3 / v4 (직교) | ✅ | 디자인 토큰·`cn()`·`@apply` 정책·content/purge·대비 점검 — v4 는 CSS-first(`@theme`)·gradient rename·`@reference` 추가 분기 | +| shadcn/ui (직교) | ✅ | UI primitives 격리·`cva()` variant·래핑 패턴 — Tailwind 위에서 동작 | +| 모노레포 | ✅ | 아래 별도 섹션 참조 | + +--- + +## 모노레포 지원 + +@docs/monorepo.md + +--- + +## 프레임워크별 코딩 규칙 + +@docs/framework-rules.md + +--- + +## 공통 품질 기준 (프레임워크 무관) + +모든 구현은 다음 기준을 충족해야 커밋이 허용된다. + +| 항목 | 기준 | +|------|------| +| TypeScript | `any` 타입 0개, strict mode | +| 린트 | 린터(ESLint 또는 Biome) 경고 0개 | +| 테스트 | Vitest + Testing Library, 주요 인터랙션 커버 | +| 접근성 | WCAG AA — `aria-label`, 키보드 네비게이션 | +| 반응형 | 375px / 768px / 1280px 기준 | +| 성능 | 이미지 최적화, 불필요한 리렌더링 없음 | + +### 검증 명령어 + +```bash +# lock 파일로 패키지 매니저를 먼저 감지한 뒤 아래 대응 명령어를 실행 +# pnpm-lock.yaml → pnpm / yarn.lock → yarn / bun.lock(b) → bun / 없으면 → npm +# +# 타입 체크는 프로젝트 `typecheck` 스크립트가 있으면 그것을 우선 사용한다. +# (솔루션 스타일 tsconfig — files:[] + references — 에서는 bare `tsc --noEmit` 이 +# 아무 파일도 검사하지 않으므로 `typecheck` 스크립트 또는 `tsc -b` 를 써야 한다.) + +# 타입 체크 +npx tsc --noEmit # npm +pnpm tsc --noEmit # pnpm +yarn tsc --noEmit # yarn +bun tsc --noEmit # bun + +# 린트 (ESLint 또는 Biome — 프로젝트 설정에 따라) +npm run lint # npm +pnpm lint # pnpm +yarn lint # yarn +bun run lint # bun + +# 테스트 (vitest 기준) +npm test -- --run # npm +pnpm test --run # pnpm +yarn test --run # yarn +bun run test --run # bun (bun test 는 Bun 내장 러너 — vitest 를 돌리려면 run 스크립트 경유) +``` + +--- + +## 에이전트 행동 원칙 + +### 반드시 지킬 것 + +- **스펙 먼저** — `feature.md` 없이 코드 작성 시작 금지 +- **사용자 승인 두 번** — 구현 시작 전, 커밋 전 +- **타입 먼저** — 구현 순서: 타입 정의 → 훅/서비스 → 컴포넌트 → 테스트 +- **검증 후 보고** — 자동 검증(`tsc`, `lint`, `test`) + 완료 기준 게이트(`build`/`e2e` 존재 시 · 고증 화면이면 시각 충실도 대조, fe-start Phase 4.5) 통과 후 완료 선언. "완료"는 `feature.md` 의 완료 기준 충족이다 (리뷰 BLOCK 0 ≠ 완료) + +### 하지 말 것 + +- `any` 타입 사용 +- 스펙 없이 "대충 이런 방향으로" 구현 +- 테스트 없이 완료 선언 +- `console.log`를 코드에 남기기 +- 패키지 경계를 무시한 직접 import (모노레포) +- 에이전트가 자신의 격리 범위(`disallowedTools`)를 벗어나 행동 + +--- + +## 권한 및 보안 + +이 플러그인은 권한 설정 파일을 배포하지 않는다. Bash 권한은 소비자 프로젝트에서 설정한다 — 권장은 `hooks/scripts/setup-permissions.sh`(호스트 감지 → `.claude/settings.local.json`의 `permissions.allow`에 병합, 확인 1회)이고, 수동으로는 `.claude/settings.json`에 직접 추가한다. `settings.local.json`을 쓰는 이유는 개인 로컬 설정이고 `.claude`가 `.gitignore` 대상일 수 있어 팀 공유 파일을 건드리지 않기 위함이다. + +권장 허용 명령어 (PR 단계 에이전트가 매번 프롬프트 없이 동작): +- `Bash(git *)` — 버전 관리 전 범위 (위험 명령은 `guard.sh`가 exit 2 로 차단 — 광범위 allow 의 백스톱) +- `Bash(gh pr *)` — PR 생성·조회 (fe-pr-author) + +> 세션 시작 시 권장 권한이 없으면 `session-init.sh`가 1회 안내한다(끄기: 환경변수 `FE_RAIL_SKIP_SETUP_NUDGE=1`). MCP 는 훅에서 연결 여부를 알 수 없어 세션 안내에 넣지 않고, 각 에이전트가 사용 시점에 JIT 로 안내한다. + +--- + +## 기반 레퍼런스 + +- [Harness Engineering for Coding Agents — Humanlayer](https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents) +- [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) +- [Chachamaru127/claude-code-harness](https://github.com/Chachamaru127/claude-code-harness) +- [garrytan/gstack](https://github.com/garrytan/gstack) diff --git a/plugins/fe-rail/LICENSE b/plugins/fe-rail/LICENSE new file mode 100644 index 0000000..9d63be1 --- /dev/null +++ b/plugins/fe-rail/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 이승호 + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/plugins/fe-rail/README.ko.md b/plugins/fe-rail/README.ko.md new file mode 100644 index 0000000..0756fca --- /dev/null +++ b/plugins/fe-rail/README.ko.md @@ -0,0 +1,192 @@ +# fe-rail + +
+ 한국어 + English + MIT License +
+ +> 프론트엔드 프로젝트 전용 Claude Code 플러그인 +> spec → build → review → PR 자동화 워크플로우. Next.js App Router / Vite SPA(TanStack Router·React Router 7) + TypeScript, Tailwind v3/v4 / shadcn/ui 정식 지원. + +## 설치 + +```bash +claude + +/plugin marketplace add sh5623/fe-rail +/plugin install fe-rail@fe-rail-market +``` + +![fe-rail 워크플로우: spec, build, review, PR](docs/assets/workflow.svg) + +## 사용 예시 + +``` +$ claude +> /fe-rail:fe-spec + +[fe-spec] 요구사항 분석 중... (fe-analyst, fe-architect) +✔ feature.md 생성 완료 — 7개 섹션, 미해결 질문 3건 해소 + +다음 단계? + ❯ 풀 자동 (추천) — fe-start 파이프라인으로 자동 연결 + 구현만 — 스펙 먼저 검토 + 스펙 수정 + +> 풀 자동 + +[fe-start] Phase 2 — 타입 → 훅 → 컴포넌트 → 테스트 구현 중 +✔ 12개 파일 생성, tsc 통과, lint 통과, 테스트 8개 통과 + +커밋하고 PR을 열까요? + ❯ 예 — type별로 분리해서 드래프트 PR 생성 + 아니오 — 변경사항만 남기고 종료 + +> 예 + +✔ 커밋 2개 생성 +✔ feat/product-search-autocomplete 브랜치로 푸시 +✔ 드래프트 PR: https://github.com/you/your-app/pull/42 +``` + +사람이 개입하는 지점은 **"구현할까요?"**와 **"커밋할까요?"** 단 두 번 — 나머지는 전부 자동으로 진행됩니다. + +## 포함된 스킬 + +| 스킬 | 명령어 | 설명 | +|------|--------|------| +| fe-spec | `/fe-rail:fe-spec` | 기능 요구사항 → 구조화된 스펙 문서 생성. Phase 3 에서 다음 단계(풀 자동·구현만·스펙 수정)를 라디오 UI로 선택 — "풀 자동" 선택 시 fe-start 파이프라인으로 자동 연결 | +| fe-build | `/fe-rail:fe-build` | 프론트엔드 코드 구현 (타입→로직 분리→컴포넌트→테스트) | +| fe-review | `/fe-rail:fe-review` | 타입·성능·a11y·품질 4축 리뷰 | +| fe-start | `/fe-rail:fe-start feature.md` | 위 3개를 하나로 — PR까지 자동화. Phase 1·5 가 라디오 UI로 진행 여부·커밋 방식 확인 | +| fe-doc-sync | `/fe-rail:fe-doc-sync` | **설치된 사용자 프로젝트** 스캔 (라우트·의존성·구조·ENV) → 그 프로젝트의 CLAUDE.md·README.md 수정안 제안 | + +## 포함된 Hooks + +정책: **위험은 차단(exit 2), 품질은 경고(stderr)**. + +| Hook | 이벤트 | 역할 | 차단 | +|------|--------|------|------| +| `session-init.sh` | SessionStart | 원격 버전 체크 + 새 버전 알림 (GitHub, 하루 1회) | — | +| `guard.sh` | PreToolUse:Bash | `git add .`, force push, `--no-verify`, `rm -rf /`, `DROP TABLE`, `git reset --hard`, `git checkout/restore .` 등 차단 | ✅ | +| `write-guard.sh` | PreToolUse:Write\|Edit\|MultiEdit | `.env*`·인증서(`*.pem`/`*.key` 등)·시크릿 페이로드 파일(`*.secret`·`*credentials*.json` 등) 생성·수정 차단 (`.env.example`·`CredentialForm.tsx` 같은 소스 파일은 허용) | ✅ | +| `config-protection.sh` | PreToolUse:Write\|Edit\|MultiEdit | 린터/포매터/TS 설정 **약화** 편집만 차단 — `strict:false`·`@ts-nocheck`·린터 `recommended:false`·기존 `strict:true` 제거. 경로 alias·플러그인 추가 등 정상 편집은 통과 | ✅ | +| `read-guard.sh` | PreToolUse:Read | 민감 파일 읽기 시도 경고 출력 (`.env*`·`.envrc`, `*.pem`/`*.key`/`id_rsa` 등 키, `.npmrc`·`*credential*` — write-guard 차단 목록과 대칭) | — | +| `task-guard.sh` | PreToolUse:Task\|Agent | 서브에이전트 프롬프트 내 인젝션 패턴·위험 명령 위임 차단 | ✅ | +| `lint-fix.sh` | PostToolUse:Edit\|Write\|MultiEdit | 소비자 환경 감지 → Biome `check --write` **또는** ESLint `--fix`(+Prettier) 자동 적용 (로컬 바이너리 우선 · npx 폴백은 `FE_RAIL_ALLOW_NPX=1` 옵트인) | — | +| `nextjs-guard.sh` | PostToolUse:Edit\|Write\|MultiEdit | Server Component에서 React 훅/브라우저 API/DOM 이벤트 사용 감지, app router의 `page`/`layout`에 `'use client'` 경고 | — | +| `design-nudge.sh` | PostToolUse:Edit\|Write\|MultiEdit | 프론트 편집에 제네릭/템플릿틱(AI slop) 신호(무거운·임의 그림자, 기본 보라/인디고 그라디언트) 감지 시 경고. **DESIGN.md 있으면 침묵**(fe-reviewer 의 DESIGN Bans 가 정본) | — | +| `quality-gate.sh` | Stop | 변경 파일에 린터(Biome **또는** ESLint) + 타입체크(프로젝트 `typecheck` 스크립트 우선 / 솔루션 tsconfig면 `tsc -b`) 실행 후 경고 출력. 타입체크는 종료코드로 판정(성공 배너 오탐 없음) · 소스 변경이 없어도 `tsconfig*.json`/`package.json` 변경 시 트리거 | — | +| `doc-sync-check.sh` | Stop | 사용자 프로젝트의 코드(src/app/pages/components 등)·package.json·설정 파일 변경 감지 시 `/fe-rail:fe-doc-sync` 실행 안내 (최근 커밋 5개 포함) | — | +| `notify.sh` | (옵션) Notification | macOS terminal-notifier 배너 알림 — `bash hooks/scripts/setup-notifier.sh` 로 활성화 | — | + +### 훅 프로파일 · 토글 (강도 조절) + +훅 강도를 **환경변수로** 조절할 수 있습니다(플러그인 파일 수정 불필요 — 소비자 프로젝트의 셸/`.claude` 환경에서 설정). + +| 환경변수 | 값 | 효과 | +|---|---|---| +| `FE_RAIL_HOOK_PROFILE` | `minimal` | 비가역 위험 **차단기만** (`guard`·`write-guard`·`task-guard`·`config-protection`). 품질 경고·자동정리·문서동기화 안내는 끔 | +| | `standard` (기본) | 위 + 품질 경고·자동정리·문서동기화 전부 | +| | `strict` | `standard` 상위 티어(현재는 상위집합, 향후 더 엄격한 동작 예약) | +| `FE_RAIL_DISABLED_HOOKS` | `"a,b"` | 특정 훅만 콕 집어 비활성 (예: `"doc-sync-check,design-nudge"`) | +| `FE_RAIL_ALLOW_NPX` | `1` | 로컬 린터·`tsc` 바이너리가 없을 때 npx 폴백 허용 (기본은 로컬 전용 — 자동 훅의 네트워크 다운로드·미고정 최신버전 실행 방지). 프로젝트 자체 `typecheck` 스크립트는 패키지 매니저로 실행되므로 이 옵트인과 무관하게 항상 허용 | + +> **프로파일 하향(minimal)으로는 안전 차단기가 꺼지지 않습니다** — 차단기를 끄려면 `FE_RAIL_DISABLED_HOOKS` 에 이름을 명시해야 합니다("타협 없는 차단" + 명시적 탈출구). 세션 시작 시 기본이 아닌 프로파일/비활성 목록이 있으면 안내됩니다. + +### 회귀 eval + +```bash +bash eval/run.sh # 실패 시 exit 1 (CI 용) +``` + +라이브 모델 없이 **결정적으로** 검증합니다: 훅 동작(fixture 주입 → exit code/경고 단언, 차단 사유가 stdout이 아닌 stderr로 전달되는지·비차단 훅 5개의 안내도 동일하게 stderr로 나가는지 포함)·프로파일 토글·플러그인 self-lint(agent `model` 별칭 ∈ {opus,sonnet,haiku}·skill frontmatter·`hooks.json` 무결성·프로파일 배선·위임을 지시하는 스킬의 `allowed-tools`에 Task/Agent 포함 여부·bun `PX` 감지 일관성·`typecheck` 분기의 `references`(tsc -b) 폴백 동반 여부·바이너리+플래그 실행이 `$PM exec` 아닌 `$PX`인지). 별칭 티어가 모델 업데이트로 바뀌거나 훅/설정을 고칠 때 회귀를 잡는 용도입니다. + +## 포함된 Agents + +각 agent는 별도 컨텍스트에서 동작하여 메인 세션을 노이즈로부터 보호합니다. +frontmatter(`tools`/`disallowedTools`/`model`/`maxTurns`) + XML 태그 구조(``/``/``/``/``)로 구성됩니다. + +> **모델 티어는 별칭입니다.** 각 agent의 `model`은 `opus`/`sonnet`/`haiku` **별칭**으로 지정되어, 모델 패밀리 업데이트(예: Opus 4.7 → 4.8) 시 자동으로 최신 티어를 사용합니다. 별도 수정 없이 개선이 반영되는 대신, 플러그인 버전이 동일해도 동작이 변동될 수 있습니다. 재현성이 중요한 경우 릴리스마다 현재 별칭 해상도 기준으로 회귀를 점검하세요. +> 티어 배분: **opus**(고판단 — `fe-analyst`·`fe-architect`·`fe-reviewer`·`fe-refactor-advisor`) / **haiku**(저비용 탐색 — `fe-explorer`) / **sonnet**(나머지 실행·도구 계열). + +### spec 단계 +| Agent | 위임 시점 | 모델 | 격리 | +|-------|----------|------|------| +| `fe-analyst` | 요구사항 갭 분석 (6갭 / 7섹션); CLAUDE.md·DESIGN.md·PRODUCT.md·AGENTS.md 병렬 탐색 | opus | 책임 (read-only) | +| `fe-deck-reader` | PPT/기획서 분해 — 다중 슬라이드를 정책·화면·흐름으로 (PDF/PNG 변환 경유) | sonnet | 책임 (read-only) | +| `fe-vision` | (추출) Figma·UI 스크린샷·PDF·PPT(변환) 개별 화면 분석 (Figma URL → `get_metadata`·`get_design_context`·`get_variable_defs`·`get_screenshot`; DESIGN.md Bans anti-slop 점검) · (대조) 구현 스크린샷 ↔ 레퍼런스 시각 충실도 판정 (visual-verdict — Figma=픽셀/PPT=구조, fe-start Phase 4.5) | sonnet | 책임 (read-only) | +| `fe-researcher` | 외부 문서·라이브러리 조사 (Context7 MCP 우선, WebSearch/WebFetch fallback) | sonnet | 도구 (Context7/WebSearch/WebFetch) | +| `fe-architect` | React/TS 아키텍처 자문 — Next.js(RSC 경계) / Vite SPA(TanStack Router·React Router 7·Zustand) + Tailwind v3/v4·shadcn·openapi-fetch (직교 감지) | opus | 책임 (read-only) | + +### build 단계 +| Agent | 위임 시점 | 모델 | 격리 | +|-------|----------|------|------| +| `fe-explorer` | 코드베이스 탐색 3쿼리 이상 | haiku | 컨텍스트 | +| `fe-test-author` | BDD 시나리오 도출 + TDD Red-Green-Refactor | sonnet | 책임 (구현) | +| `fe-build-fixer` | tsc·린터(ESLint/Biome) 오류 최소 diff 수정 | sonnet | 도구 (Edit+Grep, Write/MultiEdit 금지) | + +### review 단계 +| Agent | 위임 시점 | 모델 | 격리 | +|-------|----------|------|------| +| `fe-reviewer` | 4축 리뷰 (타입·성능·a11y·품질 — 성능 축에 React 훅 런타임 버그(cleanup 누락·async 경쟁조건·무한루프) 포함, Tailwind 안티패턴·openapi-fetch 패턴·DESIGN.md 디자인 계약(존재 시) 포함) | opus | 책임 (read-only) | +| `fe-a11y-auditor` | a11y 8축 감사 (Color Contrast — Tailwind 팔레트 기준 포함). `--live` 시 Chrome DevTools MCP로 실제 Lighthouse a11y 감사·접근성 트리 스냅샷 병행, 미설치면 정적 분석만 | sonnet | 책임 (read-only) | +| `fe-perf-auditor` | 성능 정밀 감사 — Next.js(RSC·next/image·next/font) / Vite SPA(TanStack loader·RR7 TQ prefetch·fetchpriority·번들) / Tailwind v3/v4(purge·@source·@apply). `--live` 시 Chrome DevTools MCP로 dev 서버 실측(LCP 분해·콘솔·네트워크) 병행, 미설치면 정적 분석만 | sonnet | 책임 (read-only) | +| `fe-test-runner` | 테스트 실행 + 실패 분류 | sonnet | 컨텍스트 | +| `fe-refactor-advisor` | 6차원 리팩토링 분석 + Before/After | opus | 책임 (read-only) | + +### PR 단계 +| Agent | 위임 시점 | 모델 | 격리 | +|-------|----------|------|------| +| `fe-git-operator` | 커밋 분리·안전한 스테이징 + 본문 작성 (fix=증상·원인·해결 / feat=추가·핵심·영향) | sonnet | 도구 (Write/Edit 금지) | +| `fe-pr-author` | PR 본문 작성 (성격별 🐛/✨ 블록 + 리뷰 포인트 위험순) + `gh pr create` | sonnet | 컨텍스트 + 도구 | + +## 워크플로우 + +**원스톱 자동화** +``` +feature.md 작성 → /fe-rail:fe-start feature.md → "구현할까요?" 승인 → "커밋할까요?" 승인 → PR 생성 완료 +``` + +> 재위임이 같은 항목을 3회 반복해도 안 풀리면 자동 진행을 멈추고 진단을 보고하는 예외 STOP 이 한 번 더 걸릴 수 있습니다. + +**fe-spec 에서 이어가기 (핸드오프)** +``` +/fe-rail:fe-spec → "다음 단계"에서 "풀 자동" 선택 → fe-start 자동 실행 → "커밋할까요?" 승인 → PR +``` + +> fe-spec 의 "다음 단계" 게이트가 첫 승인("구현할까요?")을 대신하므로 fe-start 는 "커밋할까요?"만 묻습니다 (전체 승인 2회 유지). + +**단계별 수동 제어** +``` +/fe-rail:fe-spec → /fe-rail:fe-build → /fe-rail:fe-review → git commit && gh pr create +``` + +## 전제 조건 + +- Claude Code +- 패키지 매니저 (pnpm / npm / yarn / bun — lock 파일로 자동 감지) +- gh CLI (PR 자동 생성 시) +- TypeScript strict mode (Next.js / Vite SPA) + +## 설치 후 권장 설정 (소비자 프로젝트) + +플러그인의 agent들은 **소비자 프로젝트의 컨텍스트를 읽어** 동작합니다. 설치 직후 아래를 갖추면 품질이 크게 올라갑니다. + +| 항목 | 이유 | 방법 | +|------|------|------| +| **프로젝트 CLAUDE.md** | `fe-analyst`·`fe-architect` 등이 스택·규칙·금지사항을 읽어 추론 — 없으면 빈손으로 분석 (플러그인의 CLAUDE.md는 소비자 세션에 로드되지 않음) | `/init` 또는 `/fe-rail:fe-doc-sync` | +| **Bash 권한** | `fe-git-operator`·`fe-pr-author` 흐름에서 매번 권한 프롬프트 방지 | 자동: 프로젝트 루트에서 `bash <설치경로>/hooks/scripts/setup-permissions.sh`(호스트 감지 → `.claude/settings.local.json` 병합, 확인 1회) · 수동: `.claude/settings.json`의 `permissions.allow`에 `Bash(git *)`·`Bash(gh pr *)` 추가 | +| **MCP (선택)** | `fe-vision`의 Figma 직접 조회, `fe-researcher`의 Context7 문서 조회, `fe-perf-auditor`/`fe-a11y-auditor`의 `--live` 실측 활성화 (미설치 시 각각 로컬 이미지·WebSearch·정적 분석으로 fallback) | Figma: claude.ai 커넥터(`/mcp` → "claude.ai Figma", OAuth) · Context7: 플러그인 설치 · Chrome DevTools: 플러그인 설치. 미설치 시 각 에이전트가 폴백하며 활성화 명령을 그 자리에서 안내(JIT) | +| **검증 스크립트** | Phase 3 자동 검증이 `typecheck`/`lint`/`test` 를, Phase 4.5 완료기준 게이트가 `build`/`e2e`(존재 시)를 사용 | 해당 스크립트 정의 권장 | + +## 라이선스 + +[MIT](LICENSE) © 2026 이승호 + +## 기반 레퍼런스 + +- [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) +- [Chachamaru127/claude-code-harness](https://github.com/Chachamaru127/claude-code-harness) +- [garrytan/gstack](https://github.com/garrytan/gstack) diff --git a/plugins/fe-rail/README.md b/plugins/fe-rail/README.md new file mode 100644 index 0000000..d0adc5c --- /dev/null +++ b/plugins/fe-rail/README.md @@ -0,0 +1,191 @@ +# fe-rail + +
+ 한국어 + English + MIT License +
+ +> Frontend-focused Claude Code plugin +> Automated spec → build → review → PR workflow for Next.js App Router / Vite SPA (TanStack Router · React Router 7) + TypeScript, with full Tailwind v3/v4 / shadcn/ui support. + +## Installation + +```bash +claude + +/plugin marketplace add sh5623/fe-rail +/plugin install fe-rail@fe-rail-market +``` + +![fe-rail workflow: spec, build, review, PR](docs/assets/workflow.svg) + +## Usage + +``` +$ claude +> /fe-rail:fe-spec + +[fe-spec] Analyzing requirements... (fe-analyst, fe-architect) +✔ feature.md generated — 7 sections, 3 open questions resolved + +Next step? + ❯ Full auto (recommended) — hand off to fe-start automatically + Build only — I'll review the spec first + Revise spec + +> Full auto + +[fe-start] Phase 2 — implementing types → hooks → components → tests +✔ 12 files created, tsc clean, lint clean, 8 tests passing + +Commit and open a PR? + ❯ Yes — split by type (feat/fix/test) and open a draft PR + No — leave changes uncommitted + +> Yes + +✔ 2 commits created +✔ Pushed to feat/product-search-autocomplete +✔ Draft PR: https://github.com/you/your-app/pull/42 +``` + +Two human touch-points total — **"Implement?"** and **"Commit?"** — everything else runs unattended. + +## Skills + +| Skill | Command | Description | +|-------|---------|-------------| +| fe-spec | `/fe-rail:fe-spec` | Requirements → structured spec document. Phase 3 presents a radio UI to choose the next step (full auto · build only · revise spec) — selecting "full auto" hands off directly to the fe-start pipeline | +| fe-build | `/fe-rail:fe-build` | Frontend implementation (types → logic → components → tests) | +| fe-review | `/fe-rail:fe-review` | 4-axis code review: types · performance · a11y · quality | +| fe-start | `/fe-rail:fe-start feature.md` | All-in-one — automates through PR creation. Phase 1 · 5 use radio UI to confirm implementation and commit intent | +| fe-doc-sync | `/fe-rail:fe-doc-sync` | Scans the **consumer project** (routes · deps · structure · ENV) → proposes updates to that project's CLAUDE.md · README.md | + +## Hooks + +Policy: **Block dangers (exit 2), warn on quality issues (stderr)**. + +| Hook | Event | Role | Blocks | +|------|-------|------|--------| +| `session-init.sh` | SessionStart | Remote version check + new version notification (GitHub, once/day) | — | +| `guard.sh` | PreToolUse:Bash | Blocks `git add .`, force push, `--no-verify`, `rm -rf /`, `DROP TABLE`, `git reset --hard`, `git checkout/restore .`, etc. | ✅ | +| `write-guard.sh` | PreToolUse:Write\|Edit\|MultiEdit | Blocks creating/editing sensitive files: `.env*`, certificates (`*.pem`/`*.key`, etc.), secret-payload files (`*.secret`, `*credentials*.json`, etc.) — source files like `.env.example`, `CredentialForm.tsx` are allowed | ✅ | +| `config-protection.sh` | PreToolUse:Write\|Edit\|MultiEdit | Blocks only **weakening** edits to linter/formatter/TS config — `strict:false`, `@ts-nocheck`, linter `recommended:false`, removing an existing `strict:true`. Normal edits (path aliases, adding plugins, etc.) pass through | ✅ | +| `read-guard.sh` | PreToolUse:Read | Warns on sensitive file reads (`.env*`·`.envrc`, keys like `*.pem`/`*.key`/`id_rsa`, `.npmrc`·`*credential*` — symmetric with write-guard's block list) | — | +| `task-guard.sh` | PreToolUse:Task\|Agent | Blocks injection patterns and dangerous command delegation in sub-agent prompts | ✅ | +| `lint-fix.sh` | PostToolUse:Edit\|Write\|MultiEdit | Auto-detects consumer env → runs Biome `check --write` **or** ESLint `--fix` (+ Prettier) (local binary first · npx fallback is opt-in via `FE_RAIL_ALLOW_NPX=1`) | — | +| `nextjs-guard.sh` | PostToolUse:Edit\|Write\|MultiEdit | Detects React hooks/browser API/DOM events in Server Components; warns when `page`/`layout` in the app router is missing `'use client'` | — | +| `design-nudge.sh` | PostToolUse:Edit\|Write\|MultiEdit | Warns on generic/templated (AI-slop) signals in frontend edits (heavy/arbitrary shadows, default purple/indigo gradients). **Silent if DESIGN.md exists** (fe-reviewer's DESIGN Bans is the source of truth in that case) | — | +| `quality-gate.sh` | Stop | Runs linter (Biome **or** ESLint) + type check (prefers the project's `typecheck` script, falls back to `tsc -b` for solution-style tsconfig) on changed files, outputs warnings. Type check is judged by exit code (no false positives from success banners) · also triggers on `tsconfig*.json`/`package.json` changes even with no source changes | — | +| `doc-sync-check.sh` | Stop | Detects changes to consumer project code / package.json / config files → suggests `/fe-rail:fe-doc-sync` (includes last 5 commits) | — | +| `notify.sh` | (Optional) Notification | macOS terminal-notifier banner — activate with `bash hooks/scripts/setup-notifier.sh` | — | + +### Hook profiles & toggles (intensity control) + +Hook intensity can be tuned via **environment variables** (no plugin file edits needed — set in the consumer project's shell/`.claude` environment). + +| Env var | Value | Effect | +|---|---|---| +| `FE_RAIL_HOOK_PROFILE` | `minimal` | Only the irreversible-risk **blockers** (`guard`, `write-guard`, `task-guard`, `config-protection`). Quality warnings, auto-cleanup, and doc-sync prompts are turned off | +| | `standard` (default) | The above + all quality warnings/auto-cleanup/doc-sync | +| | `strict` | One tier above `standard` (currently a superset, reserved for stricter behavior in the future) | +| `FE_RAIL_DISABLED_HOOKS` | `"a,b"` | Disable specific hooks by name (e.g. `"doc-sync-check,design-nudge"`) | +| `FE_RAIL_ALLOW_NPX` | `1` | Allow npx fallback when no local linter or `tsc` binary is present (default is local-only — prevents auto-hooks from downloading or running unpinned latest versions). Doesn't affect a project's own `typecheck` script, which always runs via the package manager | + +> **Downgrading the profile to `minimal` does not disable the safety blockers** — to turn them off, name them explicitly in `FE_RAIL_DISABLED_HOOKS` ("no-compromise blocking" + an explicit escape hatch). A non-default profile or a disabled-hooks list is announced at session start. + +### Regression eval + +```bash +bash eval/run.sh # exits 1 on failure (CI-ready) +``` + +Deterministically verifies, with no live model required: hook behavior (fixture injection → exit code/warning assertions, including that block reasons go to stderr rather than stdout, and that the 5 non-blocking hooks' notices also go to stderr), profile toggles, and plugin self-lint (agent `model` alias ∈ {opus, sonnet, haiku}, skill frontmatter, `hooks.json` integrity, profile wiring, delegating skills listing Task/Agent in allowed-tools, bun `PX` detection consistency, typecheck branches always pairing a `references`(tsc -b) fallback, and binary+flag invocations using `$PX` rather than `$PM exec`). Useful for catching regressions when alias tiers shift with model updates, or when hooks/config change. + +## Agents + +Each agent runs in an isolated context, protecting the main session from noise. +Structure: frontmatter (`tools`/`disallowedTools`/`model`/`maxTurns`) + XML tags (``/``/``/``/``). + +> **Model tiers are aliases.** Each agent's `model` is set to `opus`/`sonnet`/`haiku` — automatically using the latest tier on model family updates (e.g. Opus 4.7 → 4.8). Behavior may vary even with the same plugin version; run regression checks on each release if reproducibility matters. +> Tier allocation: **opus** (high-judgment — `fe-analyst` · `fe-architect` · `fe-reviewer` · `fe-refactor-advisor`) / **haiku** (low-cost exploration — `fe-explorer`) / **sonnet** (all other execution/tool agents). + +### Spec stage +| Agent | When to delegate | Model | Isolation | +|-------|-----------------|-------|-----------| +| `fe-analyst` | Requirements gap analysis (6 gaps / 7 sections); parallel scan of CLAUDE.md · DESIGN.md · PRODUCT.md · AGENTS.md | opus | Scoped (read-only) | +| `fe-deck-reader` | PPT/deck decomposition — breaks multi-slide specs into policies · screens · flows (via PDF/PNG conversion) | sonnet | Scoped (read-only) | +| `fe-vision` | (Extract) Figma · UI screenshots · PDF · PPT (via conversion) per-screen analysis (Figma URL → `get_metadata` · `get_design_context` · `get_variable_defs` · `get_screenshot`; DESIGN.md Bans anti-slop check) · (Contrast) implementation screenshot ↔ reference visual fidelity judgment (visual-verdict — Figma=pixel/PPT=layout, fe-start Phase 4.5) | sonnet | Scoped (read-only) | +| `fe-researcher` | External docs · library research (Context7 MCP preferred, WebSearch/WebFetch fallback) | sonnet | Tool (Context7/WebSearch/WebFetch) | +| `fe-architect` | React/TS architecture — Next.js (RSC boundaries) / Vite SPA (TanStack Router · React Router 7 · Zustand) + Tailwind v3/v4 · shadcn · openapi-fetch (orthogonal detection) | opus | Scoped (read-only) | + +### Build stage +| Agent | When to delegate | Model | Isolation | +|-------|-----------------|-------|-----------| +| `fe-explorer` | Codebase exploration (3+ queries) | haiku | Context | +| `fe-test-author` | BDD scenario derivation + TDD Red-Green-Refactor | sonnet | Scoped (implementation) | +| `fe-build-fixer` | tsc · linter (ESLint/Biome) error fixes with minimal diff | sonnet | Tool (Edit+Grep, Write/MultiEdit blocked) | + +### Review stage +| Agent | When to delegate | Model | Isolation | +|-------|-----------------|-------|-----------| +| `fe-reviewer` | 4-axis review (type · performance · a11y · quality — performance axis now covers React hook runtime bugs: missing cleanup · async race · infinite loop; includes Tailwind anti-patterns · openapi-fetch patterns · DESIGN.md design contract, if present) | opus | Scoped (read-only) | +| `fe-a11y-auditor` | 8-axis a11y audit (Color Contrast — Tailwind palette-based included). `--live` runs a real Lighthouse a11y audit + accessibility-tree snapshot via Chrome DevTools MCP when installed; static-only otherwise | sonnet | Scoped (read-only) | +| `fe-perf-auditor` | Performance audit — Next.js (RSC · next/image · next/font) / Vite SPA (TanStack loader · RR7 TQ prefetch · fetchpriority · bundle) / Tailwind v3/v4 (purge · @source · @apply). `--live` runs a real dev-server measurement (LCP breakdown, console, network) via Chrome DevTools MCP when installed; static-only otherwise | sonnet | Scoped (read-only) | +| `fe-test-runner` | Test execution + failure classification | sonnet | Context | +| `fe-refactor-advisor` | 6-dimension refactoring analysis + Before/After | opus | Scoped (read-only) | + +### PR stage +| Agent | When to delegate | Model | Isolation | +|-------|-----------------|-------|-----------| +| `fe-git-operator` | Commit splitting · safe staging + body authoring (fix = symptom·cause·fix / feat = added·core·impact) | sonnet | Tool (Write/Edit blocked) | +| `fe-pr-author` | PR body authoring (🐛/✨ blocks by change type + risk-ordered review points) + `gh pr create` | sonnet | Context + Tool | + +## Workflow + +**All-in-one automation (fe-start)** +``` +Write feature.md → /fe-rail:fe-start feature.md → [radio] "Implement?" → [radio] "Commit?" → PR created +``` + +> If the same item still isn't resolved after 3 re-delegation attempts, an extra STOP can trigger — automation pauses and reports a diagnosis instead of looping indefinitely. + +**fe-spec → full-auto handoff** +``` +/fe-rail:fe-spec → [radio] select "Full auto" → fe-start runs automatically → [radio] "Commit?" → PR created +``` +> Selecting "Full auto" at fe-spec's "next step" gate counts as the first approval ("Implement?"), so fe-start only asks "Commit?" — two human approvals are still preserved overall. + +**Step-by-step manual control** +``` +/fe-rail:fe-spec → /fe-rail:fe-build → /fe-rail:fe-review → git commit && gh pr create +``` + +## Prerequisites + +- Claude Code +- Package manager (pnpm / npm / yarn / bun — auto-detected via lockfile) +- gh CLI (for automated PR creation) +- TypeScript strict mode (Next.js / Vite SPA) + +## Post-install Recommended Setup (Consumer Project) + +Plugin agents read and reason from the **consumer project's context**. Setting these up right after installation significantly improves output quality. + +| Item | Why | How | +|------|-----|-----| +| **Project CLAUDE.md** | `fe-analyst` · `fe-architect`, etc. read the stack · rules · constraints from it — without it, agents analyze blind (this plugin's own CLAUDE.md is not loaded into consumer sessions) | `/init` or `/fe-rail:fe-doc-sync` | +| **Bash permissions** | Prevents a permission prompt on every `fe-git-operator` · `fe-pr-author` action | Auto: run `bash /hooks/scripts/setup-permissions.sh` from the project root (detects host → merges into `.claude/settings.local.json`, confirm once) · Manual: add `Bash(git *)` · `Bash(gh pr *)` to `permissions.allow` in `.claude/settings.json` | +| **MCP (optional)** | Enables `fe-vision`'s direct Figma lookups, `fe-researcher`'s Context7 doc queries, and `fe-perf-auditor`/`fe-a11y-auditor`'s live measurement via `--live` (falls back to local images / WebSearch / static analysis if not installed) | Figma: claude.ai connector (`/mcp` → "claude.ai Figma", OAuth) · Context7: install the plugin · Chrome DevTools: install the plugin. If not installed, each agent falls back and surfaces the enable command just-in-time (JIT) | +| **Validation scripts** | Phase 3 auto-validation uses `typecheck`/`lint`/`test`; the Phase 4.5 done-criteria gate uses `build`/`e2e` if present | Define those scripts | + +## License + +[MIT](LICENSE) © 2026 이승호 + +## References + +- [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) +- [Chachamaru127/claude-code-harness](https://github.com/Chachamaru127/claude-code-harness) +- [garrytan/gstack](https://github.com/garrytan/gstack) diff --git a/plugins/fe-rail/agents/fe-a11y-auditor.md b/plugins/fe-rail/agents/fe-a11y-auditor.md new file mode 100644 index 0000000..7266f42 --- /dev/null +++ b/plugins/fe-rail/agents/fe-a11y-auditor.md @@ -0,0 +1,276 @@ +--- +name: fe-a11y-auditor +description: 접근성(a11y) 전문 감사 — semantic HTML, ARIA, 키보드 탐색, color contrast, focus 관리. fe-reviewer의 4축 a11y보다 정밀. READ-ONLY. `--live` 호출 시 Chrome DevTools MCP 로 실측(Lighthouse a11y 점수·실제 접근성 트리·런타임 콘솔) 병행, 미설치면 정적 분석만. +tools: Read, Grep, Glob, Bash, mcp__plugin_chrome-devtools-mcp_chrome-devtools__lighthouse_audit, mcp__plugin_chrome-devtools-mcp_chrome-devtools__take_snapshot, mcp__plugin_chrome-devtools-mcp_chrome-devtools__navigate_page, mcp__plugin_chrome-devtools-mcp_chrome-devtools__list_console_messages, mcp__chrome-devtools__lighthouse_audit, mcp__chrome-devtools__take_snapshot, mcp__chrome-devtools__navigate_page, mcp__chrome-devtools__list_console_messages +disallowedTools: + - Write + - Edit + - MultiEdit +model: sonnet +maxTurns: 30 +--- + +# fe-a11y-auditor Agent + +WCAG AA 기준 접근성 정밀 감사 전문 에이전트입니다. + +--- + + + +**목표:** +- Semantic HTML·ARIA·키보드 탐색·Form·Image·Focus·Landmark·Color Contrast 8개 카테고리 정밀 감사 +- WCAG AA 기준 위반 사항을 BLOCK/WARN/INFO로 분류 +- 린터 a11y 규칙(Biome a11y 그룹 또는 eslint-plugin-jsx-a11y)·axe-core 기준과 교차 검증 +- Tailwind 사용 시 팔레트 조합 기준 정적 대비 점검 추가 + +**사용 시점:** +- fe-reviewer의 a11y 축에서 BLOCK/WARN이 발견되어 심층 감사가 필요한 경우 +- 접근성이 중요한 기능(폼, 모달, 메뉴, 테이블) 구현 후 정밀 점검 +- fe-start Phase 4 에서 a11y 관련 BLOCK/WARN 이 발생해 정밀 감사가 필요한 경우 +- `--live`(+선택적 route) 플래그가 있고 Chrome DevTools MCP 가 설치돼 있으면 dev 서버 실측(Lighthouse a11y·실제 접근성 트리·콘솔) 병행 — 아래 "실측 감사" 참조 + + + +--- + +## Persona + +- **[Identity]** WCAG 2.2 AA 기준을 체화한 접근성 전문 감사관 +- **[Mindset]** 스크린 리더 사용자, 키보드만 사용하는 사용자 관점으로 본다 +- **[Communication]** WCAG 기준 번호 + Before/After 예시 + +--- + +## 8개 검사 카테고리 + +### Semantic HTML +| 위반 패턴 | 기준 | 심각도 | +|---------|------|-------| +| `
` (버튼 역할) | WCAG 4.1.2 | BLOCK | +| `
` 헤딩 계층 건너뜀 (h1→h3) | WCAG 1.3.1 | WARN | +| `` href 없음 | WCAG 2.4.1 | BLOCK | + +### ARIA +| 위반 패턴 | 기준 | 심각도 | +|---------|------|-------| +| 존재하지 않는 role 사용 | WCAG 4.1.2 | BLOCK | +| 아이콘 전용 버튼에 aria-label 없음 | WCAG 1.1.1 | BLOCK | +| `aria-hidden="true"` 요소에 포커스 가능 | WCAG 4.1.2 | BLOCK | +| aria-describedby 참조 id 없음 | WCAG 1.3.1 | WARN | + +### 키보드 탐색 +| 위반 패턴 | 기준 | 심각도 | +|---------|------|-------| +| onClick만 있고 onKeyDown 없음 (`
`) | WCAG 2.1.1 | BLOCK | +| tabIndex 양수 값 (`tabIndex={1}`) | WCAG 2.4.3 | WARN | +| focus 시 visible 표시 없음 | WCAG 2.4.7 | WARN | + +### Form +| 위반 패턴 | 기준 | 심각도 | +|---------|------|-------| +| input과 label 연결 없음 | WCAG 1.3.1 | BLOCK | +| htmlFor ↔ id 불일치 | WCAG 1.3.1 | BLOCK | +| 오류 메시지 영역 aria 없음 | WCAG 3.3.1 | WARN | + +### Image +| 위반 패턴 | 기준 | 심각도 | +|---------|------|-------| +| `` alt 누락 | WCAG 1.1.1 | BLOCK | +| next/image alt 누락 | WCAG 1.1.1 | BLOCK | +| 장식 이미지 alt="" 없음 | WCAG 1.1.1 | INFO | + +### Focus 관리 +| 위반 패턴 | 기준 | 심각도 | +|---------|------|-------| +| 모달 열릴 때 focus trap 없음 | WCAG 2.1.2 | BLOCK | +| 라우트 변경 후 focus 초기화 없음 | WCAG 2.4.3 | WARN | + +### Landmark +| 위반 패턴 | 기준 | 심각도 | +|---------|------|-------| +| `
` 랜드마크 없음 | WCAG 1.3.6 | WARN | +| `