Coding Standard

Project Context

• CLAUDE.md: !find . -maxdepth 1 -name "CLAUDE.md" -type f
• AGENTS.md: !find . -maxdepth 1 -name "AGENTS.md" -type f
• project-discovery.md: !find . -maxdepth 3 -name "project-discovery.md" -type f
• Rules directory: !find . -maxdepth 4 -type d -path "*/.claude/rules/coding-standards"

Step 1: Determine Mode

Determine which mode to operate in based on the user's request:

| Mode | When | Initial Status | Then | |------|------|----------------|------| | Creating new | Building a coding standard from scratch | proposed | → Step 2 | | Converting existing | User provides an existing document (ADR, etc.) to convert | accepted | → Step 2 | | Updating existing | Modifying an existing coding standard | — | Read the existing coding standard, → Step 3 |

Step 2: Evaluate Appropriateness

Coding standard documents are not a replacement for automated tooling. Before proceeding, evaluate whether the proposed coding standard falls into one of these categories:

• Conventions that should be enforced by linters or formatters (variable naming, indentation, whitespace, import ordering, bracket placement, line length, semicolons)
• Common language conventions that are well-known or easily discoverable from the language's own documentation and community norms (type declaration style, etc.)

If the proposed coding standard falls into one of these categories:

1. Warn the user that this is typically handled by automated tooling or is a well-known language convention, and that documenting it adds maintenance burden without value. Recommend configuring tooling instead.
2. Ask the user whether they still want to proceed
3. If the user declines, stop — the skill is done

If the proposed coding standard does not fall into these categories, proceed to the YAGNI check below.

YAGNI check

Apply the evidence-based YAGNI rule from [../../references/yagni-rule.md](../../references/yagni-rule.md) alongside the companion evidence rule in [../../references/evidence-rule.md](../../references/evidence-rule.md). A coding standard is worth writing only when the project actually does the thing the standard governs today and the standard solves a real, concrete problem the team is currently hitting. Standards about patterns the project doesn't use yet, "for future flexibility", "best practice says we should…", or symmetry with other standards ("we have one for backend, so we should have one for frontend" when the frontend codebase is a single file) are YAGNI candidates. Acceptable evidence the standard is needed now:

• The pattern the standard governs is actively used in the codebase today (cite at least three examples), and inconsistency between examples is causing real friction (review churn, bugs, onboarding cost).
• A documented incident or recurring code-review finding the standard would prevent.
• A regulatory or compliance rule the project actually falls under that requires the convention.
• A user-described need ("I keep having to remind people about X").

If no accepted evidence applies, recommend deferring the standard with the trigger that would justify writing it (a third instance of the pattern lands, a real incident occurs, a recurring review finding accumulates). Surface the recommendation to the user with the override option.

Step 3: Discover Project Structure

1. Retrieve project config: Resolve project config: read CLAUDE.md's ## Project Discovery section for docs and coding-standards directories; fall back to project-discovery.md; fall back to Glob defaults (docs/, docs/coding-standards/). Continue without any keys that remain unfound.

1. Determine the coding standards directory:

• If a coding standards directory was found, use it
• If only a docs directory was found, create {docs-dir}/coding-standards/
• If neither was found, create docs/coding-standards/

1. Enumerate existing coding standards: If a coding standards directory was found, use Glob to enumerate existing .md files in that directory.

1. Check existing coding standard format: If existing coding standards were found via Glob, read one to understand the project's existing format. If it uses a different format than the template at [template.md](./references/template.md), ask the user whether to match the existing format or use this skill's template.

1. Discover the filename hierarchy taxonomy: Coding standards are organized by a one- or two-level hierarchy encoded in the filename so related standards sort together in a directory listing. Discover the taxonomy that applies to this project — never hardcode it.

• From existing filenames: If existing standards were enumerated, parse their filenames to extract the leading hierarchy segments already in use (e.g., svelte-component-naming.md → top-level svelte; svelte-stores-state-shape.md → top-level svelte, second-level stores). Build a list of top-level prefixes and known second-level prefixes per top-level.
• From project context: Read CLAUDE.md and project-discovery.md (paths from project context above) to identify the project's languages, frameworks, runtimes, and major subsystems. Each of these is a candidate top-level hierarchy (e.g., svelte, rails, postgres, terraform, api, worker).
• Carry forward to Step 6: the discovered top-level prefixes (existing + candidate) and any second-level prefixes already in use under each.

1. Discover the project's primary file-type globs and group them into index-file buckets. The paths: frontmatter in Step 6 needs file globs scoped to the languages and directories the new standard governs. The Step 7 integration then routes the new standard into one or more per-file-type index files under .claude/rules/coding-standards/, where each index file owns a single file-type bucket (for example, svelte.md owns **/*.svelte; typescript.md owns **/*.ts and **/*.tsx; ruby.md owns **/*.rb and app/**/*.rb). Build the candidate glob set and its bucket grouping now so Steps 6 and 7 have them on hand.

• From CLAUDE.md and project-discovery.md: extract every language, file extension, and major source directory the project actually uses (e.g., **/*.go, **/*.ts, **/*.tsx, **/*.py, **/*.rb, app/**/*.rb, services/**/*.go).
• From existing standards' paths: frontmatter: if any existing standard already carries paths:, collect its globs as candidate glob prefixes — they reflect the project's accepted scoping vocabulary.
• From existing index files under .claude/rules/coding-standards/: if the rules directory was found in the project context, enumerate the index files already present and read each one's paths: frontmatter. Each existing file defines an established bucket; reuse it rather than introducing a parallel bucket for the same file type.
• Fallback: if no source yields globs, glob the project root for the dominant file extensions (**/*.{ext} for each extension seen in more than a handful of files) and surface what you found.
• Group into buckets: organize the resolved candidate glob set into file-type buckets, one per index file. Reuse an existing bucket whenever one fits; introduce a new bucket only when no existing index file's paths: covers the new glob. Name new buckets after the language, framework, or subsystem they cover (e.g., svelte, typescript, ruby, sql) — the bucket name becomes the index file's filename in Step 7.
• Carry forward to Steps 6 and 7: the candidate glob set grouped by bucket, plus the list of existing index files and the globs each one owns.

Step 4: Gather Context

1. From the arguments and conversation, determine:

• Topic: what the coding standard covers
• Scope: which parts of the system it applies to
• Motivation: why this needs to be a coding standard

1. If any of these are unclear, use AskUserQuestion to clarify before writing

Launch evidence-gathering agents

Skip these agents when the user has already provided full Correct-usage examples and conflicting-pattern evidence. Otherwise, launch both in parallel — one finds what the codebase already does, the other checks what the project has already documented. Include the topic, scope, and docs/coding-standards directories from Step 3.

1. Launch han-core:codebase-explorer agent (implementation patterns) — prompt: "Explore the codebase for existing implementations related to {topic} across {scope}. Return concrete places that illustrate the convention in practice (Correct-usage candidates), places that violate or contradict the convention (What-to-avoid candidates), and any places where the convention is applied inconsistently across the codebase. For each place, return a file path, a line range, and one or more greppable durable anchors — read ${CLAUDE_SKILL_DIR}/references/durable-references.md and follow its Rules 1 and 2 to derive them; where Rule 2 reaches escalation, return the place flagged for engineer review instead of an anchor. Focus on real files; do not invent examples."

1. Launch han-core:codebase-explorer agent (standards and ADRs) — prompt: "Explore {docs-directory} and {coding-standards-directory} for existing coding standards, ADRs, or project docs that touch {topic} across {scope}. Return: any standards or ADRs that already cover this topic (in full or in part), cross-references that the new standard will need to link — each as a document path plus a stable section heading — and any contradictions between existing docs that the new standard will need to resolve or cite."

After both agents complete, merge their findings into a context block:

• Correct-usage candidates — durable anchor(s), plus the line range (Step 6 drops it unless a house style keeps it) — for Step 6
• What-to-avoid candidates — same pairing — for Step 6
• Flagged candidates — places the rule could not cleanly anchor, carried as engineer-review items for Step 6; no reference is emitted for one without engineer input
• Inconsistency notes — areas where the convention is applied unevenly (these become Rationale material, not examples)
• Existing-doc cross-references (document path plus stable section heading) for Step 7

Step 5: Convert Source Document (skip if creating new or updating)

When converting an existing document into a coding standard:

1. Read the source document
2. Map sections to coding standard sections using the mapping at [adr-conversion-mapping.md](./references/adr-conversion-mapping.md)
3. If the source document is fully subsumed: delete it and update references (search CLAUDE.md, AGENTS.md, and other markdown files)
4. If the source document retains useful content: add a link to the new coding standard in the source document and remove migrated sections

Step 6: Write the Coding Standard

Read the durable-reference rule in [durable-references.md](./references/durable-references.md) and apply it throughout this step — this is the rule's authoring mode — all rules apply. For any candidate Step 4 flagged for engineer review — or any example you cannot cleanly anchor yourself — surface it to the engineer with a recommended resolution rather than emitting a coarse or anchorless reference; do not silently resolve it.

1. Copy the template from [template.md](./references/template.md)
2. File name: {top-level}[-{second-level}]-{hyphenated-name}.md — a one- or two-level hierarchy prefix followed by the standard's specific name. The hierarchy must come from the taxonomy discovered in Step 3.5, never invented or hardcoded.

• Top-level (required): the highest-level grouping the standard belongs to (e.g., svelte, rails, postgres, api). Reuse an existing top-level prefix from Step 3.5 when one fits; only introduce a new top-level when no existing prefix applies, and prefer one that matches a language, framework, or subsystem already named in CLAUDE.md or project-discovery.md.
• Second-level (optional): add only when the top-level has — or will plausibly grow — multiple standards that benefit from a sub-grouping (e.g., svelte-stores-…, svelte-components-…). Reuse an existing second-level prefix from Step 3.5 when one fits. Skip the second level when the standard is the only one (or one of a few) under its top-level.
• Hyphenated-name (required): the specific topic of this standard, hyphenated, distinct from the hierarchy prefix.
• If the discovered taxonomy offers more than one reasonable placement, ask the user to choose before writing.

1. Location: place in the directory determined in Step 3
2. Fill in metadata:

• Status: per Step 1 mode (proposed for new, accepted for converted)
• Applies To: a membership criterion for entities governed by this standard, per durable-reference Rule 3.
• Date Created / Last Updated: current date and time

1. Propose the paths: glob list and get user approval. The paths: field in the YAML frontmatter is the canonical declaration of which file globs the standard governs. Step 7 uses each glob to route the new standard into one or more per-file-type index files under .claude/rules/coding-standards/ — the standard itself is never loaded directly as a path-scoped rule. The index files are what Claude Code loads via Claude Code path-scoped rules, and they then point Claude at this standard on demand. Cross-cutting standards whose paths: span multiple file-type buckets get listed in each matching index.

• Build the candidate list from the Applies To text and Scope section of this standard, intersected with the project file-type globs discovered in Step 3.6. Scope a glob no broader than the standard actually governs — if the standard applies only to Svelte stores, prefer src/**/stores/**/*.ts over **/*.ts.
• Surface the proposal to the user with AskUserQuestion (or as a recommendation when running unattended). Quote the Applies To text or scope clause that justifies each glob; mark inferred globs as (inferred). Name the index-file bucket(s) each glob will be routed into in Step 7 so the user can see the integration consequence. Do not write the file until the user confirms or proposes a substitute.
• YAML rule: each glob must be double-quoted (characters like *, {, [ are YAML-significant and fail to parse unquoted). Globs follow Claude Code's standard glob syntax (**, *, ?, {a,b}).

1. Write the YAML frontmatter at the top of the file. Place a --- block before the # {Title} heading containing at minimum the approved paths: list. Example:

``` --- paths:

• "**/*.go"
• "internal/services/**/*.go"

--- `` When updating an existing standard (Step 1 mode = "Updating existing"), preserve every existing frontmatter key — only ADD or REPLACE paths:. Never strip name, description, type`, or any other key the file already carries.

1. Fill each template section with real code examples from the codebase (found in Step 4)
2. Code fence language identifiers must match the project's actual languages
3. For cross-cutting coding standards: include examples from each system area, label by area not language, set Applies To to list all areas, and propose a paths: list that includes one glob per area (e.g., "app/**/*.rb" plus "services/**/*.go")
4. If no real code examples exist yet (coding standard for a pattern not yet implemented): label examples as "Proposed pattern" and note this in the Introduction

Step 7: Integration

The standard is consumed by Claude Code through a small set of per-file-type index files under .claude/rules/coding-standards/. Each index file is itself a path-scoped rule that carries paths: frontmatter for one file type (or a closely-related group), a brief load-on-d

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: testdouble
• Source: testdouble/han
• License: MIT

Install and usage instructions live in the source repository linked above.