huhan3000/CLAUDE.md

CLAUDE.md

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

Project Overview

胡汉三千年 (Hu-Han Three Thousand Years) is an academic research project that redefines Chinese civilization's world historical significance through theoretical frameworks combining historical research, cultural analysis, and modern technology tools.

Key Theoretical Frameworks

1. Y音正统性理论 (Y-Sound Orthodoxy Theory): Global patterns of power legitimacy through Y-sounds
2. 北朝宇宙模式 (Northern Dynasty Universe Model): Multi-inclusive civilization development paradigm
3. 音韵表意文字系统 (Phonetic-Semantic Writing System): Alternative to Chinese characters used by northern nomadic peoples
4. 圐圙词根网络 (Kulue Root Network): Systematic network of 32 vocabulary items revealing linguistic patterns

Common Development Commands

Documentation

# Build documentation
./build_docs.sh

# Serve documentation locally
./serve_docs.sh

# Manual Sphinx build (if scripts fail)
cd documentation/sphinx-docs && make html

Environment Setup

# Install documentation dependencies
pip install -r documentation/sphinx-docs/requirements.txt

# Setup AI tools
./tools/ai-tools/scripts/setup_codex.sh

# Setup visualization tools
./tools/setup/install-viz-tools.sh

Testing

# Test Milvus GPU integration
python test_milvus_gpu.py

# Test ZSH plugins
./test_plugins.sh

Architecture & Structure

Core Directories

• core-theory/: Theoretical framework definitions and core concepts
• historical-research/: Historical analysis and geopolitical studies
• academic-papers/: Research methodology and academic publications
• literary-works/: Poetry and literary analysis
• tools/: AI integration, image processing, and visualization tools
• documentation/: Sphinx-based documentation system

Key Files

• core-theory/core_definitions.py: Central theoretical framework definitions
• core-theory/phonetic_semantic_framework.md: Phonetic-semantic writing system
• core-theory/heaven_earth_logic_framework.md: "Heaven-Earth connection" philosophy
• core-theory/kulue_root_network.md: Kulue root word network analysis

Documentation System

• Sphinx-based with multilingual support (Chinese/English)
• Two configurations: documentation/sphinx-docs/conf.py (main) and documentation/docs/conf.py (alternative)
• MyST parser for Markdown support
• Read the Docs theme with customizations
• Automated CI/CD via GitHub Actions and Gitea workflows

Virtual Environments

• gpu_test_env/: GPU testing environment
• sphinx-env/: Documentation building
• config/.venv/: Jupyter and development tools
• tools/ai-tools/codex_env/: AI tools integration

Development Guidelines

When Working with Theoretical Content

• Maintain academic rigor and citation standards
• Use "纯逻辑考古 (pure logic archaeology)" methodology
• Apply "多重验证 (multiple validation)" approach (linguistic + historical + geographical + cultural)
• Focus on "文明系统演化 (civilization system evolution)" framework

When Working with Technical Tools

• Test GPU integrations with test_milvus_gpu.py
• Use appropriate virtual environments for different tools
• Follow Sphinx documentation standards for new content
• Maintain CI/CD compatibility for automated builds

When Working with Documentation

• Build and test documentation before committing
• Use MyST Markdown syntax for enhanced features
• Maintain both Chinese and English content where applicable
• Follow existing academic formatting standards

Recent Research Focus

The project recently achieved a breakthrough in "Japanese phallic worship originating from Northern Wei dynasty" (commit b6105b6), combining:

• Textual analysis of character variants
• Architectural evidence (Yingxian Wooden Pagoda)
• Institutional cultural transmission analysis (386-645 CE)

Important Notes

• This is primarily a research and documentation project, not a software application
• Git LFS is enabled for large assets (3body-related materials)
• Academic integrity is paramount - maintain proper attribution and methodology
• Cultural sensitivity required when handling historical and cultural analysis
• Strategic focus on addressing China-US strategic misjudgment through cultural understanding