claude-md
- Repo stars 34,890
- Author updated Live
- Author repo claude-howto
- Domain
- AI
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @luongnv89 · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Node.js
- Permissions
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: claude-md
description: 在继续之前,你必须先考虑用户输入(如果不为空)。用户可能会指定: 围绕三个维度组织 CLAUDE.md: 对于较大的项目,建议创建 agent_docs/ 文件夹: |- buildingth…
category: ai
runtime: Node.js
---
# claude-md output preview
## PART A: Task fit
- Use case: 在继续之前,你必须先考虑用户输入(如果不为空)。用户可能会指定: 围绕三个维度组织 CLAUDE.md: 对于较大的项目,建议创建 agent_docs/ 文件夹: |- buildingtheproject.md |- running_tests.md runs entirely locally; runs on Node.js. Works with Claude Code, Cursor, Cline and 23 more..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “用户输入 / 核心原则 / 黄金法则” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “在继续之前,你必须先考虑用户输入(如果不为空)。用户可能会指定: 围绕三个维度组织 CLAUDE.md: 对于较大的项目,建议创建 agent_docs/ 文件夹: |- buildingtheproject.md |- running_tests.md runs entirely locally; runs on Node.js. Works with Claude Code, Cursor, Cline and 23 more.”.
- **02** When the source has headings, the agent prioritizes “用户输入 / 核心原则 / 黄金法则” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source does not require a stable slash command. After installation, invoke the skill by name and describe the task.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files.
Start with a small task and check whether the result follows “用户输入 / 核心原则 / 黄金法则”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: claude-md
description: 在继续之前,你必须先考虑用户输入(如果不为空)。用户可能会指定: 围绕三个维度组织 CLAUDE.md: 对于较大的项目,建议创建 agent_docs/ 文件夹: |- buildingth…
category: ai
source: luongnv89/claude-howto
---
# claude-md
## When to use
- 在继续之前,你必须先考虑用户输入(如果不为空)。用户可能会指定: create - 从零创建新的 CLAUDE.md update - 改进已有的 CLAUDE.md audit - 分析并报告当前 CLAUDE.md 的质量 一个具体…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “用户输入 / 核心原则 / 黄金法则” and keep inference separate from source facts.
- read files, write/modify files; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "claude-md" {
input -> user goal + target files + boundaries + acceptance criteria
context -> 用户输入 / 核心原则 / 黄金法则
rules -> SKILL.md triggers / order / output contract
runtime -> Node.js | read files, write/modify files | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} 用户输入
$ARGUMENTS
在继续之前,你必须先考虑用户输入(如果不为空)。用户可能会指定:
create- 从零创建新的 CLAUDE.mdupdate- 改进已有的 CLAUDE.mdaudit- 分析并报告当前 CLAUDE.md 的质量- 一个具体路径,用于创建或更新(例如
src/api/CLAUDE.md代表目录级说明)
核心原则
LLM 是无状态的:CLAUDE.md 是每次对话中唯一会自动包含的文件。它是让 AI agent 了解代码库的主要入门文档。
黄金法则
少即是多:前沿 LLM 大约能遵循 150-200 条指令。Claude Code 的系统提示词本身已经占了大约 50 条,因此 CLAUDE.md 必须聚焦且简洁。
只放通用信息:只包含每次会话都适用的内容。任务特定的说明应该放在单独文件里。
不要把 Claude 当成 lint 工具:风格指南会膨胀上下文并降低指令遵循效果。应改用确定性工具(如 prettier、eslint 等)。
绝不自动生成:CLAUDE.md 是 AI harness 中杠杆最高的位置。应该经过认真思考后手工编写。
执行流程
1. 项目分析
首先分析当前项目状态:
检查是否存在已有的 CLAUDE.md 文件:
- 根目录:
./CLAUDE.md或.claude/CLAUDE.md - 目录级:
**/CLAUDE.md - 全局用户配置:
~/.claude/CLAUDE.md
- 根目录:
识别项目结构:
- 技术栈(语言、框架)
- 项目类型(monorepo、单体应用、库)
- 开发工具(包管理器、构建系统、测试运行器)
查看已有文档:
- README.md
- CONTRIBUTING.md
- package.json、pyproject.toml、Cargo.toml 等
2. 内容策略(WHAT, WHY, HOW)
围绕三个维度组织 CLAUDE.md:
WHAT - 技术与结构
- 技术栈概览
- 项目组织方式(对 monorepo 尤其重要)
- 关键目录及其用途
WHY - 目的与背景
- 项目是做什么的
- 为什么做出这些架构决策
- 每个主要组件负责什么
HOW - 工作流与约定
- 开发流程(bun vs node、pip vs uv 等)
- 测试流程和命令
- 验证与构建方法
- 关键“坑点”或非显而易见的要求
3. 渐进式披露策略
对于较大的项目,建议创建 agent_docs/ 文件夹:
agent_docs/
|- building_the_project.md
|- running_tests.md
|- code_conventions.md
|- architecture_decisions.md
在 CLAUDE.md 中引用这些文件,并写明:
关于详细的构建说明,请参考 `agent_docs/building_the_project.md`
重要:使用 file:line 引用,而不是代码片段,以避免上下文过时。
4. 质量约束
创建或更新 CLAUDE.md 时:
- 目标长度:少于 300 行,理想情况下少于 100 行
- 不要写风格规则:移除任何 lint/format 相关说明
- 不要写任务特定说明:移到单独文件中
- 不要写代码片段:改用文件引用
- 不要重复信息:不要重复 package.json 或 README 中已有内容
5. 必备章节
一个结构良好的 CLAUDE.md 应包含:
# 项目名称
一句简短的项目描述。
## 技术栈
- 主语言和版本
- 关键框架/库
- 数据库/存储(如有)
## 项目结构
[仅适用于 monorepo 或复杂结构]
- `apps/` - 应用入口
- `packages/` - 共享库
## 开发命令
- 安装:`command`
- 测试:`command`
- 构建:`command`
## 关键约定
[只保留非显而易见、高影响的约定]
- 约定 1,简要说明
- 约定 2,简要说明
## 已知问题 / 坑点
[经常让开发者踩坑的内容]
- 问题 1
- 问题 2
6. 需要避免的反模式
不要包含:
- 代码风格指南(交给 lint 工具)
- 如何使用 Claude 的说明
- 对显而易见模式的冗长解释
- 复制粘贴的代码示例
- 泛泛而谈的最佳实践(例如“写干净的代码”)
- 特定任务的说明
- 自动生成内容
- 大量 TODO 列表
7. 验证清单
在最终确定前,检查:
- 少于 300 行(最好少于 100 行)
- 每一行都适用于所有会话
- 没有风格/格式规则
- 没有代码片段(使用文件引用)
- 命令已经验证可用
- 对复杂项目使用了渐进式披露
- 已记录关键坑点
- 没有与 README.md 重复
输出格式
对于 create 或默认模式:
- 分析项目
- 按上述结构起草 CLAUDE.md
- 向用户展示草稿以供审阅
- 在获得批准后写入相应位置
对于 update:
- 读取现有 CLAUDE.md
- 按最佳实践进行审计
- 识别:
- 需要删除的内容(风格规则、代码片段、任务特定内容)
- 需要压缩的内容
- 缺失的重要信息
- 向用户展示修改建议
- 在获得批准后应用修改
对于 audit:
- 读取现有 CLAUDE.md
- 生成报告,包括:
- 当前行数与目标的对比
- 可通用于所有会话内容的百分比
- 发现的反模式列表
- 改进建议
- 不要修改文件,只做报告
AGENTS.md 处理
如果用户请求创建或更新 AGENTS.md:
AGENTS.md 用于定义专门的 agent 行为。与 CLAUDE.md(项目上下文)不同,AGENTS.md 定义的是:
- 自定义 agent 角色和能力
- agent 级约束与说明
- 多 agent 场景下的工作流定义
同样适用以下原则:
- 保持聚焦和简洁
- 使用渐进式披露
- 用外部文档引用代替内联内容
备注
- 在写入前始终验证命令是否可用
- 不确定时就不要写,少即是多
- 系统提醒会告诉 Claude,CLAUDE.md “可能相关,也可能不相关” - 噪音越多,越容易被忽略
- monorepo 最需要清晰的 WHAT/WHY/HOW 结构
- 目录级 CLAUDE.md 应该更聚焦
Decide Fit First
Design Intent
How To Use It
Boundaries And Review