brand-voice

brand-voice

Claude Code 向けのブランド文体を自動で適用します。設定可能で、手間もかかりません。

Claude が Markdown ファイルを作成または編集するたびに、brand-voice がブランドガイドラインに照らしてチェックし、違反があればファイルの保存前に Claude へ修正を促します。手動レビューも、プロンプトごとにルールを伝える必要もありません。

Claude は違反の一覧を読み、ファイルを修正して書き込みを再試行します。すべて自動で行われます。

---

brand-voice を使う理由

ブランドガイドラインは、どこかのドキュメントに置かれたままになりがちです。Claude は、すべてのプロンプトに貼り付けない限り、その内容を読みません。貼り付けても、時間の経過とともにルールが揺らいでいきます。

brand-voice は、ルールを仕組みとして適用します。

• どの会社でも使えます — 独自の用語、文体、ビジュアルアイデンティティを設定できます
• 違反を報告するだけでなく、自動修正します — PostToolUse フックが不適切な書き込みをブロックし、再試行を促します
• 幅広い用途をカバーします — Claude Code 用のフック、オンデマンドチェック用の MCP サーバー、CI パイプライン用の CLI を備えています
• コードを適切に扱います — フェンス付きブロック、インデントされたコード、インラインコードの範囲、テーブルのセルは無視します
• 例外設定も用意しています — ファイル全体には .brand-voice-ignore、個別の行には `` を使えます
• ビジュアルアイデンティティも含められます — 色、フォント、ロゴの URL を同じガイドラインファイルに記載できます

---

インストール

npm install -g brand-voice

または、インストールせずに実行します。

npx brand-voice@latest check

Node.js 18 以降が必要です。

---

クイックスタート

オプション A — Claude Code でガイド付きセットアップ（推奨）

任意の Claude Code セッションでセットアップスキルを実行します。

/brand-voice-setup

このスキルですべてを設定できます。

1. 既存のブランドドキュメントがあるか、4 つの質問に答えるかを確認します
2. 必要に応じて、ウェブでブランドを自動調査します
3. プロジェクトに brand-guidelines.md を作成します
4. CLAUDE.md に概要ブロックを追加します
5. .claude/settings.json に PostToolUse フックを登録します
6. .mcp.json に MCP サーバーを登録します

セットアップ後、Claude が編集するすべての .md および .mdx ファイルが自動でチェックされます。

オプション B — 手動セットアップ

# 1. Install
npm install -g brand-voice

# 2. Create brand-guidelines.md in your project root (see schema below)

# 3. Register the hook
brand-voice setup

---

仕組み

3 つのコンポーネントが連携します。

コンポーネント	機能
PostToolUse フック（brand-voice-check）	.md／.mdx に対する Write／Edit／MultiEdit の実行後に動作します。違反があれば 2 で終了して Claude に自動修正を促し、問題がなければ 0 で終了します
MCP サーバー（brand-voice-mcp）	オンデマンド分析と単語単位の修正に使う analyze_readability と apply_suggestions を公開します
CLI（brand-voice）	CI パイプライン、ラチェットベースライン、GitHub の PR アノテーションに使うスタンドアロンのチェッカーです

チェック対象

ルール	重大度	説明
禁止語句	エラー	単語全体に対して大文字・小文字を区別せず照合し、書き込みをブロックします
回避語句	警告	同じ方法で照合し、推奨する代替表現を提示します
文の長さ	警告	1 文あたりの最大語数を設定できます（デフォルト：25）
受動態	警告	助動詞と過去分詞のパターンを検出します
可読性レベル	警告	各文の Flesch-Kincaid グレードを目標値と比較します

コードブロック、インラインコード、インデントされたブロック、テーブルの行はチェックされません。チェック対象は文章のみです。

チェック対象外： 物理的な行の長さや改行です。CLAUDE.md に追加される内容には、連続した段落を書き、レンダラーに折り返しを任せるよう Claude に指示する書式ルールが常に含まれます。ただし、アナライザー自体には行幅のルールがなく、今後も追加されません。文の長さは文字数や行数ではなく語数で測るため、強制的に改行した文章と改行していない文章は同じスコアになります。

PostToolUse フックの終了コード

コード	意味
0	違反なし — ファイルを受け入れます
2	違反あり — Claude が出力を読み取り、修正して再試行します

終了コード 1 は使用しません（再試行を促すのではなく、セッションを中断します）。

---

brand-guidelines.md

ブランド設定全体を 1 つの Markdown ファイルにまとめます。コンテキストに収まるよう、600 語未満にしてください。

# Brand Guidelines

## Persona
Who you are and who you write for.

## Tone & Voice
- Direct, honest, clear
- Person: second          ← "first" | "second" | "third"
- Voice: active           ← "active" | "passive"
- Sentences: max 25 words
- Contractions: yes       ← "yes" | "no"
- Exclamation marks: no

## Vocabulary
**Always use:** Acme, Acme Platform, APIs
**Avoid:** leverage, utilize, synergy, seamless
**Forbidden:** [competitor names, unverified claims]

## On-Tone Examples
> Connect your data in minutes — Acme handles the routing.

## Off-Tone Examples
> Leverage our cutting-edge platform to seamlessly integrate.

## Visual Identity
- Primary color: #006EFA
- Secondary color: #0050C3
- Accent color: #FF9DFF
- Background color: #FFFFFF
- Text color: #282828
- Logo (light): https://cdn.example.com/logo-light.svg
- Logo (dark):  https://cdn.example.com/logo-dark.svg
- Heading font: Inter
- Body font: Source Sans Pro

## Formatting Rules
- Heading style: sentence case
- Oxford comma: yes
- Readability target: 8th grade

## Quick Reference
Repeat your top 5 rules here. This section appears last —
where LLM attention is highest — to reinforce critical rules
against context-window attention drop-off.

完全な動作例については、example/brand-guidelines.md をご覧ください。

セクションの別名

## On-Brand Examples と ## Off-Brand Examples は、## On-Tone Examples／## Off-Tone Examples の別名として使用できます。その他のセクション名は、大文字と小文字を区別しない完全一致である必要があります。

検索パス

フックと CLI は、次の順序で brand-guidelines.md を検索します。

1. 現在の作業ディレクトリ
2. ~/.claude/brand-guidelines.md（ユーザースコープ — すべてのプロジェクトにルールを適用します）
3. Git ルートまでの親ディレクトリ

---

違反の抑制

ファイルまたはディレクトリを除外する — .brand-voice-ignore

プロジェクトのルートに .brand-voice-ignore ファイルを作成します。gitignore 形式のパターンを使用します。

# Auto-generated content
dist/
CHANGELOG.md

# Agent prompt files — intentional brand vocabulary exceptions
data/prompts/**

# Vendor docs
vendor/

1 行だけ除外する — インラインコメント

違反を抑制するには、このコメントを行内の任意の場所に追加します。違反が意図的な場合の一時的な例外に便利です。

---

MCP サーバー

analyze_readability

ファイルまたはインラインテキストの違反と読みやすさスコアを確認します。

入力：

フィールド	型	必須	説明
file	string	file／text のいずれか	.md／.mdx ファイルの絶対パスまたは相対パス
text	string	file／text のいずれか	分析するインライン Markdown
cwd	string	いいえ	brand-guidelines.md の検索に使用する作業ディレクトリ

戻り値： { filePath, passed, violations[], readabilityScores, visualIdentity }

apply_suggestions

禁止語や回避対象語に対して、安全な単語単位の置換を適用します。文の長さ、受動態、グレードは修正しません。これらには人間の判断が必要です。

入力：

フィールド	型	必須	説明
file	string	はい	修正するファイルのパス
dryRun	boolean	いいえ	書き込まずに差分をプレビューします（デフォルト：false）

戻り値： 差分と変更一覧（ドライラン時）、または確認メッセージと変更一覧（実行時）

ヒント： まず dryRun: true を実行してプレビューし、その後に適用してください。

---

CI 統合

brand-voice は Claude Code とは独立して動作します。任意のパイプラインに追加できます。

すべての .md ファイルを確認する：

npx brand-voice@latest check

現在のブランチで変更されたファイルのみを確認する：

npx brand-voice@latest check --changed-only

GitHub Actions のインライン注釈（PR の差分コメント）：

npx brand-voice@latest check --reporter github-pr-review

ラチェットによる適用 — 最初からすべてをクリーンな状態にしなくても、リグレッションを防止できます。

# Run once, commit the file
npx brand-voice@latest baseline --save

# In CI: fail only if violations increase above baseline
npx brand-voice@latest check --baseline .brand-voice-baseline.json

GitHub Actions ワークフローの例：

name: Brand Voice
on:
  pull_request:
    paths: ['**.md', '**.mdx']

jobs:
  prose:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: npx brand-voice@latest check --changed-only --reporter github-pr-review

終了コード 0 = 問題なし、またはベースライン以内。終了コード 1 = エラーあり、またはベースライン超過。

---

CLI リファレンス

brand-voice <command> [options]

Commands:
  check [file]          Check a file or all .md files in cwd
  setup                 Print instructions to run /brand-voice-setup in Claude Code
  import <file>         Normalize a brand-guidelines.md into cwd
  baseline --save       Save current violation count as ratchet baseline
  vale-sync             Check that the Vale binary is available

Check options:
  --changed-only        Only check files changed in git (requires git)
  --baseline <file>     Compare against a baseline JSON file (ratchet check)
  --reporter github-pr-review  Emit GitHub Actions annotation format

---

プログラム API

import { parseGuidelines, analyzeText, loadGuidelines } from 'brand-voice';

const guidelines = loadGuidelines(process.cwd());
if (guidelines) {
  const result = analyzeText(markdownString, 'doc.md', guidelines);
  console.log(result.violations);        // Violation[]
  console.log(result.readabilityScores); // ReadabilityScores
  console.log(result.passed);            // false if any error-severity violations
}

型定義の詳細については、src/types.ts をご覧ください。

---

配布パターン

シナリオ	対応方法
個人開発者	プロジェクトごとに /brand-voice-setup を 1 回実行し、brand-guidelines.md をコミットします
チーム	brand-guidelines.md、.claude/settings.json、.mcp.json をコミットします。チームメンバーは git pull すると適用を受けられます
グローバル（すべてのプロジェクト）	グローバルフラグを指定して /brand-voice-setup を実行します。~/.claude/brand-guidelines.md に書き込みます
claude.ai（ブラウザー）	セットアップスキルが Claude Project の指示に貼り付けるブロックを出力します。フックや MCP は不要です
エンタープライズ／CI	パイプラインで brand-voice check を使用します。ラチェットによる適用には .brand-voice-baseline.json をコミットします

---

要件

• Node.js 18+
• brand-guidelines.md — /brand-voice-setup で作成するか、手動で作成します
• Vale — 任意。vale-sync にのみ必要です

---

コントリビューション

バグ報告、機能リクエスト、プルリクエストを歓迎します。セットアップ手順、維持すべき重要な不変条件、コードスタイルのガイダンスについては、CONTRIBUTING.mdをご覧ください。

---

ライセンス

MIT — LICENSEをご覧ください。