[DOCS] AI를 이용한 개발을 위한 설정

.agent/workflows/pr-develop.md

@@ -0,0 +1,28 @@
+---
+description: Create a PR from current branch to develop branch with automated title and body based on GitHub issue and branch changes.
+---
+
+1. Parse the current branch name to extract the issue number (e.g., `design/#16` → issue number `16`).
+
+2. Fetch issue information: `gh issue view {issue-number}` to get the issue title.
+
+3. Generate PR title: combine branch name and issue title. Format: `{branch-name} {issue-title-without-prefix}`. Remove category prefix like `[DESIGN]` from the issue title.
+
+4. Analyze branch changes: run `git log develop...HEAD` and `git diff develop...HEAD` to understand the work done.
+
+5. Generate PR body using `.github/PULL_REQUEST_TEMPLATE.md`:
+   - Fill `closed #{issue-number}` in the related issue section
+   - Summarize branch changes in the work description section
+   - Keep review requirements section empty
+
+6. Push current branch to remote if not already pushed.
+
+7. Create PR using heredoc to safely handle special characters in the body:
+   ```
+   gh pr create --base develop --title "{title}" --body "$(cat <<'EOF'
+   {body}
+   EOF
+   )"
+   ```
+
+8. Output the created PR URL to the user.

.agent/workflows/speckits-analyze.md

@@ -0,0 +1,33 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md.
+---
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root. Parse JSON for FEATURE_DIR. Derive paths: SPEC, PLAN, TASKS. Abort if any required file is missing.
+
+2. Load artifacts progressively:
+   - **spec.md**: Overview, Functional/Non-Functional Requirements, User Stories, Edge Cases
+   - **plan.md**: Architecture/stack, Data Model, Phases, Technical constraints
+   - **tasks.md**: Task IDs, Descriptions, Phase grouping, Parallel markers, File paths
+   - **constitution**: `.specify/memory/constitution.md` for principle validation
+
+3. Build semantic models (internal, not output):
+   - Requirements inventory with stable keys
+   - User story/action inventory with acceptance criteria
+   - Task coverage mapping (each task → requirements/stories)
+   - Constitution rule set (MUST/SHOULD normative statements)
+
+4. Run detection passes (limit 50 findings total):
+   - **Duplication**: near-duplicate requirements
+   - **Ambiguity**: vague adjectives lacking measurable criteria, unresolved placeholders
+   - **Underspecification**: requirements missing outcomes, stories missing acceptance criteria
+   - **Constitution Alignment**: conflicts with MUST principles (always CRITICAL)
+   - **Coverage Gaps**: requirements with zero tasks, tasks with no mapped requirement
+   - **Inconsistency**: terminology drift, entity mismatches, task ordering contradictions
+
+5. Assign severity: CRITICAL (constitution violations, missing core artifacts) / HIGH (conflicts, ambiguous security/performance) / MEDIUM (terminology drift, missing coverage) / LOW (style improvements).
+
+6. Produce Markdown analysis report with findings table, coverage summary, constitution alignment issues, unmapped tasks, and metrics (total requirements, total tasks, coverage %, ambiguity count, critical issues count).
+
+7. Provide next actions: if CRITICAL issues exist, recommend resolving before implementation. If only LOW/MEDIUM, user may proceed. Offer to suggest concrete remediation edits (do NOT apply automatically).
+
+**IMPORTANT**: This is STRICTLY READ-ONLY. Do NOT modify any files.

.agent/workflows/speckits-checklist.md

@@ -0,0 +1,36 @@
+---
+description: Generate a custom requirements quality checklist — unit tests for requirements writing, validating completeness, clarity, and consistency.
+---
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root. Parse JSON for FEATURE_DIR and AVAILABLE_DOCS.
+
+2. Ask up to 3 clarifying questions about scope, depth, and audience. Generate questions dynamically from feature domain keywords, risk indicators, and stakeholder hints. Skip if already clear from user input.
+
+3. Load feature context from FEATURE_DIR: spec.md (requirements/scope), plan.md (technical details), tasks.md (implementation tasks). Load only portions relevant to focus areas.
+
+4. Generate checklist — "Unit Tests for Requirements":
+   - Create `FEATURE_DIR/checklists/` directory if needed
+   - Use short descriptive filename based on domain (e.g., `ux.md`, `api.md`, `security.md`)
+   - Sequential IDs: CHK001, CHK002, ...
+   - Each run creates a NEW file (never overwrites existing checklists)
+
+5. Checklist items must test REQUIREMENT QUALITY, not implementation:
+   - **Completeness**: "Are all necessary requirements documented?"
+   - **Clarity**: "Are requirements specific and unambiguous?"
+   - **Consistency**: "Do requirements align without conflicts?"
+   - **Measurability**: "Can requirements be objectively verified?"
+   - **Coverage**: "Are all scenarios/edge cases addressed?"
+   - Include traceability: `[Spec §X.Y]`, `[Gap]`, `[Ambiguity]`, `[Conflict]`
+   - Minimum 80% of items must include traceability references
+
+6. PROHIBITED patterns (these test implementation, not requirements):
+   - "Verify the button clicks correctly"
+   - "Test error handling works"
+   - Any item starting with "Verify", "Test", "Confirm" + implementation behavior
+
+7. REQUIRED patterns (these test requirements quality):
+   - "Are [requirement type] defined/specified for [scenario]?"
+   - "Is [vague term] quantified with specific criteria?"
+   - "Are requirements consistent between [section A] and [section B]?"
+
+8. Follow template structure from `.specify/templates/checklist-template.md` if available. Report: output path, item count, focus areas, depth level.

.agent/workflows/speckits-clarify.md

@@ -0,0 +1,30 @@
+---
+description: Identify underspecified areas in the current feature spec by asking up to 5 targeted clarification questions and encoding answers back into the spec.
+---
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root. Parse JSON for FEATURE_DIR and FEATURE_SPEC. If parsing fails, instruct user to run `/speckits-specify` first.
+
+2. Load the current spec file. Perform a structured ambiguity and coverage scan using this taxonomy — mark each category as Clear / Partial / Missing:
+   - Functional Scope & Behavior (goals, out-of-scope, user roles)
+   - Domain & Data Model (entities, attributes, relationships, lifecycle)
+   - Interaction & UX Flow (user journeys, error/empty/loading states)
+   - Non-Functional Quality Attributes (performance, scalability, security)
+   - Integration & External Dependencies (APIs, data formats)
+   - Edge Cases & Failure Handling (negative scenarios, rate limiting)
+   - Constraints & Tradeoffs
+   - Terminology & Consistency
+   - Completion Signals (acceptance criteria testability)
+
+3. Generate a prioritized queue of max 5 clarification questions. Each must be answerable with multiple-choice (2-5 options) or short phrase (<=5 words). Only include questions whose answers materially impact architecture, data modeling, task decomposition, or test design. For multiple-choice, provide a recommended option with reasoning.
+
+4. Present exactly ONE question at a time. After user answers, validate and record. Stop when: all critical ambiguities resolved, user signals completion, or 5 questions asked.
+
+5. After each accepted answer, update the spec file immediately:
+   - Ensure `## Clarifications` section exists with `### Session YYYY-MM-DD` subheading
+   - Append `- Q: {question} → A: {answer}`
+   - Apply clarification to the most appropriate spec section
+   - If the clarification invalidates earlier text, replace it (no contradictions)
+
+6. Validate after each write: no duplicate bullets, no lingering vague placeholders, markdown structure valid, terminology consistent.
+
+7. Report completion: number of questions asked, path to updated spec, sections touched, coverage summary table, and suggested next command.

.agent/workflows/speckits-constitution.md

@@ -0,0 +1,35 @@
+---
+description: Create or update the project constitution at .specify/memory/constitution.md from interactive or provided principle inputs, keeping dependent templates in sync.
+---
+
+1. Load the existing constitution at `.specify/memory/constitution.md`. Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
+
+2. Collect/derive values for placeholders:
+   - Use values from user input if supplied
+   - Otherwise infer from repo context (README, docs, prior constitution)
+   - `RATIFICATION_DATE`: original adoption date
+   - `LAST_AMENDED_DATE`: today if changes are made
+   - `CONSTITUTION_VERSION`: increment with semver (MAJOR: principle removals/redefinitions, MINOR: new principles added, PATCH: clarifications/typos)
+
+3. Draft the updated constitution:
+   - Replace every placeholder with concrete text (no bracketed tokens left)
+   - Preserve heading hierarchy
+   - Each Principle section: succinct name, non-negotiable rules, explicit rationale
+
+4. Consistency propagation: read and verify alignment with:
+   - `.specify/templates/plan-template.md` (Constitution Check section)
+   - `.specify/templates/spec-template.md` (scope/requirements alignment)
+   - `.specify/templates/tasks-template.md` (task categorization)
+   - Command files in `.specify/templates/commands/*.md`
+   - Runtime docs (README.md, quickstart.md)
+
+5. Produce a Sync Impact Report (prepend as HTML comment in constitution file):
+   - Version change: old → new
+   - Modified/added/removed principles
+   - Templates requiring updates (with file paths)
+
+6. Validate: no unexplained bracket tokens, version matches report, dates in ISO format, principles are declarative and testable.
+
+7. Write completed constitution to `.specify/memory/constitution.md`.
+
+8. Output summary: new version, bump rationale, files flagged for follow-up, suggested commit message.

.agent/workflows/speckits-implement.md

@@ -0,0 +1,31 @@
+---
+description: Execute the implementation plan by processing all tasks defined in tasks.md for this Vite + React SPA project.
+---
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root. Parse FEATURE_DIR and AVAILABLE_DOCS. All paths must be absolute.
+
+2. Check checklists status (if FEATURE_DIR/checklists/ exists). For each checklist, count total/completed/incomplete items. If any incomplete: STOP and ask user for confirmation. If all complete: proceed.
+
+3. Load implementation context:
+   - **Required**: tasks.md (task list), plan.md (tech stack, architecture)
+   - **Optional**: data-model.md, contracts/, research.md
+
+4. Verify project conventions before each task (Vite + React SPA):
+   - Pages: `src/page/{PageName}/` with local `components/` and `hooks/`
+   - API: Axios via `src/apis/primitives.ts`, functions in `src/apis/apis/`, types in `requests/` + `responses/`
+   - Hooks: `src/hooks/query/` for TanStack Query, `src/hooks/mutations/` for mutations
+   - Components: function declaration style (`export default function Component() {}`)
+   - i18n: `useTranslation()` for all user-facing text
+   - Variables: `const` by default, `let` only for reassignment, NEVER `var`
+   - Naming: Components PascalCase, hooks `use` prefix camelCase, utils camelCase
+
+5. Parse tasks.md structure: extract phases, dependencies, parallel markers [P].
+
+6. Execute phase-by-phase:
+   - Complete each phase before moving to the next
+   - Respect dependencies: sequential tasks in order, parallel [P] tasks can run together
+   - File-based coordination: tasks affecting same files run sequentially
+
+7. Track progress: report after each completed task, mark as `- [x]` in tasks.md. Halt on non-parallel task failure.
+
+8. Validate completion: verify all tasks completed, features match spec, tests pass, project conventions followed. Report final status.

.agent/workflows/speckits-plan.md

@@ -0,0 +1,43 @@
+---
+description: Execute the TDD-driven implementation planning workflow to generate design artifacts including test contracts for a Vite + React SPA project.
+---
+
+1. Run `.specify/scripts/bash/setup-plan.sh --json` from repo root. Parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH.
+
+2. Load context: read FEATURE_SPEC (spec.md), `.specify/memory/constitution.md`, `CLAUDE.md` or project rules if they exist, IMPL_PLAN template, and `package.json`.
+
+3. Explore the existing codebase before planning:
+   - Scan `src/page/` for page structure patterns
+   - Check `src/components/`, `src/hooks/` (query/, mutations/), `src/apis/`
+   - Check `src/util/`, `src/constants/`, `src/repositories/`
+   - Review 1-2 existing pages for patterns (TanStack Query hooks, Axios API functions, compound components)
+   - Scan existing `*.test.ts(x)` files for test patterns (Vitest, @testing-library/react, MSW, Korean descriptions)
+
+4. Fill Technical Context in the plan:
+   - TypeScript (strict), React 18 + Vite, React Router v7, TanStack React Query 5
+   - Axios (custom `request<T>` primitive), Tailwind CSS 3, i18next, Framer Motion
+   - Testing: Vitest + @testing-library/react + userEvent + MSW
+   - Test approach: **TDD (Red-Green-Refactor)**
+
+5. Run Constitution & Consistency Check from `.specify/memory/constitution.md`: verify folder structure, API layer patterns, hooks separation, page structure, no circular dependencies.
+
+6. Phase 0 — Research: extract unknowns, research each, write findings to `research.md`.
+
+7. Phase 1 — Design & Contracts (TDD-First):
+   - Extract entities → `data-model.md`
+   - Generate API contracts → `contracts/`
+   - Define project structure with test files (co-located `{module}.test.ts(x)`)
+   - Write test contracts to `test-contracts/`: behavior list per module, expected I/O, boundary conditions
+   - Test priority: `util/` → `apis/` (MSW) → `hooks/` → `components/` → `page/`
+
+8. Define TDD Implementation Order (Red-Green-Refactor cycle):
+   - Types (`type/`, `apis/requests/`, `apis/responses/`)
+   - Pure utilities (`util/`)
+   - MSW handlers (`mocks/handlers/`)
+   - API functions (`apis/apis/`)
+   - Query/Mutation hooks (`hooks/query/`, `hooks/mutations/`)
+   - Page/component hooks → UI components → Page components
+
+9. Create Architecture Decision Table: decision name, options, chosen option with rationale, impact, testability impact.
+
+10. Report: branch, spec path, IMPL_PLAN path, generated artifacts, TDD order summary, constitution check status. Suggest next: `/speckits-tasks`.

.agent/workflows/speckits-specify.md

@@ -0,0 +1,23 @@
+---
+description: Create or update a feature specification with GitHub issue tracking, branch setup, and auto-clarification loop.
+---
+
+1. Read `README.md` for project overview and domain context (debate timer service).
+
+2. Generate a concise slug (2-4 words, kebab-case) from the feature description. Use action-noun format (e.g., "social-login", "vote-results-calendar").
+
+3. Ask user which TYPE of work this is: feat / fix / design / docs / refactor / chore / config / test / style / hotfix. Use the selection as `{TYPE}` (lowercase) and `{TYPE_UPPER}` (uppercase) throughout.
+
+4. Verify `gh` CLI is authenticated (`gh auth status`). Ask user whether to create a new GitHub issue or use an existing one. If new, run `gh issue create --title "[{TYPE_UPPER}] {SLUG}" --body "..." --label "{TYPE}"`. If existing, verify with `gh issue view`.
+
+5. Ask user which base branch to use: current branch or `develop` (recommended). Create feature branch: `git checkout -b "{TYPE}/#{ISSUE_NUMBER}-{SLUG}"`.
+
+6. Run `.specify/scripts/bash/create-new-feature.sh --json --no-branch --type-prefix {TYPE} --number {ISSUE_NUMBER} --short-name "{SLUG}" --issue-number {ISSUE_NUMBER} "{FEATURE_DESCRIPTION}"` to create spec directory structure. Parse JSON output for SPEC_FILE, FEATURE_DIR, FEATURE_NUM.
+
+7. Load `.specify/templates/spec-template.md`. Write the specification to SPEC_FILE following the template structure. Focus on WHAT users need and WHY — avoid implementation details. Make informed guesses for unclear aspects, document assumptions, limit to max 3 `[NEEDS CLARIFICATION]` markers.
+
+8. Run auto-clarification loop: scan spec across 6 categories (Functional Scope, Data Model, UX Flow, Edge Cases, Non-Functional, External Integration). Generate max 5 questions for Partial/Missing categories. Present one question at a time, update spec inline after each answer.
+
+9. Generate quality validation checklist at `FEATURE_DIR/checklists/requirements.md`.
+
+10. Report completion with spec path, GitHub issue link, branch name, clarification summary, and suggest next step: run `/speckits-plan`.

.agent/workflows/speckits-tasks.md

@@ -0,0 +1,35 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on spec, plan, and design artifacts.
+---
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root. Parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
+
+2. Load design documents from FEATURE_DIR:
+   - **Required**: plan.md (tech stack, structure), spec.md (user stories with priorities)
+   - **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions)
+
+3. Execute task generation:
+   - Extract tech stack and libraries from plan.md
+   - Extract user stories with priorities (P1, P2, P3) from spec.md
+   - If data-model.md exists: map entities to user stories
+   - If contracts/ exists: map endpoints to user stories
+   - Generate tasks organized by user story
+   - Validate task completeness (each user story independently testable)
+
+4. Generate tasks.md using `.specify/templates/tasks-template.md` structure. Every task MUST follow the format: `- [ ] T001 [P] [US1] Description with file path`.
+
+5. Organize by phases:
+   - **Phase 1**: Setup (project initialization)
+   - **Phase 2**: Foundational (blocking prerequisites)
+   - **Phase 3+**: One phase per user story in priority order. Within each: Types → Utils → API → Hooks → Components → Page
+   - **Final Phase**: Polish & cross-cutting concerns
+
+6. Project path conventions for this Vite + React SPA:
+   - `src/page/{PageName}/` — Pages with local components/ and hooks/
+   - `src/components/{Component}/` — Reusable UI components
+   - `src/hooks/query/` — TanStack Query hooks, `src/hooks/mutations/` — Mutation hooks
+   - `src/apis/apis/` — API functions, `src/apis/requests/` + `responses/` — Types
+   - `src/util/`, `src/constants/`, `src/type/`, `src/repositories/`
+   - `src/mocks/handlers/` — MSW handlers
+
+7. Report: output path to tasks.md, total task count, count per user story, parallel opportunities, suggested MVP scope. Suggest next: `/speckits-analyze` or `/speckits-implement`.

.agent/workflows/speckits-taskstoissues.md

@@ -0,0 +1,13 @@
+---
+description: Convert existing tasks from tasks.md into actionable, dependency-ordered GitHub issues for the feature.
+---
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root. Parse FEATURE_DIR and AVAILABLE_DOCS. All paths must be absolute.
+
+2. Extract the path to tasks.md from the script output. Load and parse all tasks.
+
+3. Get the Git remote: `git config --get remote.origin.url`. **ONLY proceed if the remote is a GitHub URL.**
+
+4. For each task in the list, create a GitHub issue in the repository matching the Git remote. Include task ID, description, dependencies, and phase information.
+
+**CAUTION**: Under no circumstances create issues in repositories that do not match the remote URL.