This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Sign in to like and favorite skills
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
This is Jason Liu's personal blog and consulting website built with MkDocs Material. The site features AI/ML technical content, consulting services, RAG education courses, and personal writing.
# Install dependencies (using uv as preferred) uv pip install -r requirements-doc.txt # Development server with live reload mkdocs serve # Build static site mkdocs build # or ./build_mkdocs.sh # Utility scripts python check_links.py # Verify all links in markdown files python generate_sitemap.py # Generate SEO sitemap with AI summaries python generate_desc.py # Add AI-generated descriptions to posts
The site uses MkDocs with Material theme for static site generation:
docs/docs/writing/posts/mkdocs.ymldocs/stylesheets/docs/javascripts/Key architectural decisions:
When adding new blog posts:
docs/writing/posts/python generate_desc.pypython check_links.pyStructure: Core insights upfront → glossary of key terms → concrete examples → actionable next steps
Opening Format: Use "The core insight:" or "Two core insights:" followed by direct statement. Include series positioning: "This is part of the Series Name. I'm focusing on X because it's where theory meets practice."
Subheadings: Avoid corny/dramatic language. Use direct, descriptive headers like "Implementation Strategy" instead of "The Evolution from Chunks to Context" or "Why Agents Need Different Information Architecture" instead of "The Persistence Advantage: Why Agents Change Everything"
Citations: Weave research naturally to support arguments. Use descriptive link text ("research shows", "Anthropic's approach"). Position strategically where they strengthen specific points.
Key insights: "Bad context is cheap but toxic" (computational cheapness ≠ business value), coding agents as leading edge, economics/ergonomics matter, transferable principles across industries.
Tone: Concise, practical urgency ("this matters now"), concrete metrics, honest about complexity. First-person perspective from consulting experience.
Consulting Attribution: Include early reference: "Through my consulting work, I help companies..." and conclude with collaboration invitation: "If these approaches resonate with your challenges or if you're interested in working together, I'd love to help."
Cross-linking: Use blog-crosslink-optimizer agent to enhance posts with natural internal links that add reader value.
Context Engineering Series: Multi-post series exploring practical approaches to building better agentic RAG systems. Each post should:
Blog Post Titles: Use direct, actionable formats like "Four Levels Every RAG System Should Implement" or "Two Experiments We Need to Run on AI Agent Compaction" rather than abstract concepts.
scripts/shortlinks.py--blog-tag--blog-tag coding-agents-lessonsuv run python scripts/shortlinks.py "https://example.com" --title "Descriptive Title" --desc "Short description" --tags "tag1,tag2" --external-id "unique-id-for-link" --blog-tag "blog-slug"