Skip to content

CLAUDE.md

Latest commit

 

History

History
156 lines (112 loc) · 7.41 KB

CLAUDE.md

File metadata and controls

156 lines (112 loc) · 7.41 KB

Personal knowledge base

This is an LLM Wiki — a personal knowledge base where LLM actively builds and maintains structured Markdown pages instead of answering from scratch every time. The wiki is public but primarily serves as a personal reference.

The LLM owns the wiki layer — it creates pages, updates them, maintains cross-references. The human brings sources and questions. Every interaction should leave the wiki better than before.

Language

  • English is the default language
  • Czech is the secondary language

Structure

Content lives in src/content/docs/ organized by topic (AI, Development, macOS, …). Each .md or .mdx file is one wiki page. Use .mdx only when the page needs Astro components.

Sidebar navigation is configured in astro.config.mjs. When adding a new top-level category, always add it to the sidebar array there. Do not change directory structure without asking first.

File naming

  • Use human-readable filenames with spaces: Canon RF lenses.md, not canon-rf-lenses.md
  • Filenames can be in English or Czech, matching the page language
  • Keep filenames short but descriptive — 2–4 words max
  • No date prefixes — this is a wiki, not a blog

Frontmatter

  • Use YAML syntax — do not use JSON-style frontmatter
  • Keep frontmatter minimal — only set fields that differ from defaults
  • Always use title for the page title — it is the only required field
  • Always include description for SEO and social media previews
  • Use sidebar.label only when the title is long or differs from desired sidebar text
  • Do not repeat title in sidebar.label if it is the same
  • Use sidebar.order to control position within an autogenerated sidebar group — lower numbers appear higher; use a high number (e.g. 99) to push a page to the bottom
  • Do not set slug unless the file path does not match the desired URL
  • When referencing pages by slug in the sidebar array in astro.config.mjs, always use lowercase paths (e.g. 'ai/benchmarks', not 'AI/Benchmarks') — Starlight slugs are always lowercase regardless of file casing
  • When updating a page, always preserve existing frontmatter fields
  • Always include created with the date the page was first created (format YYYY-MM-DD) — never change this value after initial creation
  • Always include updated with the date of the last edit (format YYYY-MM-DD) — update this value on every change to the page
  • Order frontmatter fields consistently: title, description, created, updated, sidebar, then any extras

Images and assets

  • Store images next to the page that uses them — in the same directory
  • Use kebab-case for image filenames: prompt-caching-diagram.png, not Screenshot 2025-04-06.png
  • Reference images with relative paths: ![Alt text](./prompt-caching-diagram.png)
  • Always include meaningful alt text for accessibility
  • Prefer PNG for screenshots and diagrams, SVG for icons and simple illustrations

Page format

  • Do not use # (h1) in page body — Starlight renders title as h1
  • Start with a short introductory paragraph (1–3 sentences) explaining what the page covers
  • Use ## for main sections, ### for subsections — do not go deeper than ####
  • Use Starlight admonitions where appropriate: :::note, :::tip, :::caution, :::danger
  • Use tables for comparisons and structured data — keep them narrow (max 4–5 columns) so they remain readable
  • Use fenced code blocks with language identifiers (e.g. python, bash)
  • Keep pages concise — aim for scannable content, not exhaustive essays
  • Write in a simple, factual tone — no filler, no fluff, no unnecessary decoration
  • Prefer structured lists and short paragraphs over walls of text
  • One topic per page — split if a page grows beyond a single focused subject

New page template

When creating a new page, follow this structure:

---
title: Page Title
description: One-sentence summary for SEO and previews.
created: 2025-04-06
updated: 2025-04-06
---

Short intro paragraph explaining what this page covers and why it matters.

## First section

Content here.

## Sources

- [Source title](https://example.com) — brief note on what was used

Workflow

Ingest

When adding a new topic or source:

  1. Read and understand the source material
  2. Create a new page or update existing relevant pages
  3. When new information contradicts existing content, update with the newer information without asking
  4. Check if related pages need updates to stay consistent

Query

Answer from existing wiki pages. If the answer is worth keeping, write it back into the wiki. Every query should produce two outputs — an answer for the user and an update to the wiki if the answer adds value.

Lint

Periodically check for:

  • Contradictions between pages
  • Outdated claims (especially prices, versions, benchmarks)
  • Orphan pages with no inbound links
  • Missing cross-references between related topics
  • Claims without source attribution — never synthesize without citation

When to create a new page vs. update existing

Create a new page when:

  • The topic is distinct enough to stand on its own (has its own name, tools, concepts)
  • Adding it to an existing page would make that page lose focus

Update an existing page when:

  • The new information is a detail, example, or clarification of an existing topic
  • The existing page explicitly covers this area but is incomplete

When in doubt, update the existing page and split later if it grows too large.

Sources and attribution

  • When a page is based on an external source, include a ## Sources section at the bottom
  • If the page is written purely from LLM knowledge without external sources, omit the ## Sources section entirely
  • Link to the original with a brief note: [Title](url) — what was used from this source
  • Include access date for sources that change frequently
  • Do not copy content verbatim — always summarize and restructure in your own words
  • Every factual claim should be traceable to a source — do not synthesize without citation

Searching

If ack is available, use it to search Markdown files:

ack --type=markdown "search_text"

Git conventions

  • Use conventional commits: docs: add page on prompt caching, docs: update LLM comparison table
  • One commit per logical change — adding a page, updating related pages together, fixing a typo
  • Do not batch unrelated changes into a single commit
  • Commit after each LLM pass so diffs are reviewable and revertable
  • Always push after committing

Rules

  • Do not delete pages without asking first
  • Do not rewrite entire pages when making small updates — edit only the relevant sections
  • Do not create empty placeholder pages — every page must have real content
  • Do not create index or navigation pages that only contain links — every page must have meaningful content of its own
  • When updating a page, check if related pages need updates too
  • Use relative links for cross-references between wiki pages
  • All page links must use slugs: lowercase with hyphens as separators. Convert the page title by lowercasing everything and replacing spaces with hyphens. Example: Claude Code → claude-code
  • When linking to pages in the same directory, always use ../slug (not ./slug) — the page URL includes the page name as a path segment, so ./ resolves into the current page, not the directory
  • Never add redirects to astro.config.mjs when reorganizing content — only do so when explicitly asked
⚡