claude-skills / main-agent
CLAUDE.md0 starsChanged 40 days agoMITView on GitHub
When I ask you to create or improve a project's CLAUDE.md (including via /init or CLAUDE.md skills), apply these standing rules:
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
29 rules. About 0 are common, 25 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈25
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 5
When I ask you to create or improve a project's CLAUDE.md (including via /init or CLAUDE.md skills), apply these standing rules:
- Distinctive: line 8
Always include a component-reuse rule: "Before creating any component, search existing components and styled blocks for one to reuse or …
- Distinctive: line 12
Keep project CLAUDE.md files short and non-obvious: conventions, commands, and gotchas the code doesn't show — don't restate what's in this …
- Distinctive: line 17
Ask me before major architectural decisions, destructive changes, or introducing new dependencies.
- Distinctive: line 19
When presenting alternatives, briefly state what each optimizes for so I can pick.
- Distinctive: line 34
Prefer wider lines over splitting expressions across multiple lines.
- Very specific: line 58
Use functional elements freely: map, reduce, Select/Where/Aggregate, pattern matching, tuples, deconstruction.
- Distinctive: line 60
Avoid deep nesting of code blocks — prefer early returns, guard clauses, and flat control flow.
- Distinctive: line 65
Prefer explicit error handling — return types that encode failure (Result patterns, nullable returns with clear semantics) over silent …
- Distinctive: line 66
Use exceptions for truly exceptional cases, not control flow.
- Distinctive: line 67
Don't swallow errors. If catching, at minimum log with context.
- Distinctive: line 71
Before adding a dependency, tell me what it does and what the alternative without it looks like.
- Distinctive: line 72
Prefer small, focused libraries over large frameworks.
- Distinctive: line 73
Keep modules loosely coupled with clear boundaries.
- Distinctive: line 77
When planning or writing a substantial feature: ask me how I want to handle tests.
- Distinctive: line 86
Write commit messages in imperative mood, concise subject line.
- Distinctive: line 87
Prefer small, focused commits over monolithic ones.
- Very specific: line 91
Before commits, run the review agent matching the stack: csharp-reviewer, react-reviewer, vulkan-reviewer (GPU/graphics code), or …
- Very specific: line 92
Use the generic reviewer only for mixed or other-language code with no dedicated reviewer.
- Very specific: line 99
Prefer Span<T>, stackalloc, value types, and ref structs for performance-sensitive paths.
- Distinctive: line 100
Use pattern matching and switch expressions over if-else chains when it improves clarity.
- Distinctive: line 103
Avoid reflection at runtime when source generators or compile-time solutions exist.
- Distinctive: line 108
Prefer dataclasses or Pydantic models over raw dicts for structured data.
- Distinctive: line 109
Use list/dict comprehensions and generator expressions freely.
- Distinctive: line 120
Don't wrap simple code in try-catch "just in case."
- Distinctive: line 121
Don't refactor code I didn't ask you to touch unless it's directly broken by the change.
- Distinctive: line 122
Don't suggest design patterns by name as if the pattern itself is the justification ("we should use the Strategy pattern here").
- Distinctive: line 123
Don't create abstractions preemptively — wait until there's a concrete second use case.
- Distinctive: line 124
Don't pad output with summaries of what you just did.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Global CLAUDE.md — Emilio
Project CLAUDE.md Authoring
When I ask you to create or improve a project's CLAUDE.md (including via /init or CLAUDE.md skills), apply these standing rules:
- React projects (my default stack: plain React + TypeScript + Zustand + styled-components):
- Always include a component-reuse rule: "Before creating any component, search existing components and styled blocks for one to reuse or extend with a variant prop. Never create a near-duplicate."
- Target latest React idioms (19+: ref as regular prop instead of forwardRef,
use(),useActionState; nodefaultProps). - Note that
react-revieweris the pre-commit review agent (see Agents section below).
- Documentation Workflow section: include a short section (~2 paragraphs) wiring the global
doc-syncagent and/followupskill, tailored to the project. What it must say is in theimpl-planskill'sreference/claude-md-section.md(skills/impl-plan/under the Claude config dir) — read it before writing the section. For a minimal/throwaway project (no docs, no README), ask me whether to include this section instead of forcing it. - Keep project CLAUDE.md files short and non-obvious: conventions, commands, and gotchas the code doesn't show — don't restate what's in this global file.
Communication
- Explain decisions and tradeoffs before acting — I want to understand the why, not just the what.
- Ask me before major architectural decisions, destructive changes, or introducing new dependencies.
- Be direct. Skip preambles like "Great question!" or "Sure, I can help with that."
- When presenting alternatives, briefly state what each optimizes for so I can pick.
- In the main conversation, when a response would ask me to decide or weigh in on 5 or more items (decisions, questions, review findings I'm meant to judge), don't end with a wall of questions: end with a compact table (# · point · your recommendation, judgment calls flagged) and offer to go through them with
/walkthrough. Not for findings you're about to fix yourself, not inside/implementruns, not when a skill is already asking via its own pickers — and never in subagent reports (they keep their own output format). - In the main conversation, when I ask to understand a large document or what a whole repo does and a full answer would run well past a screen, give a short overview and offer a guided tour (
/walkthrough tour …) once. A specific question, or a small doc or repo, just gets its answer. Not in subagent reports, not mid-task inside another skill's run, not again after I decline.
Code Style
General Philosophy
- Concise, structured, modular. Separate concerns. Keep things reusable.
- Minimal dependencies — prefer standard library and lightweight solutions over heavy frameworks.
- Strong typing and explicit contracts — avoid
dynamic,object,any, or untyped patterns unless truly necessary. - Pragmatic, not dogmatic — every rule below has exceptions when following it makes the code worse.
Formatting & Density
- Prefer wider lines over splitting expressions across multiple lines.
- One-liner
if/for/whilewithout braces when the body is a single statement:if (condition) DoThing(); - Inline simple expressions instead of unnecessary intermediate variables:
// prefer Process(a + b); // over var sum = a + b; Process(sum); - Extract variables when: a deeply nested value is reused (
msg.conversation.user.email), or nesting gets noisy enough to hurt scanning. - A few levels of nested function calls are fine. Avoid extreme chains like
f(g(h(x).Map(r => a(b(c(r)))))).
Naming
- Abbreviated variable names are fine (
ctx,cfg,msg,evt,idx,pos,vel). - Be more descriptive only when ambiguity exists — similar locals, similar globals, or domain terms that would be confusing abbreviated.
- Types, public APIs, and method names should still be clear and descriptive.
Functional & Structural
- Use functional elements freely:
map,reduce,Select/Where/Aggregate, pattern matching, tuples, deconstruction. - But don't force functional style when a loop or
ifis simpler and more readable. - Avoid deep nesting of code blocks — prefer early returns, guard clauses, and flat control flow.
- Favor composition over inheritance.
Error Handling
- Prefer explicit error handling — return types that encode failure (Result patterns, nullable returns with clear semantics) over silent defaults.
- Use exceptions for truly exceptional cases, not control flow.
- Don't swallow errors. If catching, at minimum log with context.
Dependencies & Architecture
- Before adding a dependency, tell me what it does and what the alternative without it looks like.
- Prefer small, focused libraries over large frameworks.
- Keep modules loosely coupled with clear boundaries. If something can be a standalone utility, make it one.
Testing
- When planning or writing a substantial feature: ask me how I want to handle tests. Present these options:
- Basic smoke tests — just verify the feature works end-to-end (my default).
- Detailed unit tests — cover edge cases and internal behavior.
- TDD approach — write tests first, then implement.
- For small changes, fixes, or utilities, don't write tests unless I ask.
- Suggest TDD when we're planning multiple features on a bigger project or starting a new project from scratch.
Git
- Write commit messages in imperative mood, concise subject line.
- Prefer small, focused commits over monolithic ones.
Agents
- Before commits, run the review agent matching the stack:
csharp-reviewer,react-reviewer,vulkan-reviewer(GPU/graphics code), orpython-reviewer. - Use the generic
revieweronly for mixed or other-language code with no dedicated reviewer.
Language-Specific Notes
C#
- Target latest stable C# features (top-level statements, file-scoped namespaces, primary constructors,
fieldkeyword where supported). - Prefer
Span<T>,stackalloc, value types, and ref structs for performance-sensitive paths. - Use pattern matching and switch expressions over if-else chains when it improves clarity.
- Collections: prefer
ReadOnlySpan, arrays, orImmutableArrayoverList<T>when mutation isn't needed. - Familiar with and prefer: Arch ECS, LeoECSLite, Silk.NET, CommunityToolkit.Mvvm source generators.
- Avoid reflection at runtime when source generators or compile-time solutions exist.
Python
- Type hints on all function signatures. Use
typing/ modern union syntax (X | None). - Prefer dataclasses or Pydantic models over raw dicts for structured data.
- Use list/dict comprehensions and generator expressions freely.
- Virtual environments assumed — don't suggest
--break-system-packagesor global installs.
Documentation
- Project docs are welcome — README.md, docs/ folder with features, usage instructions, API specs, diagrams.
- Inline comments during active development: no — don't add docstrings, XML comments, or explanatory comments while writing code. They create churn and can be generated after the code is stable.
- Comments for non-obvious logic: yes — if something is genuinely tricky or has a gotcha, a brief comment is fine.
Things to Avoid
- Don't wrap simple code in try-catch "just in case."
- Don't refactor code I didn't ask you to touch unless it's directly broken by the change.
- Don't suggest design patterns by name as if the pattern itself is the justification ("we should use the Strategy pattern here"). Instead, describe the actual structure and why it fits.
- Don't create abstractions preemptively — wait until there's a concrete second use case.
- Don't pad output with summaries of what you just did. If I can see the code, I can read it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

