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. 询问你是否已有品牌文档，或是否愿意回答四个问题
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

---

工作原理

三个组件协同工作：

组件	功能
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 注释

检查内容

规则	严重级别	说明
禁用词	error	匹配完整单词，不区分大小写——阻止写入
建议避免的词语	warning	使用相同的匹配方式——提示更推荐的替代词
句子长度	warning	可配置每句的最大词数（默认值：25）
被动语态	warning	检测助动词 + 过去分词模式
可读性年级	warning	根据目标值，逐句计算 Flesch-Kincaid 年级

绝不会检查代码块、行内代码、缩进代码块和表格行——只检查正文内容。

**绝不会检查：**物理行长度或换行。注入 CLAUDE.md 的内容始终包含一条格式规则，要求 Claude 编写连续段落，并由渲染器自动换行；但分析器本身没有行宽规则，以后也不会添加——句子长度按词数而非字符数或行数计算，因此无论正文是否硬换行，评分都相同。

PostToolUse hook 退出代码

代码	含义
0	未发现违规 — 文件通过
2	发现违规 — Claude 读取输出、进行修正并重试

永不使用退出代码 1（它会中止会话，而不是触发重试）。

---

brand-guidelines.md

一个 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 的别名。其他所有章节名称均不区分大小写，但必须完全匹配。

搜索路径

hook 和 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/

跳过单行 — 内联注释

在某一行的任意位置添加此注释，即可抑制该行中的所有违规提示。适用于违规属于有意为之的一次性例外情况。

---

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；提交 brand-guidelines.md
团队	提交 brand-guidelines.md、.claude/settings.json 和 .mcp.json；队友执行 git pull 后即可启用规则检查
全局（所有项目）	使用全局标志运行 /brand-voice-setup；将配置写入 ~/.claude/brand-guidelines.md
claude.ai（浏览器）	设置技能会生成一段可粘贴的内容，用于 Claude Project 指令 — 无需 hook 或 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。