create-claude-webapp 1.0.0 → 1.0.1

package/.claude/commands/task.md

@@ -0,0 +1,13 @@
+---
+description: Execute tasks following appropriate rules
+---
+
+Task: $ARGUMENTS
+
+**Pre-execution Checklist** (MUST clarify BEFORE starting):
+
+1. **Applicable Rules**: Which development rules apply to this task?
+2. **Initial Action**: Based on the rules, what is the FIRST step?
+3. **Scope Boundary**: What are the completion criteria and scope of responsibility?
+
+Proceed with the task ONLY AFTER making the above explicit.

package/.claude/skills/coding-standards/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: coding-standards
+description: Detects code smells, anti-patterns, and readability issues. Use when implementing features, reviewing code, or refactoring.
+---
+
+# Universal Coding Standards
+
+## Technical Anti-patterns (Red Flag Patterns)
+
+Immediately stop and reconsider design when detecting the following patterns:
+
+### Code Quality Anti-patterns
+1. **Writing similar code 3 or more times** - Violates Rule of Three
+2. **Multiple responsibilities mixed in a single file** - Violates Single Responsibility Principle (SRP)
+3. **Defining same content in multiple files** - Violates DRY principle
+4. **Making changes without checking dependencies** - Potential for unexpected impacts
+5. **Disabling code with comments** - Should use version control
+6. **Error suppression** - Hiding problems creates technical debt
+7. **Excessive use of type assertions (as)** - Abandoning type safety
+
+### Design Anti-patterns
+- **"Make it work for now" thinking** - Accumulation of technical debt
+- **Patchwork implementation** - Unplanned additions to existing code
+- **Optimistic implementation of uncertain technology** - Designing unknown elements assuming "it'll probably work"
+- **Symptomatic fixes** - Surface-level fixes that don't solve root causes
+- **Unplanned large-scale changes** - Lack of incremental approach
+
+## Basic Principles
+
+- **Aggressive Refactoring** - Prevent technical debt and maintain health
+- **No Unused "Just in Case" Code** - Violates YAGNI principle (Kent Beck)
+
+## Comment Writing Rules
+
+- **Function Description Focus**: Describe what the code "does"
+- **No Historical Information**: Do not record development history
+- **Timeless**: Write only content that remains valid whenever read
+- **Conciseness**: Keep explanations to necessary minimum
+
+## Error Handling Fundamentals
+
+### Fail-Fast Principle
+Fail quickly on errors to prevent processing continuation in invalid states. Error suppression is prohibited.
+
+For detailed implementation methods (Result type, custom error classes, layered error handling, etc.), refer to language and framework-specific rules.
+
+## Rule of Three - Criteria for Code Duplication
+
+How to handle duplicate code based on Martin Fowler's "Refactoring":
+
+| Duplication Count | Action | Reason |
+|-------------------|--------|--------|
+| 1st time | Inline implementation | Cannot predict future changes |
+| 2nd time | Consider future consolidation | Pattern beginning to emerge |
+| 3rd time | Implement commonalization | Pattern established |
+
+### Criteria for Commonalization
+
+**Cases for Commonalization**
+- Business logic duplication
+- Complex processing algorithms
+- Areas likely requiring bulk changes
+- Validation rules
+
+**Cases to Avoid Commonalization**
+- Accidental matches (coincidentally same code)
+- Possibility of evolving in different directions
+- Significant readability decrease from commonalization
+- Simple helpers in test code
+
+## Common Failure Patterns and Avoidance Methods
+
+### Pattern 1: Error Fix Chain
+**Symptom**: Fixing one error causes new errors
+**Cause**: Surface-level fixes without understanding root cause
+**Avoidance**: Identify root cause with 5 Whys before fixing
+
+### Pattern 2: Abandoning Type Safety
+**Symptom**: Excessive use of any type or as
+**Cause**: Impulse to avoid type errors
+**Avoidance**: Handle safely with unknown type and type guards
+
+### Pattern 3: Implementation Without Sufficient Testing
+**Symptom**: Many bugs after implementation
+**Cause**: Ignoring Red-Green-Refactor process
+**Avoidance**: Always start with failing tests
+
+### Pattern 4: Ignoring Technical Uncertainty
+**Symptom**: Frequent unexpected errors when introducing new technology
+**Cause**: Assuming "it should work according to official documentation" without prior investigation
+**Avoidance**:
+- Record certainty evaluation at the beginning of task files
+- For low certainty cases, create minimal verification code first
+
+### Pattern 5: Insufficient Existing Code Investigation
+**Symptom**: Duplicate implementations, architecture inconsistency, integration failures
+**Cause**: Insufficient understanding of existing code before implementation
+**Avoidance Methods**:
+- Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords)
+- Similar functionality found -> Use that implementation (do not create new implementation)
+- Similar functionality is technical debt -> Create ADR improvement proposal before implementation
+- No similar functionality exists -> Implement new functionality following existing design philosophy
+- Record all decisions and rationale in "Existing Codebase Analysis" section of Design Doc
+
+## Debugging Techniques
+
+### 1. Error Analysis Procedure
+1. Read error message (first line) accurately
+2. Focus on first and last of stack trace
+3. Identify first line where your code appears
+
+### 2. 5 Whys - Root Cause Analysis
+```
+Symptom: Build error
+Why1: Type definitions don't match -> Why2: Interface was updated
+Why3: Dependency change -> Why4: Package update impact
+Why5: Major version upgrade with breaking changes
+Root cause: Inappropriate version specification
+```
+
+### 3. Minimal Reproduction Code
+To isolate problems, attempt reproduction with minimal code:
+- Remove unrelated parts
+- Replace external dependencies with mocks
+- Create minimal configuration that reproduces problem
+
+## Type Safety Fundamentals
+
+**Type Safety Principle**: Use `unknown` type with type guards. `any` type disables type checking and causes runtime errors.
+
+**any Type Alternatives (Priority Order)**
+1. **unknown Type + Type Guards**: Use for validating external input
+2. **Generics**: When type flexibility is needed
+3. **Union Types/Intersection Types**: Combinations of multiple types
+4. **Type Assertions (Last Resort)**: Only when type is certain
+
+**Type Guard Implementation Pattern**
+```typescript
+function isUser(value: unknown): value is User {
+  return typeof value === 'object' && value !== null && 'id' in value && 'name' in value
+}
+```
+
+**Type Complexity Management**
+- Field Count: Up to 20 (split by responsibility if exceeded, external API types are exceptions)
+- Optional Ratio: Up to 30% (separate required/optional if exceeded)
+- Nesting Depth: Up to 3 levels (flatten if exceeded)
+- Type Assertions: Review design if used 3+ times
+- **External API Types**: Relax constraints and define according to reality (convert appropriately internally)
+
+## Refactoring Techniques
+
+**Basic Policy**
+- Small Steps: Maintain always-working state through gradual improvements
+- Safe Changes: Minimize the scope of changes at once
+- Behavior Guarantee: Ensure existing behavior remains unchanged while proceeding
+
+**Implementation Procedure**: Understand Current State -> Gradual Changes -> Behavior Verification -> Final Validation
+
+**Priority**: Duplicate Code Removal > Large Function Division > Complex Conditional Branch Simplification > Type Safety Improvement
+
+## Implementation Completeness Assurance
+
+### Required Procedure for Impact Analysis
+
+**Completion Criteria**: Complete all 3 stages
+
+#### 1. Discovery
+```bash
+Grep -n "TargetClass\|TargetMethod" -o content
+Grep -n "DependencyClass" -o content
+Grep -n "targetData\|SetData\|UpdateData" -o content
+```
+
+#### 2. Understanding
+**Mandatory**: Read all discovered files and include necessary parts in context:
+- Caller's purpose and context
+- Dependency direction
+- Data flow: generation -> modification -> reference
+
+#### 3. Identification
+Structured impact report (mandatory):
+```
+## Impact Analysis
+### Direct Impact: ClassA, ClassB (with reasons)
+### Indirect Impact: SystemX, ComponentY (with integration paths)
+### Processing Flow: Input -> Process1 -> Process2 -> Output
+```
+
+**Important**: Do not stop at search; execute all 3 stages
+
+### Unused Code Deletion Rule
+
+When unused code is detected -> Will it be used?
+- Yes -> Implement immediately (no deferral allowed)
+- No -> Delete immediately (remains in Git history)
+
+Target: Code, documentation, configuration files
+
+## Red-Green-Refactor Process (Test-First Development)
+
+**Recommended Principle**: Always start code changes with tests
+
+**Development Steps**:
+1. **Red**: Write test for expected behavior (it fails)
+2. **Green**: Pass test with minimal implementation
+3. **Refactor**: Improve code while maintaining passing tests
+
+**NG Cases (Test-first not required)**:
+- Pure configuration file changes (.env, config, etc.)
+- Documentation-only updates (README, comments, etc.)
+- Emergency production incident response (post-incident tests mandatory)
+
+## Test Design Principles
+
+### Test Case Structure
+- Tests consist of three stages: "Arrange," "Act," "Assert"
+- Clear naming that shows purpose of each test
+- One test case verifies only one behavior
+
+### Test Data Management
+- Manage test data in dedicated directories
+- Define test-specific environment variable values
+- Always mock sensitive information
+- Keep test data minimal, using only data directly related to test case verification purposes
+
+### Mock and Stub Usage Policy
+
+**Recommended: Mock external dependencies in unit tests**
+- Merit: Ensures test independence and reproducibility
+- Practice: Mock DB, API, file system, and other external dependencies
+
+**Avoid: Actual external connections in unit tests**
+- Reason: Slows test speed and causes environment-dependent problems
+
+### Test Failure Response Decision Criteria
+
+**Fix tests**: Wrong expected values, references to non-existent features, dependence on implementation details, implementation only for tests
+**Fix implementation**: Valid specifications, business logic, important edge cases
+**When in doubt**: Confirm with user
+
+## Test Granularity Principles
+
+### Core Principle: Observable Behavior Only
+**MUST Test**: Public APIs, return values, exceptions, external calls, persisted state
+**MUST NOT Test**: Private methods, internal state, algorithm implementation details

package/.claude/skills/documentation-criteria/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: documentation-criteria
+description: Guides PRD, ADR, Design Doc, and Work Plan creation with templates and decision matrix.
+---
+
+# Documentation Creation Criteria
+
+## Creation Decision Matrix
+
+| Condition | Required Documents | Creation Order |
+|-----------|-------------------|----------------|
+| New Feature Addition | PRD -> [ADR] -> Design Doc -> Work Plan | After PRD approval |
+| ADR Conditions Met (see below) | ADR -> Design Doc -> Work Plan | Start immediately |
+| 6+ Files | ADR -> Design Doc -> Work Plan (Required) | Start immediately |
+| 3-5 Files | Design Doc -> Work Plan (Recommended) | Start immediately |
+| 1-2 Files | None | Direct implementation |
+
+## ADR Creation Conditions (Required if Any Apply)
+
+### 1. Type System Changes
+- **Adding nested types with 3+ levels**: `type A = { b: { c: { d: T } } }`
+  - Rationale: Deep nesting has high complexity and wide impact scope
+- **Changing/deleting types used in 3+ locations**
+  - Rationale: Multiple location impacts require careful consideration
+- **Type responsibility changes** (e.g., DTO->Entity)
+  - Rationale: Conceptual model changes affect design philosophy
+
+### 2. Data Flow Changes
+- **Storage location changes** (DB->File, Memory->Cache)
+- **Processing order changes with 3+ steps**
+  - Example: "Input->Validation->Save" to "Input->Save->Async Validation"
+- **Data passing method changes** (props->Context, direct reference->events)
+
+### 3. Architecture Changes
+- Layer addition, responsibility changes, component relocation
+
+### 4. External Dependency Changes
+- Library/framework/external API introduction or replacement
+
+### 5. Complex Implementation Logic (Regardless of Scale)
+- Managing 3+ states
+- Coordinating 5+ asynchronous processes
+
+## Detailed Document Definitions
+
+### PRD (Product Requirements Document)
+
+**Purpose**: Define business requirements and user value
+
+**Includes**:
+- Business requirements and user value
+- Success metrics and KPIs (measurable format)
+- User stories and use cases
+- MoSCoW prioritization (Must/Should/Could/Won't)
+- MVP and Future phase separation
+- User journey diagram (required)
+- Scope boundary diagram (required)
+
+**Excludes**:
+- Technical implementation details (->Design Doc)
+- Technical selection rationale (->ADR)
+- **Implementation phases** (->Work Plan)
+- **Task breakdown** (->Work Plan)
+
+### ADR (Architecture Decision Record)
+
+**Purpose**: Record technical decision rationale and background
+
+**Includes**:
+- Decision (what was selected)
+- Rationale (why that selection was made)
+- Option comparison (minimum 3 options) and trade-offs
+- Architecture impact
+- Principled implementation guidelines (e.g., "Use dependency injection")
+
+**Excludes**:
+- Implementation schedule, duration (->Work Plan)
+- Detailed implementation procedures (->Design Doc)
+- Specific code examples (->Design Doc)
+- Resource assignments (->Work Plan)
+
+### Design Document
+
+**Purpose**: Define technical implementation methods in detail
+
+**Includes**:
+- **Existing codebase analysis** (required)
+  - Implementation path mapping (both existing and new)
+  - Integration point clarification (connection points with existing code even for new implementations)
+- Technical implementation approach (vertical/horizontal/hybrid)
+- **Technical dependencies and implementation constraints** (required implementation order)
+- Interface and type definitions
+- Data flow and component design
+- **E2E verification procedures at integration points**
+- **Acceptance criteria (EARS format: When/While/If-then/none)**
+- Change impact map (clearly specify direct impact/indirect impact/no ripple effect)
+- Complete enumeration of integration points
+- Data contract clarification
+- **Agreement checklist** (agreements with stakeholders)
+- **Prerequisite ADRs** (including common ADRs)
+
+**Excludes**:
+- Why that technology was chosen (->Reference ADR)
+- When to implement, duration (->Work Plan)
+- Who will implement (->Work Plan)
+
+### Work Plan
+
+**Purpose**: Implementation task management and progress tracking
+
+**Includes**:
+- Task breakdown and dependencies (maximum 2 levels)
+- Schedule and duration estimates
+- **Copy E2E verification procedures from Design Doc** (cannot delete, can add)
+- **Phase 4 Quality Assurance Phase (required)**
+- Progress records (checkbox format)
+
+**Excludes**:
+- Technical rationale (->ADR)
+- Design details (->Design Doc)
+
+**Phase Division Criteria**:
+1. **Phase 1: Foundation Implementation** - Type definitions, interfaces, test preparation
+2. **Phase 2: Core Feature Implementation** - Business logic, unit tests
+3. **Phase 3: Integration Implementation** - External connections, presentation layer
+4. **Phase 4: Quality Assurance (Required)** - Acceptance criteria achievement, all tests passing, quality checks
+
+**Three Elements of Task Completion Definition**:
+1. **Implementation Complete**: Code is functional
+2. **Quality Complete**: Tests, type checks, linting pass
+3. **Integration Complete**: Verified connection with other components
+
+## Creation Process
+
+1. **Problem Analysis**: Change scale assessment, ADR condition check
+2. **ADR Option Consideration** (ADR only): Compare 3+ options, specify trade-offs
+3. **Creation**: Use templates, include measurable conditions
+4. **Approval**: "Accepted" after review enables implementation
+
+## Storage Locations
+
+| Document | Path | Naming Convention | Template |
+|----------|------|------------------|----------|
+| PRD | `docs/prd/` | `[feature-name]-prd.md` | See prd-template.md |
+| ADR | `docs/adr/` | `ADR-[4-digits]-[title].md` | See adr-template.md |
+| Design Doc | `docs/design/` | `[feature-name]-design.md` | See design-template.md |
+| Work Plan | `docs/plans/` | `YYYYMMDD-{type}-{description}.md` | See plan-template.md |
+| Task File | `docs/plans/tasks/` | `{plan-name}-task-{number}.md` | See task-template.md |
+
+*Note: Work plans are excluded by `.gitignore`
+
+## ADR Status
+`Proposed` -> `Accepted` -> `Deprecated`/`Superseded`/`Rejected`
+
+## AI Automation Rules
+- 5+ files: Suggest ADR creation
+- Type/data flow change detected: ADR mandatory
+- Check existing ADRs before implementation
+
+## Diagram Requirements
+
+Required diagrams for each document (using mermaid notation):
+
+| Document | Required Diagrams | Purpose |
+|----------|------------------|---------|
+| PRD | User journey diagram, Scope boundary diagram | Clarify user experience and scope |
+| ADR | Option comparison diagram (when needed) | Visualize trade-offs |
+| Design Doc | Architecture diagram, Data flow diagram | Understand technical structure |
+| Work Plan | Phase structure diagram, Task dependency diagram | Clarify implementation order |
+
+## Common ADR Relationships
+1. **At creation**: Identify common technical areas (logging, error handling, async processing, etc.), reference existing common ADRs
+2. **When missing**: Consider creating necessary common ADRs
+3. **Design Doc**: Specify common ADRs in "Prerequisite ADRs" section
+4. **Compliance check**: Verify design aligns with common ADR decisions
+
+## Templates
+
+Templates are available in the `references/` directory:
+- [Design Document template](references/design-template.md)
+- [Product Requirements Document template](references/prd-template.md)
+- [Work Plan template](references/plan-template.md)
+- [Architecture Decision Record template](references/adr-template.md)
+- [Task File template](references/task-template.md)

package/.claude/skills/documentation-criteria/references/adr-template.md

@@ -0,0 +1,64 @@
+# [ADR Number] [Title]
+
+## Status
+
+[Proposed | Accepted | Deprecated | Superseded]
+
+## Context
+
+[Describe the background and reasons why this decision is needed. Include the essence of the problem, current challenges, and constraints]
+
+## Decision
+
+[Describe the actual decision made. Aim for specific and clear descriptions]
+
+### Decision Details
+
+| Item | Content |
+|------|---------|
+| **Decision** | [The decision in one sentence] |
+| **Why now** | [Why this needs to happen now (timing rationale)] |
+| **Why this** | [Why this option over alternatives (1-3 lines)] |
+| **Known unknowns** | [At least one uncertainty at this point] |
+| **Kill criteria** | [One signal that should trigger reversal of this decision] |
+
+## Rationale
+
+[Explain why this decision was made and why it is the best option compared to alternatives]
+
+### Options Considered
+
+1. **Option 1**: [Description]
+   - Pros: [List advantages]
+   - Cons: [List disadvantages]
+
+2. **Option 2**: [Description]
+   - Pros: [List advantages]
+   - Cons: [List disadvantages]
+
+3. **Option 3 (Selected)**: [Description]
+   - Pros: [List advantages]
+   - Cons: [List disadvantages]
+
+## Consequences
+
+### Positive Consequences
+
+- [List positive impacts on the project or system]
+
+### Negative Consequences
+
+- [List negative impacts or trade-offs that need to be accepted]
+
+### Neutral Consequences
+
+- [List changes that are neither good nor bad]
+
+## Implementation Guidance
+
+[Principled direction only. Implementation procedures go to Design Doc]
+Example: "Use dependency injection" ✓, "Implement in Phase 1" ✗
+
+## Related Information
+
+- [Links to related ADRs, documents, issues, PRs, etc.]