From 851985dbf085a50d703b6153c94309184ebdd498 Mon Sep 17 00:00:00 2001
From: Oscar Wallberg <oscar.wallberg@outlook.com>
Date: Sat, 25 Apr 2026 04:20:10 +0200
Subject: [PATCH] feat(claude): add global CLAUDE.md

---
 .claude/CLAUDE.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++
 setup.py          |  1 +
 2 files changed, 76 insertions(+)
 create mode 100644 .claude/CLAUDE.md

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
new file mode 100644
index 0000000..aea4aeb
--- /dev/null
+++ b/.claude/CLAUDE.md
@@ -0,0 +1,75 @@
+# CLAUDE.md
+
+Cross-project preferences for working with me. Project-specific CLAUDE.md files extend or override these.
+
+## Writing
+
+### Linear prose
+
+Avoid em-dashes (—), en-dashes (–), double hyphens (--) as em-dash substitutes, and semicolons in prose. Applies to anything checked in to a project: code comments, Markdown docs, commit messages, and PR descriptions. Code syntax isn't prose, so language constructs like `;` as a statement terminator or separator don't count.
+
+Sentences should read linearly. Em-dashes, en-dashes, and semicolons all introduce sub-clauses or asides that interrupt the flow. Swapping one for another (em-dash for semicolon, em-dash for double hyphen) shifts the punctuation without solving the underlying issue. Restructure instead:
+
+- Split into two sentences with a period.
+- Use a connective: "because", "since", "which", "and", "so", "while", "where".
+- Use parentheses for a genuine aside, sparingly.
+- Use a comma for a short, tightly-integrated clause.
+- Rework so the sub-clause isn't needed.
+
+Don't substitute a regular hyphen between words where an em-dash would have gone. That's broken English, not a fix.
+
+## Code
+
+### No section-divider comments
+
+Don't add section-divider comments in source files: no `// ---` horizontal rules, no `// ===` banners, no `// -- Label --` headers that announce the next region of a file. The `struct` / `impl` / `class` / `function` definitions already mark structure, and the banner just duplicates that visually.
+
+If a file is large enough that its structure is genuinely hard to follow, split it into submodules or smaller files instead of layering dividers on top. Strip these when touching files that already have them.
+
+Markdown section headers in docs (`## Foo`) are fine. They're the intended way to structure prose.
+
+### No milestone references in code docs
+
+Don't write "for M2", "added in M1", "comes in M3", or similar milestone references in code comments or doc comments (rustdoc, JSDoc, equivalents). Describe what the code currently does or doesn't do, not which roadmap milestone it was written in or will be extended in.
+
+Milestones live in roadmap docs (`TODO.md`, `ROADMAP.md`, equivalents) and are a planning artifact. Pinning them into code docs ties the code to a numbering that will keep shifting as milestones are added, renumbered, or dropped. The code's current behaviour is the durable thing to document. The project-management metadata belongs in roadmap docs.
+
+If future work is worth flagging in a doc comment, say *what* that future work is, not *when* it's scheduled.
+
+## Commits
+
+### Use Conventional Commits
+
+Commit messages follow the Conventional Commits format. Apply this to every new commit you make.
+
+Format:
+
+```
+<type>(<optional scope>): <short description>
+
+<optional body explaining the why>
+
+<optional footers, e.g. BREAKING CHANGE: ...>
+```
+
+Common types:
+
+- `feat`: a new user-facing capability.
+- `fix`: a bug fix.
+- `refactor`: code restructuring with no external behaviour change.
+- `perf`: a performance-focused change with no behaviour change.
+- `docs`: documentation only.
+- `test`: test-only changes.
+- `build`: build-system, dependency, or configuration changes.
+- `chore`: repo housekeeping that doesn't fit above.
+- `style`: formatting only (rarely warranted if a formatter runs).
+
+Subject line: imperative, lowercase after the colon, no trailing period, aim for <= 72 chars. Body paragraphs explain the *why*, not the *what* (the diff shows the what).
+
+Breaking changes: append `!` to the type or scope (`feat(api)!: ...`) and include a `BREAKING CHANGE:` footer when the change needs explanation.
+
+Don't retroactively rewrite committed history unless the user explicitly asks.
+
+### No Co-Authored-By Claude line
+
+Don't add `Co-Authored-By: Claude ... <noreply@anthropic.com>` (or any Claude co-author trailer) to commit messages. End the commit with the actual content. The user finds the trailer adds clutter without serving any audience.
diff --git a/setup.py b/setup.py
index 60d4fb2..ddf7a4d 100755
--- a/setup.py
+++ b/setup.py
@@ -120,6 +120,7 @@ PROFILES: dict[str, Profile] = {
             Pkg("zsh"),
         ],
         symlinks=[
+            ".claude/CLAUDE.md",
             ".claude/skills",
             ".config/fish",
             ".config/lf",