adrian/adrian-altner.com
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
adrian-altner.com/CLAUDE.md
Adrian Altner 017bf6e067 init
2026-03-30 14:16:43 +02:00

4.5 KiB
Raw Blame History

CLAUDE.md

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

Commands

npm run dev            # Start dev server (localhost:4321)
npm run build          # astro check + build + copy-sw (use this to verify changes)
npm run check          # Type check + Biome lint
npm run check:fix      # Type check + Biome lint with auto-fix
npm run stylelint      # Lint CSS/Astro styles
npm run stylelint:fix  # Fix style issues

There are no automated tests. Verification is done via npm run build (0 errors required) and the preview MCP tools.

Architecture

Astro 6 site running in SSR mode (Node.js standalone adapter) with static output for most routes. TypeScript strict mode. Path alias @/* → src/*.

Formatter/linter: Biome (not ESLint/Prettier). Run check:fix after larger edits.

Content Collections (src/content.config.ts)

Five collections defined with Zod schemas:

Collection Path Notes
blog src/content/blog/ Posts with series support (seriesParent, seriesOrder), tags, category ref, syndication URLs
categories src/content/categories/ Referenced by blog posts
notes src/content/notes/ Short-form with optional cover image
links src/content/links/ Curated external links
collections_photos src/content/photos/collections/ Photo collections; photos stored as JPG + JSON sidecar files in img/ subdirs

Key Routing Patterns

  • /blog/[...slug] — Blog posts use the full content path as slug (e.g. 2026/03/01/post-name)
  • /og/blog/[...slug].png — OG images generated server-side via Satori (src/lib/og.ts)
  • /rss/blog.xml, /rss/notes.xml, /rss/links.xml, /rss/photos.xml — Separate RSS feeds per content type
  • /photos/collections/[...slug] — Nested photo collections with breadcrumb navigation

Lib Utilities (src/lib/)

  • collections.ts — Photo collection helpers: collectionSlug(), buildCollectionPhotos(), buildBreadcrumbs(), getChildCollections()
  • og.ts — OG image generation using Satori (buildArticleVNode, renderOgImage)
  • webmentions.ts — Fetch and filter webmentions from webmention.io
  • photo-albums.ts — Photo album organisation utilities

Scripts (scripts/)

  • mastodon-syndicate.js — Scans src/content/blog and src/content/notes for posts without a syndication field, posts to Mastodon, writes the status URL back to frontmatter. Env vars: MASTODON_BASE_URL, MASTODON_ACCESS_TOKEN, MASTODON_VISIBILITY, MASTODON_DRY_RUN, MASTODON_LIMIT
  • publish-posts.sh — Full deploy orchestration: rsync content to VPS → rebuild container → send webmentions → run mastodon-syndicate

IndieWeb / Syndication

Blog posts support POSSE via mastodon-syndicate.js. After posting, the Mastodon status URL is written to frontmatter as syndication: ["https://..."]. The SyndicationLinks component reads this and renders u-syndication microformat links. Webmentions are fetched at build time from webmention.io and displayed via WebMentions.astro.

Workflow

1. Plan First

  • Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
  • If something goes sideways, STOP and re-plan immediately - don't keep pushing
  • Write plan to tasks/todo.md with checkable items (not just TodoWrite tool)
  • Check in before starting implementation

2. Subagent Strategy

  • Use subagents liberally to keep main context window clean
  • Offload research, exploration, and parallel analysis to subagents
  • For complex problems, throw more compute at it via subagents

3. Self-Improvement Loop

  • After ANY correction from the user: update tasks/lessons.md with the pattern
  • Review tasks/lessons.md at session start
  • Write rules that prevent the same mistake from recurring

4. Verification Before Done

  • Never mark a task complete without proving it works
  • Run npm run build — must complete with 0 errors
  • Use preview MCP tools to visually verify UI changes

5. Demand Elegance (Balanced)

  • For non-trivial changes: pause and ask "is there a more elegant way?"
  • Skip for simple, obvious fixes — don't over-engineer

6. Autonomous Bug Fixing

  • When given a bug report: just fix it. Point at logs/errors, then resolve them.

Core Principles

  • Simplicity First: Make every change as simple as possible. Impact minimal code.
  • No Laziness: Find root causes. No temporary fixes. Senior developer standards.
  • Minimal Impact: Changes should only touch what's necessary.