claude-md-writer

用途

claude-md-writer 用于在创建或重构 CLAUDE.md 文件时，强制遵循 Anthropic 官方（2025）最佳实践，控制文件的大小、结构与内容组织方式。

主要能力

核心原则

CLAUDE.md 保持在 200 行以内（每次请求都会加载，消耗 token）。
每个规则文件不超过 500 行。
关键规则写在最前面，顶部即最高优先级。
采用模块化规则，放入 .claude/rules/，实现条件加载与组织。
使用 paths: 前置元数据，仅对匹配文件加载对应规则。
不在文档中写 lint 规则，改用 ESLint/Prettier/Biome。
用指针（引用）代替复制，因为文件会变、引用始终有效。

记忆层级

Claude Code 按以下顺序加载记忆（越靠前优先级越高）：企业级 /Library/Application Support/ClaudeCode/CLAUDE.md、项目级 ./CLAUDE.md 或 ./.claude/CLAUDE.md、规则 ./.claude/rules/*.md（条件加载）、用户级 ~/.claude/CLAUDE.md、本地级 ./CLAUDE.local.md（已 gitignore）。可用 /memory 命令查看当前已加载文件。

三层文档体系

基础层：CLAUDE.md，始终加载，目标 200 行以内。
组件层：.claude/rules/{component}/，在对应组件中工作时加载，每文件 500 行以内。
功能层：与代码同目录，在处理该功能时加载，按需而定。

示例结构：

.claude/
├── CLAUDE.md                 # Tier 1: always loaded
└── rules/
    ├── database.md           # Tier 2: SQL, migrations
    ├── api.md                # Tier 2: API patterns
    └── frontend/             # Tier 2: subdirectory
        ├── components.md     # paths: src/**/*.tsx
        ├── layout.md         # paths: src/pages/**/*.tsx
        └── tokens.md         # paths: **/*.tsx

结构模板

# Project Name

One-line description.

## Commands

- `npm run dev` - Development
- `npm run build` - Production
- `npm run test` - Tests

## Architecture

| Path | Purpose |
|------|---------|
| `lib/` | Core logic |
| `app/api/` | API routes |

## Key Patterns

**Pattern Name**: One-line explanation.

## Database (if applicable)

| Table | Key Fields |
|-------|------------|

## Modular Docs

See `.claude/rules/` for:
- `database.md` - queries, schema
- `deploy.md` - deployment

## Tech Stack

One line: Next.js 15, PostgreSQL, TypeScript

条件规则（按路径）

使用 YAML 前置元数据指定文件类型规则：

---
paths: "src/api/**/*.ts"
---

# API Rules

- All endpoints must validate input
- Use standard error format

常用 Glob 模式：**/*.ts（任意位置的 .ts）、src/**/*（src/ 下全部）、*.md（根目录 Markdown）、src/components/*.tsx（特定目录组件）。可组合：paths: "src/**/*.{ts,tsx}"、paths: "{src,lib}/**/*.ts, tests/**/*.test.ts"。注意：YAML 中模式需加引号。带 paths: 的规则仅在处理匹配文件时加载，节省 token。

使用方式

新项目流程

运行 /init 生成基础 CLAUDE.md。
检查并精简生成内容。
识别关键规则（忽略会出问题的部分）。
为领域文档创建 .claude/rules/。
主文件保持 100 行以内。

重构现有文件流程

统计行数，超过 300 行必须拆分。
找出任务特定内容（SQL、调试、部署），抽取出去。
创建 .claude/rules/：如 database.md（查询、模式、连接）、deploy.md（部署流程）、messaging.md（Telegram 等集成）。
使用 @file 引用，不要复制。
CLAUDE.md 只保留适用于每项任务的内容。

内容归属

CLAUDE.md：项目描述、关键约束（置顶）、快速开始（3 条命令）、架构概览、关键模式（一句话）。
.claude/rules/database.md：SQL 查询/模式；deploy.md：部署步骤；api.md：API 文档；git.md：Git 工作流。
CLAUDE.local.md（gitignored）：个人偏好。
代码风格规则：放 .eslintrc / biome.json，不写文档。

引用语法

用 @README.md、@docs/architecture.md、@~/.claude/snippets/common.md 引用文件而不复制；相对路径 @docs/file.md，绝对路径 @~/path/file.md，最大深度 5 跳。

CLAUDE.local.md

个人项目设置（自动 gitignore），示例：

# My Local Settings

- Prefer verbose output
- Run tests after every change
- My worktree location: .trees/

常见错误与修正

500+ 行 → 拆分到 .claude/rules/。
内联 SQL 示例 → 移到 rules/database.md。
“运行 prettier”类规则 → 改用工具配置文件。
完整 API 文档 → 移到 rules/api.md。
部署说明 → 移到 rules/deploy.md。
CLAUDE.md 中放代码 → 用 @file:line 引用。
只有否定规则 → 补充替代方案：“Don't X; use Y instead”。

质量检查清单

CLAUDE.md < 200 行？
每个规则文件 < 500 行？
关键规则在顶部？
主文件无任务特定内容？
无代码风格规则（用 ESLint/Prettier）？
领域文档放 .claude/rules/？
组件按子目录划分（frontend/、backend/）？
用 paths: 前置元数据实现条件加载？
用 @ 引用而非复制？
个人偏好放 CLAUDE.local.md？

常用命令

/init：生成初始 CLAUDE.md。
/memory：查看已加载的记忆文件。

适用场景

新建项目的 CLAUDE.md 初始化、既有过大文件的重构拆分、多层级文档体系整理、按文件类型条件加载规则的配置。

限制

本资料未提供该技能的安装方式、收费或价格信息；具体命令与配置细节以官方文档为准。