Skip to content

CLAUDE.md

Latest commit

 

History

History
259 lines (206 loc) · 8.71 KB

CLAUDE.md

File metadata and controls

259 lines (206 loc) · 8.71 KB

CLAUDE.md

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

Primary Directive

Focus on structure and presentation only. The user will handle all content changes separately.

The number one goal is an accessible and progressive adoption of clean standards with impeccable markup and style rules that comply with ATS best guidance for a parseable and machine-legible website.

In Scope

  • HTML structure and semantic markup
  • CSS styling and print optimization
  • Accessibility (WCAG compliance)
  • ATS parsing optimization
  • Schema.org structured data (JSON-LD)
  • Template logic and data flow
  • Build configuration and validation

Out of Scope

  • Resume content (descriptions, achievements, skills lists)
  • Position details and dates
  • Personal information changes

Project Overview

Personal resume/portfolio website for Mike Hall (just3ws.com). Built with Jekyll 4.x and validated/deployed via GitHub Actions.

Commands

See CONTRIBUTING.md for full development, test, and validation workflows.

# Quick Core Commands
./bin/server        # Local dev server
./bin/pipeline ci   # Build + Unit Test + Validate
./bin/pipeline smoke # Browser smoke tests

Architecture

Static Site Generator: Jekyll 4.x with custom generator plugins.

Resume Data Structure:

  • _data/resume/timeline.yml - List of position references (controls display order)
  • _data/resume/positions/*.yml - Individual YAML file per employer with role details
  • index.html - Main resume template (uses minimal layout)
  • resume.txt - Plain text version (auto-generated from YAML)

Styling: Minimal custom CSS in assets/css/minimal.css

  • No framework dependencies
  • Print-optimized with @media print
  • ATS-friendly semantic structure

Structured Data:

  • _includes/json-ld.html - Schema.org Person + Occupation data

Key Configuration:

  • _config.yml - Jekyll config with plugins, excludes
  • .tool-versions - Ruby 3.4.8 (for asdf/rtx)
  • CNAME - Custom domain (www.just3ws.com)

Build Output: _site/ (git-ignored, auto-generated)

Position YAML Structure

company:
  name: Company Name
  location: City, ST
title: Job Title
type: Full-time | Contract
start_date: Month YYYY
end_date: Month YYYY
context: >-
  Business context for the role (reference only, not displayed)
scope:
  scale: User/revenue scale
  ownership: What you owned
  influence: Cross-functional reach
description: >-
  Role summary (displayed on site)
achievements:
  highlights:
    - Achievement bullet points
skills:
  - Skill 1
  - Skill 2

Validation Standards

  • HTML: Valid HTML5, semantic elements, proper heading hierarchy
  • Accessibility: WCAG 2.1 AA compliance, skip links, focus states
  • ATS: Parseable text, Schema.org markup, plain text fallback
  • Print: Clean PDF output via browser print

<CRITICAL_INSTRUCTION>

BACKLOG WORKFLOW INSTRUCTIONS

This project uses Backlog.md MCP for all task and project management activities.

CRITICAL GUIDANCE

  • If your client supports MCP resources, read backlog://workflow/overview to understand when and how to use Backlog for this project.

  • If your client only supports tools or the above request fails, call backlog.get_backlog_instructions() to load the tool-oriented overview. Use the instruction selector when you need task-creation, task-execution, or task-finalization.

  • First time working here? Read the overview resource IMMEDIATELY to learn the workflow

  • Already familiar? You should have the overview cached ("## Backlog.md Overview (MCP)")

  • When to read it: BEFORE creating tasks, or when you're unsure whether to track work

These guides cover:

  • Decision framework for when to create tasks
  • Search-first workflow to avoid duplicates
  • Links to detailed guides for task creation, execution, and finalization
  • MCP tools reference

You MUST read the overview resource to understand the complete workflow. The information is NOT summarized here.

</CRITICAL_INSTRUCTION>

RTK (Rust Token Killer) - Token-Optimized Commands

Golden Rule

Always prefix commands with rtk. If RTK has a dedicated filter, it uses it. If not, it passes through unchanged. This means RTK is always safe to use.

Important: Even in command chains with &&, use rtk:

# ❌ Wrong
git add . && git commit -m "msg" && git push

# ✅ Correct
rtk git add . && rtk git commit -m "msg" && rtk git push

RTK Commands by Workflow

Build & Compile (80-90% savings)

rtk cargo build         # Cargo build output
rtk cargo check         # Cargo check output
rtk cargo clippy        # Clippy warnings grouped by file (80%)
rtk tsc                 # TypeScript errors grouped by file/code (83%)
rtk lint                # ESLint/Biome violations grouped (84%)
rtk prettier --check    # Files needing format only (70%)
rtk next build          # Next.js build with route metrics (87%)

Test (90-99% savings)

rtk cargo test          # Cargo test failures only (90%)
rtk vitest run          # Vitest failures only (99.5%)
rtk playwright test     # Playwright failures only (94%)
rtk test <cmd>          # Generic test wrapper - failures only

Git (59-80% savings)

rtk git status          # Compact status
rtk git log             # Compact log (works with all git flags)
rtk git diff            # Compact diff (80%)
rtk git show            # Compact show (80%)
rtk git add             # Ultra-compact confirmations (59%)
rtk git commit          # Ultra-compact confirmations (59%)
rtk git push            # Ultra-compact confirmations
rtk git pull            # Ultra-compact confirmations
rtk git branch          # Compact branch list
rtk git fetch           # Compact fetch
rtk git stash           # Compact stash
rtk git worktree        # Compact worktree

Note: Git passthrough works for ALL subcommands, even those not explicitly listed.

GitHub (26-87% savings)

rtk gh pr view <num>    # Compact PR view (87%)
rtk gh pr checks        # Compact PR checks (79%)
rtk gh run list         # Compact workflow runs (82%)
rtk gh issue list       # Compact issue list (80%)
rtk gh api              # Compact API responses (26%)

JavaScript/TypeScript Tooling (70-90% savings)

rtk pnpm list           # Compact dependency tree (70%)
rtk pnpm outdated       # Compact outdated packages (80%)
rtk pnpm install        # Compact install output (90%)
rtk npm run <script>    # Compact npm script output
rtk npx <cmd>           # Compact npx command output
rtk prisma              # Prisma without ASCII art (88%)

Files & Search (60-75% savings)

rtk ls <path>           # Tree format, compact (65%)
rtk read <file>         # Code reading with filtering (60%)
rtk grep <pattern>      # Search grouped by file (75%)
rtk find <pattern>      # Find grouped by directory (70%)

Analysis & Debug (70-90% savings)

rtk err <cmd>           # Filter errors only from any command
rtk log <file>          # Deduplicated logs with counts
rtk json <file>         # JSON structure without values
rtk deps                # Dependency overview
rtk env                 # Environment variables compact
rtk summary <cmd>       # Smart summary of command output
rtk diff                # Ultra-compact diffs

Infrastructure (85% savings)

rtk docker ps           # Compact container list
rtk docker images       # Compact image list
rtk docker logs <c>     # Deduplicated logs
rtk kubectl get         # Compact resource list
rtk kubectl logs        # Deduplicated pod logs

Network (65-70% savings)

rtk curl <url>          # Compact HTTP responses (70%)
rtk wget <url>          # Compact download output (65%)

Meta Commands

rtk gain                # View token savings statistics
rtk gain --history      # View command history with savings
rtk discover            # Analyze Claude Code sessions for missed RTK usage
rtk proxy <cmd>         # Run command without filtering (for debugging)
rtk init                # Add RTK instructions to CLAUDE.md
rtk init --global       # Add RTK to ~/.claude/CLAUDE.md

Token Savings Overview

Category Commands Typical Savings
Tests vitest, playwright, cargo test 90-99%
Build next, tsc, lint, prettier 70-87%
Git status, log, diff, add, commit 59-80%
GitHub gh pr, gh run, gh issue 26-87%
Package Managers pnpm, npm, npx 70-90%
Files ls, read, grep, find 60-75%
Infrastructure docker, kubectl 85%
Network curl, wget 65-70%

Overall average: 60-90% token reduction on common development operations.