القائمة
Auto-loads design documentation style rules when .claude/design/**/*.md files are read. Enforces focused, boundary-level documentation over exhaustive code re-documentation.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | design-docs-style |
| description | Auto-loads design documentation style rules when .claude/design/**/*.md files are read. Enforces focused, boundary-level documentation over exhaustive code re-documentation. |
| user-invocable | false |
| paths | ["**/.claude/design/**/*.md"] |
These guidelines apply to files in .claude/design/. Design docs are read by agents working on implementation tasks — they provide context about key patterns, load-bearing interfaces, architectural decisions and the relationships between systems.
Design docs record why things are structured the way they are and which parts are load-bearing. They are not exhaustive code documentation. Code is authoritative about its own shape — design docs are authoritative about intent, decisions and topology.
A design doc that fits in one screenful is better than one that requires scrolling. Agents are good at exploring code; design docs should tell them where to look and what matters, not re-describe what they can read for themselves.
Document: Key architectural decisions and their rationale. Cardinal types and interfaces that are load-bearing across many files. Data flow topology — which systems delegate to which, what crosses each boundary. Tradeoffs and constraints that are not obvious from reading the code.
Do not document: Exact method counts, test counts or error type enumerations. Internal implementation details of individual modules. Anything that is easy to discover with grep or by reading the source file.
Document delegation chains and system boundaries at the topology level. "The DataLayer delegates to the DataReader, which resolves from cache or network" is worth writing down — agents lose track of this topology. How the DataReader internally resolves its value is not worth documenting — that is discoverable by reading the file.
Document: which component calls which, what data crosses each boundary, which interfaces must stay stable.
Do not document: the internal mechanics of how a component does its work.
Use file paths to direct agents to source locations rather than restating what code does. Prefer:
See
src/services/DataReader.tsfor the full resolution logic.
Over rewriting the module's behavior in prose. The second form creates a second source of truth that drifts with every code change.
The same applies to config: do not transcribe design.config.json (or any live config file) shape into a design doc. A pasted snippet of keys and values is a second source of truth that silently rots when the config changes — and nothing validates prose against the live file. Point to it instead: write "see quality.context in design.config.json" rather than pasting rootMaxWords/childMaxWords. Name a key only when its meaning is the point; never reproduce the file's current values.
"There are 7 error types" is stale before the next commit. Write "see the DataError tagged union in src/errors.ts" instead. Exact method counts, parameter lists and error enumerations belong in code, not design docs.
Exception: cardinal types whose shapes must stay stable across many files. If a type shape is a genuine constraint agents must know before editing, document it. If it is just a snapshot of what the code currently looks like, leave it out.
API, CLI) and proper nouns (TypeScript, Effect).A, B and C, not A, B, and C.Each paragraph and each list item occupies a single source line. The renderer handles wrapping. Do not insert hard line breaks inside a sentence or bullet point. If you encounter a pre-existing violation of this rule, you MUST fix it when you edit the file for other reasons, but do not add new violations. When editing a section of a hard-wrapped legacy doc, reflow the paragraphs you touch rather than matching the surrounding wrapping — a correctly formatted island is the migration path, not an inconsistency to avoid.
This is the enforced wrapping policy: design-validate warns on hard-wrapped prose, and markdownlint's MD013 (line length) is disabled intentionally — there is no maximum line length for prose.
Wrong:
This is a paragraph that has an artificial line break in the
middle of a sentence, which is against the style rules.
- This is a bullet item
that continues on a second source line.
Right:
This paragraph occupies a single source line, with no artificial breaks. The renderer wraps it appropriately.
- This is a bullet item that stays on a single source line.
Generate cross-reference graph showing relationships between design documents. Use when visualizing doc dependencies, finding related docs, or understanding documentation structure.
Validate design doc structure and frontmatter. Use when checking design docs for compliance, ensuring proper formatting, or verifying metadata before commits.
Comprehensive quality audit for CLAUDE.md context files. Use when performing thorough quality checks, preparing for releases, ensuring context efficiency, or verifying token optimization.
Style rules for LLM context files (CLAUDE.md, AGENTS.md and their .local variants). Fires automatically when these files are opened. Enforces on-demand loading patterns, proper @-reference syntax and lean context structure.
Split large CLAUDE.md into child files. Use when context files exceed word limits, are too verbose, or cover multiple distinct topics that should be separate.
Validate CLAUDE.md structure, formatting, and quality. Use when checking context files for compliance, ensuring proper structure, or verifying before commits.