claude-em-toolkit CLAUDE.md

Project Rules for Claude Code

These rules apply to all work in this repository. They're written as a reusable template — copy into your own project and adjust.

Commits & branches

• Use Conventional Commits style: feat:, fix:, refactor:, docs:, test:, chore:.
• Never commit directly to main. Create a feature branch per change.
• Never use git push --force, git reset --hard, or skip hooks (--no-verify) without asking first.
• Only create commits when the user explicitly asks.

Code style

• Match the existing formatting/linting config in the repo (don't introduce a new style).
• Prefer editing existing files over creating new ones.
• No speculative abstractions — solve the problem in front of you, not hypothetical future ones.
• Default to no comments; add one only when the why isn't obvious from the code.

Testing

• Every bug fix needs a regression test before it's considered done.
• Run the existing test suite before declaring a task complete; report failures honestly.

Ask before

• Installing/removing dependencies
• Modifying CI/CD config
• Any destructive or hard-to-reverse git operation
• Pushing to a shared remote

Cost and token efficiency

• Default model is set in .claude/settings.json. Don't switch to a heavier model mid task unless the task genuinely needs deeper reasoning (architecture decisions, ambiguous debugging). Routine tasks (standup notes, formatting, simple lookups) run fine on lighter/faster models.
• Read only the files and line ranges you actually need. Don't read whole large files when a grep for the relevant symbol would do.
• For broad, multi area searches, dispatch scoped subagents (see triage-researcher) rather than one sprawling search that fills your own context with raw output.
• Don't re read files you just wrote or edited to "verify." A successful Edit/Write means the change landed; trust it.
• Prefer the permission allow list in settings.json for routine, safe commands (git log, git diff, tests) so you aren't re prompted on every run. Keep the deny list for destructive operations.
• Schedule recurring routines (pulses, summaries, doc syncs) instead of running them ad hoc. A scheduled job that filters for "nothing notable, skip posting" (see jira-progress-pulse) costs far less over a month than manually re running the same broad query.