CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

📚 知見管理システム

このプロジェクトでは、Claude Codeでの効率的な開発のために体系的な知見管理システムを運用しています：

📋 知見管理ファイル構成

.claude/context.md - プロジェクトコンテキスト

.claude/project-knowledge.md - 技術的知見

.claude/project-improvements.md - 改善履歴

.claude/common-patterns.md - 頻用パターン

.claude/debug-log.md - デバッグ記録

.claude/debug/ - 一時デバッグ管理

debug/
├── sessions/     # セッション別作業ログ
├── temp-logs/    # 作業中の一時ファイル
└── archive/      # 解決済み問題の保管

🔄 知見更新フロー

新しい実装や重要な決定を行った際は、関連ファイルを更新してください：

  1. 技術的発見: → project-knowledge.md に実装パターン追加
  2. 問題解決: → project-improvements.md に改善記録追加
  3. 効率化発見: → common-patterns.md にパターン追加
  4. 重要なデバッグ: → debug-log.md に詳細記録

⚡ カスタムコマンド

重要な知見が得られた際は、以下のコマンドで適切なファイル更新を促進：

/project:learnings

このコマンドを実行すると、Claude Codeが適切なファイルに知見を整理して記録します。

重要: この知見管理システムにより、過去の経験を活用した一貫性のある開発が可能になります。新しい発見や重要な決定があった際は、必ず関連ファイルを更新してください。

プロジェクト概要

mming - 発達多様性の子ども向けプログラミング教室サイト

発達特性を持つ子ども向けのプログラミング教室の静的サイト。適性診断システムを通じて、保護者がプログラミングが子どもに適しているかを判断できる機能が中核となっている。

2024年12月 デジタル庁デザインシステム準拠完了 - デジタル庁デザインシステム（design.digital.go.jp）に準じた全面リファクタリングを実施。実用性重視のアクセシビリティ、8pxベーススペーシング、統一された色彩・タイポグラフィシステム、実用的UI/UXパターンを確立。

開発環境

よく使うコマンド

Jekyllプロジェクトの基本コマンド:

# 依存関係インストール
bundle install

# ローカルでサイトをビルド・サーブ
bundle exec jekyll serve --host 0.0.0.0 --livereload --incremental --drafts --future

# 本番用ビルド
JEKYLL_ENV=production bundle exec jekyll build

# 開発用スクリプト（改行コード修正済み）
./dev.sh      # 開発サーバー起動
./build.sh    # 本番ビルド
./docker.sh   # Docker管理

Docker開発環境

./docker.sh build    # イメージビルド
./docker.sh start    # コンテナ起動
# VS Code「Remote-Containers: Attach to Running Container」で接続

アーキテクチャ（全体リファクタリング後）

データ駆動設計 2.0

すべてのコンテンツは _data/ ディレクトリのYAMLファイルに格納（統合・最適化済み）:

シンプル・確実なフロントエンドアーキテクチャ（2024年12月最終版）

JavaScript アーキテクチャ（簡略化）

SCSS アーキテクチャ 2.0 + 統合デザインパターン

適性診断システム

コア機能である多質問式適性診断:

サイト構成（2025年6月更新）

index.html - メインページ:

  1. ヘッダー（固定ナビゲーション）- “特別な配慮が必要な子どものための専門プログラミング教室”
  2. ヒーローセクション
  3. 🆕 対象者情報セクション - 明確なターゲティング（療育・放デイ・特別支援学級対象）
  4. 教室について
  5. 特徴（3つの特徴：心理的安全性・学習環境の最適化・独自メソッド）
  6. よくある質問（対象者FAQを先頭追加）
  7. 料金・アクセス
  8. フッター（固定CTA）

trial/index.html - 体験ページ:

  1. ヒーローセクション
  2. 🆕 確認事項セクション - 対象者の事前確認（5項目チェックリスト）
  3. 適性診断紹介
  4. mmingの価値観
  5. 適性診断システム（6問形式）
  6. 結果判定と体験申込フォーム

開発状況（2024年12月 - 全体リファクタリング完了）

✅ 完了済み項目（基盤機能）

完了済み項目（全体リファクタリング 2024年12月）

アーキテクチャ刷新

パフォーマンス最適化

アクセシビリティ完全対応

デザインシステム統合

最新のサイト構成（2024年12月）

index.html - メインランディングページ:

  1. ヘッダー（固定ナビゲーション）
  2. ヒーローセクション（教室について知るCTA）
  3. 教室について（なぜmming？当事者性・約束）
  4. 特徴（3つに統合：心理的安全性・学習環境の最適化・独自メソッド）
  5. よくある質問
  6. 料金・アクセス
  7. フッター（固定CTA：体験の流れを見る）

trial/index.html - 体験専用ページ:

重要な設計変更

  1. 情報アーキテクチャの最適化:
    • 「環境の個別最適化」+「独自開発の教材」→「学習環境の最適化」に統合
    • 物理環境（光・音・温度、3つのスペース）とデジタル教材を一元管理
  2. ページ構成のスッキリ化:
    • index.htmlから「体験の流れ」セクション削除
    • materials-section削除（featuresに統合済み）
    • 詳細情報はtrial/index.htmlに集約
  3. 適性診断システムの分離:
    • index.htmlは概要・信頼構築に専念
    • trial/index.htmlで完全な適性診断〜申込フロー
  4. Material Iconsの課題解決:
    • star → 表示されない問題あり
    • calendar → scheduleに変更済み

データ駆動アーキテクチャの徹底

技術的な成果

技術的改善内容（リファクタリング）

SCSS アーキテクチャ刷新

JavaScript 簡略化（最終版）

アクセシビリティ完全対応

パフォーマンス最適化

進行中・次の開発予定

完了（デジタル庁デザインシステム対応 - 2024年12月完全実装）

🆕 最新の実装（2025年6月）対象者明確化・デジタル庁準拠完全最適化

今後の開発予定

デジタル庁デザインシステム準拠（2024年12月・実用性重視）

🎨 カラーシステム（デジタル庁準拠v2.4.0・完全階層）

_variables.scss で完全定義:

プライマリーカラー階層（50-900スケール）

セカンダリー・ターシャリーカラー

機能カラー（ビジネス必須）

インタラクションカラー（v2.4.0準拠）

リンクカラー（識別性・アクセシビリティ重視）

ニュートラルカラー（6段階グレースケール）

UI/UXデザインパターン（デジタル庁準拠）

アコーディオンカード（クリック可能）

情報バナー/リボン（表示のみ）

ボタンコンポーネント（デジタル庁準拠・実用性向上）

📝 タイポグラフィシステム（デジタル庁v2.4.0完全準拠）

フォントファミリー

フォントサイズ階層（xs-7xl完全定義）

テキストスタイル分類（デジタル庁準拠）

ライン高（用途別最適化）

Letter Spacing（タイポグラフィ品質向上）

フォントウェイト

📏 スペーシングシステム（デジタル庁v2.4.0完全実装）

基本8pxベーススペーシング（32段階）

主要スペーシング値

ネガティブスペーシング（オーバーラップ用）

セクションパディング階層（重要度別）

レスポンシブスペーシング

コンテナ幅階層

レガシー互換性

📱 レスポンシブブレークポイント（拡張）

♿ アクセシビリティ仕様（デジタル庁v2.4.0・WCAG AA準拠）

タッチターゲットサイズ（WCAG 2.1準拠）

フォーカス管理（WCAG 2.1準拠）

コントラスト比（WCAG AA準拠）

動きの軽減対応（prefers-reduced-motion）

スクリーンリーダー対応

ハイコントラストモード対応

実用性重視方針

🗂️ ファイル構造（全体リファクタリング後）

📁 コア構造

_config.yml           # Jekyll設定（GitHub Pages準拠）

_data/               # データ駆動アーキテクチャ 2.0
├── config.yml       # 🆕 統合設定（サイト・SEO・デザインシステム）
├── aptitude_check.yml # 適性診断システム（完全実装）
├── target_info.yml  # 🆕 対象者情報セクション（2025年6月追加）
├── confirmation.yml # 🆕 確認事項セクション（2025年6月追加）
├── hero.yml         # ヒーローセクション
├── features.yml     # 特徴セクション（画像スライダー対応）
├── faq.yml          # よくある質問（対象者FAQ追加済み）
├── navigation.yml   # ナビゲーション
├── ui_text.yml      # UI共通テキスト（多言語準備済み）
└── [その他セクション別YAML]

_layouts/
└── default.html     # 🔄 最適化済みレイアウト（SEO・パフォーマンス・A11y）

_includes/           # コンポーネント化
├── sections/        # ページセクション
│   ├── hero-section.html        # ヒーロー（レスポンシブ画像）
│   ├── target-info-section.html # 🆕 対象者情報（2025年6月追加）
│   ├── features-section.html    # 特徴（アコーディオン・スライダー）
│   └── [その他セクション]
├── trial/          # 体験ページ専用
│   ├── trial-confirmation-section.html # 🆕 確認事項（2025年6月追加）
│   └── [その他trial専用コンポーネント]
└── [共通コンポーネント]

assets/
├── css/
│   └── main.scss    # SCSS エントリーポイント
├── js/
│   ├── simple-main.js       # 🆕 統合JavaScript（全機能）
│   └── aptitude-check.js    # 適性診断（独立）
└── images/          # 最適化済み画像
    ├── hero_bg_*.jpg        # レスポンシブヒーロー画像
    └── [コンテンツ画像群]

_sass/               # SCSS アーキテクチャ 2.0 + デジタル庁v2.4.0準拠
├── _variables.scss          # 🔄 統合変数システム（デジタル庁v2.4.0完全準拠）
├── _mixins.scss             # 🆕 ミックスインライブラリ（統合コンポーネント）
├── _base.scss               # ベース・リセット
└── components/              # コンポーネント分離
    ├── _header.scss         # ヘッダー・ナビ（デジタル庁準拠）
    ├── _hero.scss           # ヒーロー
    ├── _target-info.scss    # 🆕 対象者情報・確認事項（2025年6月追加）
    ├── _features.scss       # 特徴（スライダー含む）
    ├── _image-slider.scss   # 🆕 画像スライダー
    ├── _aptitude-check.scss # 適性診断（統一配置対応・デジタル庁準拠）
    ├── _footer.scss         # フッター（デジタル庁準拠・ミニマル実装）
    ├── _accessibility.scss  # 🆕 アクセシビリティ（WCAG AA完全準拠）
    └── _performance.scss    # 🆕 パフォーマンス最適化

🖼️ 画像・メディア処理（最適化）

⚙️ 技術仕様・制約事項

🚫 禁止要素（設計思想）

✅ 必須機能・要件

🔧 開発・運用注意点

🎉 デジタル庁デザインシステム準拠完了

2024年12月 デジタル庁デザインシステム準拠リファクタリングにより、以下を達成：

🏛️ デジタル庁デザインシステム準拠項目

⚡ 技術実装成果

技術スタック: Jekyll + SCSS + デジタル庁デザインシステム完全準拠 + 実用アクセシビリティ + シンプルJavaScript

🆕 デジタル庁デザインシステムβ版v2.4.0準拠実装詳細

Phase 5: 完全準拠リファクタリング（2024年12月完了）

  1. 🎨 カラーシステム完全準拠: Primary階層（50-900）+ Secondary・Tertiary定義 ✅
  2. 📝 タイポグラフィシステム強化: Display/Standard/Dense/Oneline分類 + xs-7xl階層 ✅
  3. 📏 スペーシングシステム拡張: 32段階完全定義（0px-128px）+ ネガティブ値対応 ✅
  4. 🧩 コンポーネントシステム標準化: ボタン・カード・フォーム完全準拠ミックスイン ✅
  5. ♿ アクセシビリティ強化: WCAG AA完全準拠 + sr-only・ハイコントラスト対応 ✅
  6. ⚡ パフォーマンス最適化: content-visibility・will-change活用 ✅
  7. 🔧 デザイントークン体系化: 統合変数システム + レガシー互換性維持 ✅
  8. 📱 レスポンシブ強化: 6段階ブレークポイント + フルードデザイン ✅

技術実装の核心成果

🔧 重要：JavaScript設計の最終決定（2024年12月）

問題と解決策

❌ 問題: 複雑なES6モジュールシステムがブラウザ環境で動作しない

✅ 解決: シンプル・確実なアプローチに全面移行

新しいJavaScript構成

assets/js/
├── simple-main.js           # ナビゲーション、画像遅延読み込み、アクセシビリティ
└── aptitude-check.js        # 適性診断（独立したシステム）

HTML内のインライン関数:
├── toggleFAQ()              # FAQ アコーディオン
├── toggleFeature()          # 特徴 アコーディオン  
├── toggleApplication()      # 体験申込 アコーディオン
└── slideImage()             # 画像スライダー

設計思想の変更