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"
• personal config directory: !bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
• project .han/config.md: !cat .han/config.md 2>/dev/null || echo ""

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md probe supplies content, apply it per config-rule.md, which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Step 1: Determine Mode

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

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 alongside the companion evidence rule in ../../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.

2. 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/

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

4. 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, ask the user whether to match the existing format or use this skill's template.

5. 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.

6. 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
2. 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."

2. 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
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

Before writing, invoke han-communication:readability-guidance to source the shared readability standard into your context, then apply it as you write the standard's prose (Purpose, Rationale, when-to-apply, when-not-to-apply, and example commentary), holding the named audience: the engineer who must follow the standard. The frame governs how a fact is said, never whether a required fact appears — keep the exact rules, thresholds, and anchors the standard commits to.

Read the durable-reference rule in 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
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.
3. Location: place in the directory determined in Step 3
4. 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
5. 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}).
6. 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.
7. Fill each template section with real code examples from the codebase (found in Step 4)
8. Code fence language identifiers must match the project's actual languages
9. 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")
10. 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-demand instruction paragraph, and a list of entries pointing to the canonical standards in the project's coding-standards directory. When Claude Code reads a file matching an index file's globs, Claude loads only that small index, then decides which (if any) of the listed standards to open with the Read tool. The full text of a standard is never loaded automatically. This replaces the prior one-symlink-per-standard layout, which forced every standard whose paths: matched the current file into context at once. Do not add the new standard as an enumerated link in CLAUDE.md (or AGENTS.md). Rules are discovered through the .claude/rules/ surface, not through the memory file, and enumerating them in the memory file is the failure mode this integration replaces.

1. Determine which index file(s) the new standard belongs in. Using the buckets carried forward from Step 3.6, map each glob in the standard's approved paths: to a bucket. The set of matching buckets is the set of index files the standard will be listed in. A standard whose paths: spans multiple buckets (a cross-cutting standard, e.g., "app/**/*.rb" plus "services/**/*.go") will be listed in each matching index — the canonical standards file is still only ever in one place; only the index entries are repeated.

2. Ensure .claude/rules/coding-standards/ exists. Run mkdir -p .claude/rules/coding-standards.

3. For each matching index file, create or update it.

   • If the index file does not exist yet, copy the template at index-file-template.md to .claude/rules/coding-standards/{bucket-name}.md and fill it in:

     • Replace the placeholder globs in paths: with the bucket's globs (each double-quoted; see the YAML rule in Step 6.5).
     • Replace {File-type} in the heading with the bucket name (e.g., Svelte, TypeScript, Ruby). Use the capitalization that matches the language/framework's own conventions.
     • Leave the entire instruction paragraph (everything between the heading and the ## Available standards heading) verbatim. It is what tells Claude to make a relevance decision before opening any standard.
     • Replace the example bullet under ## Available standards with a single entry for the new standard (see entry format below).

   • If the index file already exists, edit it in place:

     • Append a new entry for this standard under ## Available standards, in alphabetical order by standard title (or by the existing hierarchy already in use in that index).
     • Do not modify the existing paths:, the instruction paragraph, or any other entries unless this is update-mode and the change explicitly requires it (see step 5 below).

4. Entry format. Each entry under ## Available standards is a single bullet of the form:

   - [{Standard title}]({relative-path-to-canonical-file}) — {1-3 sentence description}

   • Title: use the standard's # {Title} heading verbatim.
   • Relative path: the path to the canonical standard from .claude/rules/coding-standards/. For a canonical file at docs/coding-standards/{filename}.md, the target is ../../../docs/coding-standards/{filename}.md. Adjust the ../ depth when the docs directory is nested differently.
   • Description (1-3 sentences): name what the standard covers AND when a reader should pull the full file. This is bait for a relevance decision, not a summary of the standard. Examples: "Naming rules for Svelte components, including file names, exported types, and slot conventions. Read when creating or renaming a component." / "Transaction boundaries in repository methods. Read when writing a new repository method or changing the call sites of an existing one." Vague descriptions ("covers component conventions") cause Claude to either over-load or skip relevant standards.

5. Update-mode delta handling. If the skill is in "Updating existing" mode and the standard's paths: changed:

   • Removed buckets. For each index file that previously listed this standard but whose paths: no longer overlaps the standard's paths:, remove the standard's entry from that index. Leave the rest of the index untouched.
   • Added buckets. For each newly-matching index file, follow step 3 above (create or update) to add the entry.
   • Same buckets. If the matching index files did not change but the standard's title or description should change (e.g., the standard's scope shifted), update the entry text in place — title, link, and description — without disturbing surrounding entries.

6. Ensure the pointer paragraph exists in CLAUDE.md (or AGENTS.md). The memory file should mention the rules surface exactly once; the skill never adds an enumerated entry for the new standard.

   • Check whether the memory file already references .claude/rules/coding-standards/. If yes, leave it alone.
   • If not, append a short pointer paragraph under a "Coding Standards" heading. Adapt the wording to the project's voice, but keep the load-bearing facts:

     Coding standards live in `{docs-directory}`. They are exposed to Claude
     Code through a small set of per-file-type index files under
     `.claude/rules/coding-standards/`. Each index file is a path-scoped rule
     that lists the standards relevant to one file type, with a short
     description of each. When Claude reads a file matching an index's
     `paths:` glob, Claude loads only the index and then decides which (if
     any) standards to open. The full text of a standard is never loaded
     automatically. Standards do not appear in the available-skills picker.
     Humans continue to browse `{docs-directory}` for the canonical readable
     form.

   • Do not touch any pre-existing enumerated coding-standard entries in the memory file. Migrating those out is a separate operation, not this skill's responsibility.

7. Search for related documentation (other coding standards, ADRs, feature docs).

8. Add cross-references in the new coding standard's "Additional Resources" section.

9. Add back-references from related docs where they add value.