/coding-standard

name: coding-standard
description: >
  Creates and updates coding standards, conventions, rules, and guidelines for the current project. Use when creating
  new standards from scratch, converting existing documents into coding standards, or updating existing standards. Does
  not create architectural decision records — use architectural-decision-record for ADRs. Does not write feature or
  system documentation — use project-documentation for that. Does not research open-ended options — use research. Does
  not produce runbooks for operational scenarios — use runbook for that.
argument-hint: "[standard-topic or document-path]"
allowed-tools:
  Read, Write, Edit, Glob, Grep, Agent, Bash(mkdir *), Bash(find *),
  Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh")

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](../../references/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:

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

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 form