CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## What This Repo Is
6 
7A content-only repository for [ElixirSchool.com](https://elixirschool.com). It contains lessons, blog posts, and translations. There is no Elixir application here — the website itself lives in the separate [school_house](https://github.com/elixirschool/school_house) repo.
8 
9## Useful Commands
10 
11Check translation status across languages:
12 
13```shell
14elixir bin/version_report.exs
15elixir bin/version_report.exs --lang ru,ja
16elixir bin/version_report.exs --severity major,missing
17```
18 
19## Content Structure
20 
21- `lessons/<lang>/<category>/<lesson>.md` — lesson files by language code (e.g., `en`, `ru`, `ja`)
22- `posts/YYYY-MM-DD-name-separated-with-hyphens.md` — blog posts
23- English lessons under `lessons/en/` are the source of truth; all other languages are translations
24 
25### Lesson categories (under each language)
26 
27`basics`, `intermediate`, `advanced`, `ecto`, `misc`, `storage`, `testing`, `data_processing`, `phoenix`
28 
29## Front Matter Format
30 
31All lessons require front matter in this format:
32 
33```elixir
34%{
35  version: "1.0.0",
36  title: "Lesson Title",
37  excerpt: """
38  A short description of the lesson.
39  """
40}
41---
42```
43 
44Translations set `version` to match the English source version. The version is used programmatically to detect stale translations.
45 
46**Version bump rules:**
47- MAJOR — rewrote most of the lesson (translators will need to update)
48- MINOR — added or removed sentences/paragraphs
49- PATCH — spelling/typo fixes only
50 
51Blog post front matter includes `author`, `author_link`, `tags`, `date` (`~D[YYYY-MM-DD]`), `title`, and `excerpt`.
52 
53## Writing Style
54 
55See `AGENTS.md` for the full style guide. Key points:
56 
57- Use inclusive "we" — the reader is a collaborator, not a student
58- Show code first, then explain — examples precede explanation
59- Short paragraphs; dense info gets bullet points or code blocks
60- Active voice, contractions always ("we'll", "don't", never "we will")
61- No emoji, no platitudes, no filler sentences
62- Oxford comma
63- Headers: H2 for major sections, H3 for subsections; never H1 in body content
64- Code blocks always include a language identifier
65 
66Content structure for lessons: brief overview → motivation (2-3 sentences max) → core content with code → connections to related topics.
67 
68## Translation Style Guides
69 
70Language-specific translation conventions are documented alongside the lessons:
71 
72- Russian (`ru`): [`.claude/locales/ru.md`](.claude/locales/ru.md)
73 
74## Adding New Content
75 
76**New lesson:** create `lessons/en/<category>/<lesson>.md` with front matter. A corresponding change in `school_house` may be needed to register it on the website.
77 
78**New translation:** copy the English file to `lessons/<lang>/`, translate it, keep `version` matching the English source.
79 
80**New language:** create `lessons/<iso-code>/{basics,advanced,intermediate,ecto,misc,storage,testing,data_processing,phoenix}/` and update `school_house` to register the language.
81