My global CLAUDE.md: code style, commit discipline, and a multi-session tasks/ ledger convention (see github.com/freeeve/taskman)

CLAUDE.md

Global Guidelines

File Editing

• Edit files with the dedicated Edit/Write tools, not shell text tools--no cat heredocs, python, sed, awk, or similar for file modification. The only good reason to shell out is a genuinely multi-file replace (e.g. the same rename across many files); a single-file edit never qualifies.

Code Style

• Use TypeScript strict mode
• Prefer functional components in React
• Always include JSDoc comments for public APIs
• Always do gofmt -s before committing
• Prefer fewer dependencies if possible.
• Prefer function / method level comments rather than in-line comments.
• For backend and ui with logging frameworks, prefer log messages at appropriate levels instead of in-line comments.
• Try to keep files <500 lines. Worst case <1000 lines.

Testing

• Always run tests before committing.
• Target >80% coverage unless specified
• Make fuzz tests if applicable

Committing

• In projects with sonar configured, check sonar issues before committing.
• Always do gofmt -s before committing a go project
• Always use semantic commit messages.
  • in projects where there are multiple modules, use a template like fix(module1): fixed module1 by doing such and such.
• Only describe functional or technical changes/improvements to the code:
  • no messages that sound like they're talking from AI to repo owner
• Always tag semantic version numbers.
• Commit after each task completes--don't ask, don't batch several tasks into one commit, and don't leave finished work sitting uncommitted in the working tree. Stage only the task's own files (pathspec), never a concurrent session's changes.
• Only modify the session's own working repository. Do not edit code in other repos (a co-developed sibling or dependency). If another repo needs a change, file a task there instead (see Task Tracking); committing that task file is fine, but touch nothing else in the other repo.

Writing Style

• Write em-dashes as a double hyphen -- joined directly to the surrounding words, with no spaces: word--word, never word — word or word -- word. Applies to all communication (chat replies, PR descriptions, commit messages, docs, code comments).

Task Tracking

• Task files live in tasks/ (one file per task, numbered like 001_description.md)
• Status convention--rename file to change status:
  • Pending: 001_description.md
  • In progress: 001_description.in-progress.md
  • Complete: 001_description.done.md
• Cross-repo asks: file with taskman file <repo> "desc", which mints the RECEIVING repo's next number and commits the file there immediately (the immediate commit is what makes the number claim safe). Legacy prefixed asks (<filer>_description.md, from the old convention where cross-repo asks sat uncommitted and could not safely claim a number) get renumbered with taskman adopt on adoption.
• Use the taskman CLI for ALL ledger chores instead of ad-hoc ls/grep/mv:
  • taskman list [-all] (open tasks; flags duplicates and unadopted asks), taskman next, taskman new "desc"
  • taskman start|done|reopen <n|slug-fragment>--status renames; a duplicate number or ambiguous fragment errors instead of guessing
  • taskman adopt <file>--renumber a legacy prefixed ask into the ledger
  • taskman file [-as filer] <repo-dir> "desc"--file a cross-repo ask, numbered in the target ledger and committed there
  • taskman fix [-n]--repair duplicate numbers (dups move to the lowest free numbers, most advanced status keeps the contested one); -n = dry run
• taskman's mutating commands auto-commit the touched task files with a pathspec (chore(tasks): ...), so: don't rename task files by hand, don't also commit the rename yourself, and don't fold status renames into code commits. Flow per task: taskman start N -> work -> semantic code commit(s) -> append an Outcome section to the task file -> taskman done N (commits the outcome edit + rename together). -no-commit opts out.
• Source: github.com/freeeve/taskman; install with go install github.com/freeeve/taskman@latest. Full docs in its README.