CLAUDE.md · git:20260121.979728d · 2026-01-21 · sha256 57c5a497f11a4074
CLAUDE.md git:20260121.979728dA
Immutable. This exact content is served forever at /api/v1/blob/57c5a497f11a4074.
# Skills 开发流水线 - Claude Code 项目指令
你正在 `/Users/bensz/Nutstore Files/PythonCloud/Agents/pipelines/skills` 中工作：该目录用于开发与维护一组"可复用 Agent Skills"。
## 项目目标
本项目是 **Agent Skills 开发流水线**：用于创建、优化和维护高质量、可复用的 AI Agent Skills。所有技能遵循 [Agent Skills 开放标准](https://agentskills.io)，确保在 Claude Code、OpenAI Codex、Cursor 等多个平台间"编写一次，随处使用"。
**核心价值**：
- 提供标准化的技能开发框架和工作流
- 确保技能质量（安全性、可靠性、通用性）
- 支持有机迭代和持续优化
## 核心工作流
当用户提出 Skills 开发相关需求时，按以下流程执行：
### 1. 任务理解
- 理解用户的真实需求：新建技能 / 优化现有技能 / 修复问题
- 确认任务范围和预期输出
- 识别可能的依赖和约束
### 2. 执行流程
**新建技能**：
```
需求确认 → 创建结构 → 编写 SKILL.md → 添加配置/脚本 → 质量检查 → 测试验证 → 系统安装
```
**优化技能**：
```
分析现状 → 规划改进 → 有机更新 → 自检验证 → 轻量测试 → 记录变更
```
### 3. 交付验证
- 通过有机更新检查清单
- 通过技能质量六大原则验证
- 记录所有变更到 [CHANGELOG.md](CHANGELOG.md)
## 工程原则
本项目遵循以下工程原则：
| 原则 | 核心思想 | 在本项目中的体现 |
|------|----------|------------------|
| **KISS** | Keep It Simple, Stupid | 追求极致简洁，避免过度设计 |
| **YAGNI** | You Aren't Gonna Need It | 只实现当前需要的功能 |
| **DRY** | Don't Repeat Yourself | 相似逻辑应抽象复用 |
| **SOLID** | 面向对象设计五大原则 | 单一职责、开闭原则等 |
| **关注点分离** | Separation of Concerns | 不同层次逻辑应分离 |
| **奥卡姆剃刀** | 如无必要，勿增实体 | 优先选择最简单的解决方案 |
| **最小惊讶原则** | Principle of Least Astonishment | API 行为应符合用户直觉 |
| **早期返回原则** | Early Return | 尽早返回，减少嵌套 |
**原则冲突时的决策优先级**：
1. **正确性 > 一切**
2. **简洁性 > 灵活性**
3. **清晰性 > 性能**
4. **扩展性 > 紧凑性**
## 高质量技能开发原则
基于实战经验总结，开发高质量 Agent Skills 需遵循以下六大原则：
### 1. 硬编码/AI 功能规划
**核心思想**：合理划分确定性与灵活性的边界
| 层级 | 处理方式 | 典型场景 |
|------|----------|----------|
| **确定性操作** | 硬编码到 scripts/ | 文件解析、数据验证、格式转换 |
| **启发式判断** | AI 动态处理 | 需求理解、方案设计、内容生成 |
| **可配置参数** | 提取到 config.yaml | 阈值、路径、模板、选项 |
**实践要点**：
- ❌ 避免：让 AI 反复编写相同的代码逻辑
- ✅ 推荐：将重复性、确定性操作脚本化
- ❌ 避免：硬编码会变化的业务逻辑
- ✅ 推荐：将可配置参数集中到 config.yaml
### 2. 多轮 AI 自检 + 人类监督 + 时刻轻量测试
**核心思想**：建立可重复的优化循环，确保每次变更都可验证
```
┌─────────────────────────────────────────────────────────┐
│ 优化循环（Repeatable Optimization Loop） │
├─────────────────────────────────────────────────────────┤
│ 1. AI 自检：静态分析（代码-文档一致性、逻辑推演） │
│ 2. 人类监督：审查关键决策和变更范围 │
│ 3. 轻量测试：验证核心功能（非全面测试） │
│ 4. 记录结果：在 CHANGELOG.md 中记录变更 │
│ 5. 迭代优化：根据测试结果调整（回到步骤1） │
└─────────────────────────────────────────────────────────┘
```
**实践要点**：
- 每次变更后，在 `tests/{test_name}/` 目录下进行轻量测试
- 测试目录必须包含：规划文档（PLAN.md）和测试报告（REPORT.md）
- 所有中间文件保存在测试目录，不污染项目主目录
### 3. 冗余残留错误检查
**核心思想**：每次更新时主动清理冗余和残留
**检查清单**：
- [ ] **冗余检查**：是否存在重复逻辑或可合并的相似代码？
- [ ] **残留检查**：删除功能后，相关引用是否全部清理？
- [ ] **一致性检查**：YAML frontmatter、SKILL.md、config.yaml 三者是否一致？
- [ ] **版本号检查**：确认版本号仅在 config.yaml 中记录，SKILL.md 和 README.md 中是否存在冗余的版本号记录？
- [ ] **僵尸检查**：是否存在未被引用的文件或定义？
**实践要点**：
- 删除功能时，使用 Grep 工具全局搜索引用，确保彻底清理
- 定期检查 `references/` 目录，移除过时的参考文档
- 合并相似功能时，主动重构而非简单追加
### 4. 安全性检查
**核心思想**：预防常见安全漏洞和风险
**检查维度**：
| 维度 | 检查内容 | 典型风险 |
|------|----------|----------|
| **输入验证** | 用户输入是否充分验证 | 注入攻击、路径遍历 |
| **路径处理** | 文件路径是否规范化 | 路径遍历、任意文件写入 |
| **敏感信息** | 是否泄露密钥/凭证 | 凭证泄露 |
| **权限控制** | 文件操作权限是否合理 | 权限提升 |
| **外部调用** | 网络/系统调用是否安全 | SSRF、命令注入 |
**实践要点**：
- 文件路径始终使用正斜杠（跨平台兼容）
- 用户提供的路径需验证其在项目范围内的合法性
- 避免在日志或错误消息中泄露敏感信息
- 脚本错误处理要明确，不推诿给 AI 猜测
### 5. 过度设计检查
**核心思想**：用奥卡姆剃刀原则审视每个设计决策
**自问清单**：
- "这个功能当前是否真的需要？"（YAGNI）
- "是否有更简单的实现方式？"（KISS）
- "这个抽象是否增加了不必要的复杂性？"（奥卡姆剃刀）
- "用户是否会理解这个设计？"（最小惊讶原则）
**典型反模式**：
- ❌ 为"未来可能用到"的场景预留扩展点
- ❌ 引入多层抽象解决简单问题
- ❌ 提供过多可选配置，增加理解成本
- ❌ 过度泛化，导致代码难以理解
**推荐做法**：
- ✅ 只实现当前明确需要的功能
- ✅ 优先选择最直观的解决方案
- ✅ 提供合理的默认值，减少配置负担
- ✅ 当真正需要时再重构，而非提前过度设计
### 6. 通用性检查
**核心思想**：避免不必要的场景和年份限制，提高技能复用性
**检查清单**：
- [ ] **时间敏感性**：是否包含具体年份、日期等会过时的信息？
- [ ] **场景限制**：是否过度限定使用场景？
- [ ] **平台依赖**：是否不必要地依赖特定平台或工具？
- [ ] **语言假设**：是否假设特定语言或文化背景？
**实践要点**：
- 使用相对时间描述（如"当前版本"而非"2025年版"）
- 描述功能时使用通用术语，避免特定品牌或产品
- 如需限定场景，在 YAML `description` 中说明，而非硬编码到工作流
- 提供扩展机制（如 config.yaml），而非写死配置
## 默认语言
除非用户明确要求其他语言，始终使用简体中文与用户对话与撰写文档/说明。
## 联网与搜索
默认优先使用项目内文件与本地上下文；确需联网获取信息时，优先使用本地 SearXNG（如已通过 MCP 配置）。仅当 SearXNG 不足以满足需求时再使用其它联网手段，并说明原因与保留关键链接。
### 文件访问边界
- **Prompts.md**：开发者私有的 Prompt 库，包含常用工作流和模板。AI 不应主动读入此文件，除非用户明确要求。
- 理由：Prompts.md 是开发者的"个人笔记"，用于手动调用特定流程，不是 AI 自动执行的规范
- 正确做法：优先根据项目指令（AGENTS.md）和上下文理解需求；仅在用户明确引用 Prompts.md 内容时才读入
## 目录结构
```
skills/
├── {skill_name}/ # 每个 skill 一个子目录
│ ├── SKILL.md # 必需：技能定义（YAML frontmatter + Markdown）
│ ├── README.md # 推荐：用户使用指南
│ ├── config.yaml # 推荐：技能参数配置
│ ├── scripts/ # 可选：可执行脚本
│ ├── references/ # 可选：参考文档
│ ├── assets/ # 可选：模板/资源文件
│ └── test/ # 可选：测试目录
├── AGENTS.md # 本文档：项目指令
├── CLAUDE.md # Claude Code 特定指令
├── Prompts.md # 工作流与定义（优先级最高）
└── CHANGELOG.md # 项目变更记录（强制性）
```
## Claude Code 特定说明
### 文件引用规范
在 Claude Code 中引用文件时，使用 markdown 链接语法：
- 文件：`[filename.md](path/to/filename.md)`
- 特定行：`[filename.md:42](path/to/filename.md#L42)`
- 行范围：`[filename.md:42-51](path/to/filename.md#L42-L51)`
- 目录：`[目录名/](path/to/directory/)`
### 任务管理
- 使用 TodoWrite 工具跟踪复杂任务的进度
- 完成任务后及时标记为 completed
- 拆分大任务为可管理的小步骤
### 代码变更规范
- 修改代码前先使用 Read 工具阅读文件
- 优先使用 Edit 工具进行精确修改
- 避免不必要的格式化或重构
### 语义发现机制
Claude Code 使用**语义匹配**触发技能，因此：
**YAML `description` 的特殊地位**：
- 它是技能的"语义入口"——决定了技能何时被触发
- 更新 `description` 时，必须考虑其对发现机制的影响
**更新实践**：
- 新增触发场景 → 补充 `metadata.keywords`
- 工作流变化 → 同步更新 `description`
- 技能定位变化 → 更新 `name` 和 `metadata.short-description`
### Progressive Disclosure 体现
Claude Code 的加载机制天然支持三层渐进披露：
| 层级 | 加载时机 | 有机更新要点 |
|------|----------|--------------|
| **YAML frontmatter** | 会话启动时 | 确保 `name` 和 `description` 准确反映核心价值 |
| **SKILL.md 正文** | 技能触发时 | 保持简洁，只包含 AI 执行所需的核心信息 |
| **references/** | 按需加载 | 将详细策略、标准、参考文档独立存放 |
## 有机整体更新原则
本项目的技能迭代遵循**有机整体更新**原则，而非简单的补丁式修补。
### 核心理念
**❌ 补丁式更新**（避免）：
```
用户："加一条规则：输出文件要按日期命名"
AI：在文档末尾添加："2025-12-29 更新：文件按日期命名"
```
**✅ 有机更新**（倡导）：
```
用户："加一条规则：输出文件要按日期命名"
AI：理解意图 → 定位文件命名规则在工作流中的位置 →
整合到相关章节（如"输出规范"） →
检查是否与其他规则冲突 →
重构该章节以保持内聚性 →
更新相关示例以保持一致性
```
### 操作原则
1. **理解而非记录**：在更新前，先理解用户需求背后的意图
2. **定位生态位**：每条规则都应找到其在文档结构中的位置
3. **协调生长**：更新一个部分时，检查并同步更新相关部分
4. **保持呼吸感**：文档应像生物体一样有逻辑流动，而非割裂的清单
5. **定期修剪整合**：当章节臃肿时，主动重构
### 表头-正文一致性原则
**YAML frontmatter 不是静态元数据，而是技能的"活语义接口"**：
| 工作逻辑变更 | 表头同步更新 |
|-------------|-------------|
| 新增工作流步骤 | 更新 `description` 中的功能描述 |
| 修改输入参数 | 更新 `description` 中的参数说明 |
| 新增输出格式 | 更新 `description` 中的输出描述 |
| 扩展使用场景 | 补充 `metadata.keywords` |
| 调整技能定位 | 更新 `name` 和 `metadata.short-description` |
### 更新自检清单
在响应任何"更新/优化/修改"请求时，问自己：
- [ ] **意图理解**：我真正理解了用户想要解决什么问题吗？
- [ ] **生态位定位**：这个更新应该放在文档的哪个位置？
- [ ] **影响范围**：这个更新会影响其他哪些章节？
- [ ] **冲突检查**：新内容是否与现有规则冲突？
- [ ] **术语一致性**：我是否使用了与文档其他部分一致的术语？
- [ ] **示例同步**：相关示例是否反映了新的规则？
- [ ] **内聚性保持**：更新后，该章节是否仍然围绕一个清晰的核心主题？
- [ ] **表头一致性**：我是否检查并更新了 YAML frontmatter？
## 技能开发流程
### 新建技能流程
1. **需求确认**：
- 阅读 [Prompts.md](Prompts.md)，确认是否属于"创建/优化 skill"
- 获取 `skill_name`（用户指定或自取 1-3 个候选）
2. **创建结构**：
- 创建 `{skill_name}/` 目录
- 生成 `SKILL.md`（包含 YAML frontmatter）
- 按需添加 `config.yaml`、`scripts/`、`references/`、`assets/`
3. **质量检查**：
- 通过"六大质量原则"验证
- 运行静态自检清单
4. **生成用户文档**：
- 使用 **write-skill-readme** skill 生成用户友好的 README.md
- README.md 面向使用者，说明如何触发和使用技能
- SKILL.md 面向 AI，定义执行规范和工作流
5. **测试验证**：
- 在 `tests/{test_name}/` 进行轻量测试
- 生成测试报告
6. **系统安装**：
- 运行 `python3 install-bensz-skills/scripts/install.py`
- 验证技能在任意项目中可被发现
### 优化技能流程
1. **分析现状**：
- 使用 auto-test-skill 分析问题
- 将问题记录到 `{skill_name}/suggestions/Problems_from_xxx.md`
2. **规划改进**：
- 制定优化计划（plans/v{timestamp}.md）
- 明确 P0-P2 优先级
3. **有机更新**：
- 按照有机整体更新原则修改
- 同步更新相关文件和示例
4. **自检验证**：
- 运行静态自检清单
- 检查六大质量原则
5. **更新用户文档**：
- 如技能工作流或配置有变更，使用 **write-skill-readme** skill 更新 README.md
- 确保 README.md 与 SKILL.md、config.yaml 保持一致
6. **轻量测试**：
- 在测试目录验证核心功能
- 记录测试结果
7. **记录变更**：
- 更新 `{skill_name}/CHANGELOG.md`
- 同步更新项目级 [CHANGELOG.md](CHANGELOG.md)
## Agent Skills 标准规范
### 必需结构
每个 skill 必须包含 `SKILL.md` 文件，格式如下：
```yaml
---
name: skill-name
description: Brief description of what this Skill does and when to use it
---
# Skill Title（Markdown body）
[技能说明、工作流程、使用指南等]
```
### 技能触发条件设计原则
**核心问题**：技能触发条件过于宽泛会导致 AI 在不恰当的场景下误触发技能，影响用户体验和开发效率。
**设计原则**：
| 原则 | 说明 | 示例 |
|------|------|------|
| **精确边界** | `description` 应明确界定触发条件，而非列举所有可能场景 | ✅ "用户明确要求'测试技能'时使用"<br>❌ "用于技能/项目迭代时" |
| **精简关键词** | `keywords` 只保留核心关键词，移除同义词和变体 | ✅ 保留 3-5 个核心术语<br>❌ 列举 10+ 个同义词 |
| **负向约束** | 明确说明不适用场景，避免误触发 | ✅ "以下情况不适用：用户只是想优化功能"<br>❌ 无边界说明 |
| **避免"等场景"** | "等场景"暗示更多未列举场景，扩大触发范围 | ✅ 明确列举适用场景<br>❌ "适用于XXX等场景" |
**实践要点**：
1. **`description` 应使用"当用户明确要求"句式**
- ✅ "当用户明确要求'提交 Git 改动'时使用"
- ❌ "当用户要提交 Git 改动时使用"
2. **`keywords` 应控制在 3-5 个核心术语**
- ✅ 保留：`git commit`, `conventional commit`, `commit message`
- ❌ 删除：`提交代码`, `提交改动`, `自动提交`, `拆分提交`（同义词）
3. **添加负向约束明确边界**
```yaml
description: |
当用户明确要求"测试技能"或"运行 auto-test"时使用。
⚠️ 以下情况不适用：
- 用户只是想优化/改进某个功能（应直接修改）
- 用户只是询问技能问题（应直接回答）
- 没有明确"测试"意图的一般性开发
```
4. **避免"适用于XXX等场景"句式**
- ✅ "用于以下场景：场景A、场景B、场景C"
- ❌ "适用于场景A、场景B、场景C等场景"
### YAML frontmatter 规范
| 字段 | 必需性 | 规范 |
|------|-------|------|
| `name` | 必需 | 小写字母、数字、连字符；最大 64 字符；推荐动名词形式 |
| `description` | 必需 | 最大 1024 字符；使用"当用户明确要求"句式；可包含负向约束 |
| `metadata.short-description` | 可选 | 单行概览（用于 UI 显示） |
| `metadata.keywords` | 可选 | 3-5 个核心关键词；避免同义词和变体 |
### 推荐文件结构
| 文件 | 必需性 | 面向对象 | 核心作用 |
|------|-------|---------|---------|
| **SKILL.md** | 必需 | AI | 定义工作流、输入输出、验证标准 |
| **README.md** | 推荐 | 用户 | 教用户如何触发和使用技能 |
| **config.yaml** | 推荐 | 维护者 | 集中管理可配置参数和版本号 |
| **scripts/** | 可选 | 执行引擎 | 需要确定性可靠性的自动化任务 |
| **references/** | 可选 | AI（按需） | 详细策略、标准、领域知识 |
| **assets/** | 可选 | 输出生成 | 模板、图标、字体等资源 |
### SKILL.md 格式约束原则
**核心思想**：SKILL.md 是 AI 执行时的核心输入，必须保持简洁、聚焦、高效，避免信息过载和认知负荷。
| 约束项 | 限制 | 理由 |
|--------|------|------|
| **主体长度** | ≤ 500 行 | 控制上下文窗口占用，确保 AI 能完整理解 |
| **Frontmatter 字段** | name ≤ 64 字符<br>description ≤ 1024 字符 | 符合 Agent Skills 开放标准，避免触发失败 |
| **Token 预算** | ≤ 5,000 tokens（约 500 行） | 确保技能加载时不会占用过多上下文 |
| **引用层级** | 仅一层深度 | 避免 SKILL.md → advanced.md → details.md 的深层嵌套 |
| **冗余内容** | 版本历史移至 CHANGELOG.md<br>宣传性内容移至 README.md | 保持 SKILL.md 聚焦功能规范，减少噪声 |
**实践要点**：
- ❌ 避免：在 SKILL.md 中添加"版本历史"章节
- ❌ 避免：用多层引用分散内容（应保持扁平化或集中到 references/）
- ❌ 避免：添加宣传性标记（如"新增"、"v2.x.0 新增"）
- ✅ 推荐：当 SKILL.md 接近 500 行时，主动拆分详细内容到 references/
- ✅ 推荐：使用 Progressive Disclosure 策略——核心逻辑在 SKILL.md，细节在 references/
**与用户私有指令的一致性**：
本项目遵循 `/Users/bensz/.claude/CLAUDE.md` 中定义的"文档编写设计哲学"：
- 移除版本标记和宣传性内容，聚焦功能本身
- 标题不使用序号前缀（用 `##` 而非 `## 1)`）
- CHANGELOG.md 作为唯一版本真理来源
## 技能版本号管理规范
**核心原则**：所有技能的版本号统一通过 config.yaml 管理（Single Source of Truth），确保版本信息的一致性和可追溯性。
### 技能配置文件结构
每个技能的 `config.yaml` 应包含以下结构：
```yaml
# 技能基本信息
skill_info:
name: skill-name # 技能名称（与 SKILL.md 的 name 字段一致）
version: 1.0.0 # 版本号（遵循语义化版本规范）
description: "技能简短描述" # 与 SKILL.md 的 description 保持一致
category: "技能分类" # 如：数据处理、文档生成、测试等
# 可配置参数
# ... 其他配置项 ...
```
### 版本号命名规则
遵循 [语义化版本](https://semver.org/lang/zh-CN/) 规范：
| 版本类型 | 格式 | 使用场景 |
|---------|------|----------|
| **稳定版** | `v1.0.0` 及以上 | 技能已稳定可用 |
| **开发中** | `v0.x.x` | 功能开发中，可能有较大变更 |
| **实验性** | `v0.0.x` | 早期实验阶段，API 不稳定 |
版本号格式：`主版本号.次版本号.修订号`
- **主版本号**：不兼容的 API 修改
- **次版本号**：向下兼容的功能性新增
- **修订号**：向下兼容的问题修正
### 版本同步机制
**核心规则**：版本号仅在 `config.yaml` 中记录（Single Source of Truth），其他任何地方**不得直接记录版本号**，只能通过引用 config.yaml 获取。
| 文件 | 版本号处理方式 | 说明 |
|------|--------------|------|
| **config.yaml** | **唯一记录处** | 版本号的唯一来源，遵循语义化版本规范 |
| **SKILL.md** | ❌ **禁止直接记录** | 不得在 YAML frontmatter 或正文中直接记录版本号 |
| **README.md** | 仅引用 | 在文档中说明"版本号见 config.yaml:skill_info.version" |
| **CHANGELOG.md** | 仅引用 | 在版本条目标题中使用，但本质是记录变更历史，非版本号存储 |
**实践要点**：
- ❌ **禁止**：在 SKILL.md 的 YAML frontmatter 中添加 `metadata.version` 字段
- ❌ **禁止**：在 SKILL.md 正文中直接写明"当前版本：v1.0.0"
- ❌ **禁止**：在 README.md 中硬编码版本号（如"最新版本 v1.0.0"）
- ✅ **推荐**：在 README.md 中写明"版本信息见 config.yaml:skill_info.version"
- ✅ **推荐**：使用脚本或构建工具动态读取 config.yaml 中的版本号（如需要）
### 新建技能时的版本号初始化
创建新技能时：
1. **初始化 config.yaml**，设置版本为 `v0.1.0`（开发中版本）
2. **在 CHANGELOG.md 添加初始版本**：
```markdown
## [0.1.0] - YYYY-MM-DD
### Added（新增）
- 初始化技能，实现核心功能
```
### 版本号更新时机
| 变更类型 | 版本更新示例 | 说明 |
|---------|-------------|------|
| Bug 修复 | `1.0.0` → `1.0.1` | 修复问题，不改变功能 |
| 新增功能 | `1.0.0` → `1.1.0` | 向下兼容的新功能 |
| 破坏性变更 | `1.0.0` → `2.0.0` | 不兼容的 API 变更 |
**实践要点**：
- 每次更新技能时，首先评估变更类型
- 根据变更类型更新 config.yaml 中的版本号
- 立即在 CHANGELOG.md 中记录变更内容
- ❌ 不要在其他文件中记录或同步版本号（保持 config.yaml 为唯一来源）
### 版本号检查命令
快速检查技能版本号：
```bash
# 查看 config.yaml 中的版本号
grep -A 3 "skill_info:" {skill_name}/config.yaml | grep "version"
# 检查所有技能的版本号
find . -name "config.yaml" -exec grep -l "skill_info" {} \; | while read f; do echo "$f:"; grep -A 3 "skill_info" "$f" | grep "version"; done
```
### 与有机更新原则的集成
版本号管理是**有机整体更新**的一部分：
- **理解意图**：版本变更的目的是什么？（修复/增强/重构）
- **定位生态位**：变更属于哪个版本类型？（修订/次版本/主版本）
- **协调生长**：版本号更新后，同步更新 CHANGELOG.md 和相关文档
- **记录变更**：在 CHANGELOG.md 中详细记录每个版本的具体变更
## 变更边界
- 只修改 `pipelines/skills/` 内文件，除非用户明确授权扩展到其它目录
- 不批量重写与当前任务无关的文档与结构；保持最小可用、可迭代
- 修改技能时，优先优化而非重写，保留用户自定义内容
## 变更记录规范
**重要原则**：凡是项目的更新，都要统一在 `CHANGELOG.md` 文件里记录。
### 记录范围
每次修改以下内容时，必须更新 [CHANGELOG.md](CHANGELOG.md)：
- **项目指令文件**：[CLAUDE.md](CLAUDE.md)、[AGENTS.md](AGENTS.md) 的任何修改
- **技能核心文件**：SKILL.md、config.yaml 的修改
- **项目结构变更**：新增/删除/重命名目录或关键文件
- **工作流变更**：核心工作流程的调整
- **工程原则变更**：新增、修改或删除工程原则
- **重要配置变更**：影响项目行为的配置文件修改
### 记录格式
遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 格式：
```markdown
## [版本号] - YYYY-MM-DD
### Added（新增）
- 新增了 XXX 功能/章节：用途是 YYY
### Changed（变更）
- 修改了 XXX 章节：原因是 YYY，具体变更内容是 ZZZ
### Fixed（修复）
- 修复了 XXX 问题：表现是 YYY，修复方式是 ZZZ
```
### 记录时机
- **修改前**：先在 [CHANGELOG.md](CHANGELOG.md) 的 `[Unreleased]` 部分草拟变更内容
- **修改后**：完善变更描述，添加具体细节和影响范围
- **发布时**：将 `[Unreleased]` 内容移至具体版本号下
## 技能加载路径
Claude Code 从以下路径加载技能（按优先级）：
1. **项目级技能**：`{项目根目录}/.claude/skills/`
2. **用户级技能**：`~/.claude/skills/`
## 与 AGENTS.md 的关系
- **[AGENTS.md](AGENTS.md)**：OpenAI Codex CLI 项目指令（主文件）
- **[CLAUDE.md](CLAUDE.md)**：基于 AGENTS.md 适配的 Claude Code 版本（本文件）
- 两个文件的核心内容保持一致，仅平台特定说明有差异
**同步机制**：
- 运行 `python3 init-project/scripts/generate.py --sync-from agents` 从 AGENTS.md 同步到 CLAUDE.md
- 运行 `python3 init-project/scripts/generate.py --check-consistency` 检查一致性
---
**提示**：修改本文档后，请立即在 [CHANGELOG.md](CHANGELOG.md) 中记录变更。这是项目管理的强制性要求，不是可选项。