Skip to content

CLAUDE.md

Latest commit

 

History

History
377 lines (291 loc) · 13.3 KB

CLAUDE.md

File metadata and controls

377 lines (291 loc) · 13.3 KB

CLAUDE.md - AI Assistant Guide for WebIntro Repository

Project Overview

Project Name: 「書けるフロントエンド完全攻略」(Complete Frontend Writing Guide) Purpose: A comprehensive educational repository for learning web frontend development from basics to advanced topics Language: Japanese documentation with English technical terms Status: Early-stage (planning phase - only requirements document exists currently)

Target Technologies

  • HTML & CSS (layouts, responsive design)
  • JavaScript (DOM manipulation, event handling)
  • TypeScript (type-safe component design)
  • React (component-based architecture, state management)
  • Next.js (routing, image optimization, SSR/SSG)
  • Deployment platforms (GitHub Pages, Vercel)

Repository Structure

Current State

WebIntro/
├── .git/                   # Git version control
└── README.md               # Requirements definition document (要件定義書)

Planned Structure (as per README.md)

WebIntro/
├── docs/                   # Educational materials (markdown)
│   ├── 01_env/            # Environment setup
│   ├── 02_html-css/       # HTML & CSS fundamentals
│   ├── 03_js/             # JavaScript basics
│   ├── 04_ts/             # TypeScript introduction
│   ├── 05_react/          # React fundamentals
│   ├── 06_nextjs/         # Next.js introduction
│   ├── 07_ux/             # UX enhancement
│   ├── 08_deploy/         # Deployment & operations
│   └── 09_final/          # Advanced & final project
├── samples/                # Working code samples
│   ├── 01_env/            # Hello World examples
│   ├── 02_html-css/       # Profile page examples
│   ├── 03_js/             # Interactive UI examples
│   ├── 04_ts/             # TypeScript component examples
│   ├── 05_react/          # Todo app example
│   ├── 06_nextjs/         # Multi-page site example
│   ├── 07_ux/             # Web service example
│   ├── 08_deploy/         # Deployment examples
│   └── 09_final/          # Final project examples
├── README.md               # Project overview & navigation
└── CLAUDE.md               # This file - AI assistant guide

Curriculum Overview (9 Chapters)

Chapter Topic Learning Outcome Sample Deliverable
1 Environment Setup VS Code, Node.js, GitHub, Next.js setup Hello World app
2 HTML & CSS Layouts, responsive design, styling Personal profile page
3 JavaScript Basics DOM manipulation, event handling Interactive UI components
4 TypeScript Introduction Type-safe component design Typed React components
5 React Fundamentals Components, state management Todo application
6 Next.js Introduction Routing, image optimization Multi-page website
7 UX Enhancement Forms, API integration, SPA Simple web service
8 Deployment & Operations Vercel deployment, metadata Published website URL
9 Advanced & Final Project Custom project, iteration Complete personal website

Target Audience

  • Primary: Web frontend beginners to intermediate learners
  • Secondary: UI/UX enthusiasts and web production learners
  • Language: Japanese speakers (all documentation in Japanese)

Learning Goals

Students completing this curriculum should be able to:

  1. Technical Competency: Understand and use TypeScript, React, and Next.js appropriately
  2. Implementation Skills: Build UI components and assemble complete websites
  3. Design Skills: Apply information architecture and state management principles
  4. Publishing Skills: Deploy websites to GitHub Pages or Vercel
  5. Self-Sufficiency: Execute full development workflow from environment setup to deployment independently

Development Workflows

For Creating Educational Content

  1. Documentation (docs/):

    • Write in Japanese with clear explanations
    • Use markdown format
    • Include screenshots and diagrams (visual-first approach)
    • Provide step-by-step instructions
    • Link to corresponding sample code
    • Ensure beginner-friendly explanations

  2. Sample Code (samples/):

    • Must be executable with simple commands
    • Include clear comments (in Japanese)
    • Follow modern best practices
    • Provide README.md in each sample directory
    • Include package.json with clear scripts
    • Ensure reproducible setup

  3. Chapter Structure:

    • Each chapter should have both docs/ and samples/ content
    • Progressive difficulty (basics → advanced)
    • Clear learning path from previous chapter
    • Practical, hands-on examples

Git Workflow

  • Main branch: Stable, production-ready content
  • Feature branches: Use claude/ prefix for AI-generated content
  • Commit messages: Clear, descriptive (can be in Japanese or English)
  • Testing: Verify all sample code runs successfully before committing

Code Quality Standards

  1. Sample Code Requirements:

    • Executable without errors
    • Modern JavaScript/TypeScript syntax
    • Clear variable/function naming
    • Appropriate code comments
    • No security vulnerabilities
    • Mobile-responsive where applicable

  2. Documentation Requirements:

    • Beginner-friendly language
    • Visual aids (screenshots, diagrams)
    • Step-by-step instructions
    • Expected outcomes clearly stated
    • Troubleshooting sections where helpful

Key Conventions for AI Assistants

Language Guidelines

  1. Documentation Language: Write all docs/ content in Japanese
  2. Code Comments: Write in Japanese for educational clarity
  3. Technical Terms: Use English terms with Japanese explanations where appropriate
  4. README files: Primary content in Japanese, code snippets with English keywords
  5. Variable/Function Names: Use English (standard programming convention)

Content Creation Guidelines

  1. Visual-First Approach:

    • Prioritize clarity and understanding over brevity
    • Use diagrams, screenshots, and visual examples
    • Show before/after comparisons for changes

  2. Progressive Learning:

    • Build on previous chapters
    • Reference earlier concepts when introducing new ones
    • Maintain consistent terminology throughout

  3. Hands-On Focus:

    • Every concept should have executable code
    • Provide "try it yourself" opportunities
    • Include challenges/exercises for practice

  4. Beginner-Friendly:

    • Assume minimal prior knowledge
    • Explain "why" not just "how"
    • Provide context for technical decisions
    • Avoid unexplained jargon

File Organization

  1. Naming Conventions:

    • Use numbered prefixes for chapter ordering (01_, 02_, etc.)
    • Use kebab-case for directory names
    • Use descriptive names that match content

  2. Directory Structure:

    • Keep docs/ and samples/ parallel in structure
    • Each chapter directory should be self-contained
    • Include index/README in each major directory

  3. Asset Management:

    • Store images in docs/[chapter]/images/ or assets/images/[chapter]/
    • Use relative paths in markdown
    • Optimize images for web (compressed, appropriate dimensions)

Sample Code Standards

  1. Package.json Requirements:

    {
  "name": "descriptive-name",
  "scripts": {
    "dev": "command to run development server",
    "build": "command to build project",
    "start": "command to run production build"
  }
}

  2. README Requirements for Samples:

    • Purpose of the sample
    • Setup instructions
    • How to run
    • Expected output/behavior
    • Key learning points

  3. Code Style:

    • Use consistent formatting (Prettier recommended)
    • Follow modern ES6+ conventions
    • TypeScript for type safety where applicable
    • Clear component/function separation

Common Tasks for AI Assistants

Creating New Chapter Content

  1. Create directory structure: docs/XX_topic/ and samples/XX_topic/
  2. Write documentation in docs/XX_topic/README.md
  3. Create working sample code in samples/XX_topic/
  4. Add images/diagrams to docs/XX_topic/images/
  5. Test sample code execution
  6. Update main README.md navigation if needed
  7. Commit with descriptive message

Updating Existing Content

  1. Read existing content thoroughly
  2. Maintain consistent tone and style
  3. Preserve existing learning flow
  4. Update related samples if documentation changes
  5. Test any code modifications
  6. Document what was changed and why

Creating Sample Applications

  1. Initialize appropriate project structure (React, Next.js, etc.)
  2. Add clear comments in Japanese
  3. Keep code simple and focused on learning objectives
  4. Include error handling where appropriate
  5. Create accompanying README with setup/run instructions
  6. Test on clean environment to ensure reproducibility

Technical Considerations

Environment Setup Assumptions

  • Students will use VS Code as their editor
  • Node.js will be installed (specify version requirements)
  • Git will be available for version control
  • Students have basic command line familiarity
  • Modern web browser (Chrome, Firefox, Safari, Edge)

Deployment Targets

  • GitHub Pages: For static HTML/CSS/JS projects
  • Vercel: For Next.js and React applications
  • Focus on free tier options suitable for learning

Accessibility & Best Practices

  • Semantic HTML
  • ARIA labels where appropriate
  • Keyboard navigation support
  • Responsive design (mobile-first approach)
  • Performance optimization (image optimization, code splitting)

Troubleshooting Common Issues

When Creating Sample Code

  1. Dependencies: Always include package.json with exact versions
  2. Path Issues: Use relative paths, avoid absolute paths
  3. Environment Variables: Document any required .env setup
  4. Port Conflicts: Use standard ports (3000 for Next.js) and document
  5. Build Errors: Test build process, not just development mode

When Writing Documentation

  1. Broken Links: Verify all internal and external links
  2. Image Paths: Ensure relative paths work from repository root
  3. Code Blocks: Use proper syntax highlighting
  4. Version Conflicts: Specify version requirements clearly

Project Status & Next Steps

Current Status (as of last update)

  • ✅ Requirements document created (README.md)
  • ⏳ Directory structure not yet implemented
  • ⏳ No documentation chapters created yet
  • ⏳ No sample code created yet
  • ⏳ No configuration files (package.json, etc.) created yet

Immediate Next Steps

  1. Create directory structure (docs/ and samples/)
  2. Set up chapter 01 (Environment Setup)
  3. Create first working sample (Hello World)
  4. Establish documentation template/format
  5. Add project configuration files (.gitignore, etc.)

Long-term Goals

  • Complete all 9 chapters with documentation and samples
  • Add supplementary materials (cheat sheets, reference guides)
  • Include video tutorials or animated diagrams
  • Build community contribution guidelines
  • Create automated testing for sample code
  • Publish to GitHub Pages or as GitHub repository template

Questions to Clarify with User

When working on this repository, AI assistants should clarify:

  1. Target Node.js Version: Which version should be recommended?
  2. Package Manager: npm, yarn, or pnpm?
  3. Styling Approach: Plain CSS, CSS Modules, Styled Components, Tailwind?
  4. React Version: Which version (consider stability vs. modern features)?
  5. Next.js Version: Which version and rendering strategy (App Router vs Pages Router)?
  6. Testing Framework: Should testing be included? (Jest, Vitest, Testing Library?)
  7. Linting/Formatting: ESLint and Prettier configurations?
  8. Accessibility Level: WCAG compliance level target?

Additional Resources

Related Documentation

Community & Support

  • Issues: Use GitHub issues for bug reports and questions
  • Contributions: Follow the planned structure and conventions
  • Discussions: Use GitHub discussions for general questions

For AI Assistants: Quick Reference

Before Making Changes

  • ✓ Read README.md to understand current requirements
  • ✓ Check existing content structure and style
  • ✓ Understand which chapter you're working on
  • ✓ Identify target audience (beginners)

When Creating Content

  • ✓ Write documentation in Japanese
  • ✓ Create both docs/ and samples/ content
  • ✓ Test all code samples before committing
  • ✓ Use visual aids (screenshots, diagrams)
  • ✓ Keep explanations beginner-friendly
  • ✓ Follow progressive learning approach

Before Committing

  • ✓ All sample code runs without errors
  • ✓ Documentation is clear and complete
  • ✓ Links and images work correctly
  • ✓ Consistent with existing content style
  • ✓ Commit message is descriptive

When in Doubt

  • ✓ Ask user for clarification
  • ✓ Check README.md for guidance
  • ✓ Follow existing patterns in repository
  • ✓ Prioritize learner experience over technical sophistication

Last Updated: 2025-11-17 Repository: https://github.com/K-Subaru-nd80/WebIntro Branch Strategy: Use claude/ prefix for AI-generated feature branches