# content-forge / CLAUDE.md
## 1) 项目定位
`content-forge` 是一个「以 Obsidian Vault 为单一内容源」的自媒体内容生产编排项目，目标是把选题、写作、配图、格式化、发布变成可重复执行的流水线。
黄金法则：**Agents Read, Humans Write** — Agent 只读取 Vault，永远不写入。Vault 只包含人类的思考，Agent 的输出走 CLI 命令或终端，不污染知识源。
核心边界：
- 只新增一个本地 skill：`write-article`（文章生成）。
- 其余能力优先复用现有 `baoyu-*`、`image-gen-orchestrator`、`basic-image-gen`、`social-media-pipeline`。
- 所有中间产物必须落到 Vault，禁止在多个系统维护平行真相。
成功标准：
- 可以从 `01-topics` 的选题笔记自动产出 `02-drafts` 草稿。
- 可以把草稿格式化并生成配图资产，再发布到微信/X。
- 全链路状态通过 frontmatter 字段可追踪。
### 1.1 Quick Start
```bash
# 1. 初始化 Vault（创建目录 + 注册到 Obsidian）
bash scripts/init-vault.sh
# 2. 验证环境
command -v obsidian # CLI 可用
obsidian vault # Vault 已注册
obsidian search query="templates" # 模板可搜索
# 3. 创建第一个选题
obsidian create path="01-topics/2026-03-02-my-first-topic.md" content="---
title: 我的第一个选题
slug: my-first-topic
status: topic
content_type: article
---
# 选题内容"
# 4. 用 write-article skill 生成草稿
# 在 Claude Code 中执行：/write-article
```
### 1.2 项目文件结构
```text
content-forge/
├── CLAUDE.md # 项目规范（本文件）
├── my-commands.md # 自定义命令文档
├── .gitignore # 排除 content-forge/ (vault 有独立仓库)
├── scripts/
│ ├── init-vault.sh # Vault 初始化脚本
│ └── vault-sync.sh # Vault 自动同步到 Gitea
├── .claude/
│ ├── commands/ # 自定义 slash 命令
│ │ ├── my-world.md # /my-world — 一键加载 vault 上下文
│ │ ├── emerge.md # /emerge — 发现隐藏模式
│ │ ├── challenge.md # /challenge — 压力测试信念
│ │ └── connect.md # /connect — 跨领域桥接
│ └── skills/
│ ├── write-article/ # 从 Vault 选题生成文章
│ │ ├── SKILL.md # skill 定义与工作流
│ │ └── references/
│ │ └── writing-styles.md # 4 种写作风格规范
│ └── my-world/ # 一键加载 vault 上下文（skill 版）
│ └── SKILL.md
└── content-forge/ # Obsidian Vault（内容存储）
├── 00-inbox/ # 临时灵感、原始素材
├── 01-topics/ # 结构化选题
├── 02-drafts/ # 初稿/改稿
├── 03-review/ # 待审核稿
├── 04-published/ # 已发布归档
├── 05-assets/ # 配图、封面等资产
├── 06-archived/ # 废弃/放弃的内容
├── 07-leads/ # Lead magnets, newsletter content
├── 08-events/ # Webinars, launches, selling events
├── 09-viral-examples/ # 爆款案例库（选题灵感/风格学习/热点追踪/竞品分析）
└── templates/ # article / tech-blog / social-post
```
---
## 2) 完整依赖关系图
### 2.1 技能依赖图（必读）
```mermaid
graph TD
WA[write-article
新建] --> OBS[obsidian:obsidian-cli]
BAI[baoyu-article-illustrator] --> AUTO[image gen skill auto-discover]
BCI[baoyu-cover-image] --> AUTO
BXI[baoyu-xhs-images] --> AUTO
BINF[baoyu-infographic] --> AUTO
AUTO --> IGO[image-gen-orchestrator]
IGO --> BIG[basic-image-gen
硬依赖]
AUTO --> BIMG[baoyu-image-gen
备选]
PTW[post-to-wechat] --> M2H[baoyu-markdown-to-html
硬依赖]
PTW --> CDP[Chrome CDP 发布链路]
PTW --> WXA[WeChat API 发布链路]
PTX[post-to-x] --> XCDP[Chrome CDP + X 登录态]
UTM[url-to-markdown] --> UCDP[Chrome CDP]
FMD[format-markdown] --> REMARK[remark + remark-cjk-friendly]
SMP[social-media-pipeline] --> NONE[无 skill 运行时依赖]
```
### 2.2 生产链路图（执行顺序）
```text
social-media-pipeline
-> url-to-markdown（可选：采集外部素材）
-> write-article
-> format-markdown
-> baoyu-cover-image / baoyu-article-illustrator / baoyu-xhs-images / baoyu-infographic
-> image-gen-orchestrator -> basic-image-gen
-> post-to-wechat
-> post-to-x
```
---
## 3) 必需插件 / API 清单
### 3.1 插件与本地技能
| 类型 | 名称 | 作用 | 必要性 | 最小验证 |
|---|---|---|---|---|
| 插件 | `obsidian` | 提供 `obsidian-cli`（Vault 读写） | 必需 | `obs vault` |
| 插件包 | `ai-generation-skills` 或 `content-skills` | 提供 `baoyu-*` 系列技能 | 必需 | 在技能列表可见对应 skill |
| 本地 skill | `basic-image-gen` | 图片生成底层能力 | 必需 | 能被 `image-gen-orchestrator` 调用 |
| 本地 skill | `image-gen-orchestrator` | 批量图片编排 | 必需 | 触发图像任务成功返回 |
| 本地 skill | `social-media-pipeline` | 选题/模板/日历方法论 | 建议启用 | 能输出结构化选题与日历 |
| 本地 skill | `write-article` | 从 Vault 选题生成文章 | 必需（本项目唯一新增） | 生成 `02-drafts/*.md` |
| 本地 skill | `my-world` | 一键加载 vault 上下文 | 建议启用 | `/my-world` 输出 vault 摘要 |
| 社区插件 | `dataview` (v0.5.68) | Vault 当数据库查询 | 建议启用 | Obsidian 设置中已启用 |
| 社区插件 | `templater-obsidian` | 高级模板引擎 | 建议启用 | Obsidian 设置中已启用 |
| 社区插件 | `note-to-mp` | 笔记转微信公众号格式 | 建议启用 | Obsidian 设置中已启用 |
### 3.2 外部依赖与环境变量
| 类别 | 项 | 用途 | 关键配置 |
|---|---|---|---|
| 浏览器 | Google Chrome | CDP 抓取与发布（url-to-markdown / post-to-wechat / post-to-x） | 本机可启动 Chrome |
| 图像 API | OpenAI / Google / DashScope 任一 | `basic-image-gen` 推理 | `OPENAI_API_KEY` 或 `GOOGLE_API_KEY` 或 `DASHSCOPE_API_KEY` |
| 微信发布 | WeChat API（API 模式） | 公众号发布 | `WECHAT_APP_ID`, `WECHAT_APP_SECRET` |
| 微信/X 发布 | 浏览器登录态（CDP 模式） | 无 API 时发布兜底 | 本地已登录对应账号 |
| 配置文档 | `EXTEND.md`（各 skill） | 首次配置入口 | 按 skill 文档逐项完成 |
---
## 4) Vault 目录约定与 frontmatter 规范
### 4.1 目录约定（固定）
默认 Vault 路径：`/content-forge/`（通过 `scripts/init-vault.sh` 初始化，可用 `VAULT_PATH` 环境变量覆盖）。
**关键操作约束**：Obsidian CLI 的 `vault=` 参数存在已知 bug（静默失效），**必须先 `cd` 到 vault 目录内再执行 CLI 命令**，CLI 会自动检测当前目录所属的 vault：
```bash
cd /home/kang/apps/content-forge/content-forge
obsidian vault # 正确识别 content-forge vault
obsidian orphans # 在 vault 目录内执行才有效
```
```text
/
├── 00-inbox/ # 临时灵感、原始素材、待分类
├── 01-topics/ # 结构化选题（write-article 输入）
├── 02-drafts/ # 初稿/改稿（format-markdown 输入）
├── 03-review/ # 待审核稿（人工或规则审校）
├── 04-published/ # 已发布内容归档
├── 05-assets/ # 配图、封面、信息图等资产
├── 06-archived/ # 废弃/放弃的内容
├── 07-leads/ # Lead magnets, newsletter content
├── 08-events/ # Webinars, launches, selling events
├── 09-viral-examples/ # 爆款案例库（选题灵感/风格学习/热点追踪/竞品分析）
└── templates/ # 模板（article / tech-blog / social-post）
```
命名规则：
- 文件名：`YYYY-MM-DD-.md`
- 资产目录：`05-assets//...`
- 一个内容单元（topic/draft/review/published）使用同一个 `slug`，避免多份身份。
### 4.2 frontmatter 统一规范
所有 `01-topics`、`02-drafts`、`03-review`、`04-published` 笔记必须包含以下字段：
```yaml
---
id: "2026-03-01-example-slug"
title: "示例标题"
slug: "example-slug"
status: "topic" # inbox | topic | draft | formatting | review | polish | publishing | published | revision | blocked | archived
content_type: "article" # article | thread | x-post | wechat-post | infographic
channels: ["wechat", "x"]
language: "zh-CN"
source_urls: []
assets: []
cover_image: ""
template: "article"
owner: "content-forge"
created_at: "2026-03-01T00:00:00+08:00"
updated_at: "2026-03-01T00:00:00+08:00"
published_at: null
# 周期时间追踪（可选）
cycle_days: null # 从创建到发布的总天数
stage_days: # 各阶段停留天数
inbox: 0
topic: 0
draft: 0
review: 0
total: 0
# 推广字段（可选，由 /promote 命令分析）
promotion_status: null # null | planned | promoting | converted | paused
promotion_channels: [] # ["newsletter", "webinar", "x-thread", "linkedin"]
holding_patterns: [] # ["email-list", "youtube", "podcast"]
conversion_type: null # null | "lead-magnet" | "webinar" | "product-sale"
repurposed_from: null # slug of original content
repurposed_to: [] # slugs of derivative content
evergreen: false # true if content can be re-promoted
# 审稿润色字段（可选，由 /review 命令管理）
review_status: null # null | pending | in_progress | passed | failed
review_issues: [] # [{id, category, severity, description, status}]
review_passed_at: null
polish_status: null # null | pending | skipped | done
polish_version: 0
polished_at: null
revision_count: 0
revision_history: [] # [{date, issues_fixed, notes}]
---
```
字段约束：
- `id` 与 `slug` 一一对应，禁止同 slug 多 id。
- `status` 只能按 `topic -> draft -> review -> published` 前进。
- `assets` 只存 Vault 相对路径（禁止外部临时路径）。
- `cycle_days` 在发布时自动计算：`published_at - created_at`。
- `stage_days` 由 `/today` 或 `/close` 命令更新。
### 4.3 各阶段退出标准
每个阶段必须满足以下条件才能前进到下一阶段：
| 阶段 | 必填字段 | 退出条件 |
|------|----------|----------|
| **inbox** | `title` | 有标题即可进入 topic |
| **topic** | `slug`, `source_urls` 或明确观点 | 有 slug + 明确写作角度 |
| **draft** | 完整正文 | 正文结构完整，有开头/主体/结尾 |
| **formatting** | `assets`, `cover_image` | 配图已生成，格式化完成 |
| **review** | `review_status: passed` | 四维审核通过（结构/事实/文风/格式），Critical=0, High≤1 |
| **polish** | `polish_status: done/skipped` | 润色完成或跳过润色 |
| **publishing** | `channels` | 渠道已确定，准备发布 |
| **published** | `published_at`, `published_url` | 已发布，记录发布时间和链接 |
**特殊情况**：
- **revision**：从 review/polish 回退，修复后返回 review；单篇 revision ≤ 3 次，超限自动进入 blocked
- **blocked**：等待外部输入或 revision 超限，解除后返回原阶段
- **archived**：废弃内容，不再前进
### 4.4 爆款案例 frontmatter 规范（09-viral-examples/）
爆款案例用于：选题灵感、风格学习、热点追踪、竞品分析。通过 wikilinks 关联到你的选题。
```yaml
---
id: "2026-03-05-xxx"
title: "原标题"
source_url: "https://..."
platform: "x" # x | wechat | xiaohongshu | douyin | bilibili | medium | other
author: "@someone"
author_url: "https://..."
published_at: "2026-03-01"
collected_at: "2026-03-05"
metrics:
likes: 12000
comments: 500
shares: 300
views: null # 可选，部分平台不公开
viral_score: null # 可选：综合评分（可自定义公式）
tags: ["productivity", "ai-tools"]
language: "zh-CN"
related_topics: # wikilink 关联到你的选题
- "[[01-topics/2026-03-01-my-topic|我的选题]]"
analysis: null # 可选：为什么火的拆解笔记
takeaways: [] # 可选：可复用的要点
---
```
正文结构建议：
```markdown
# 原文（或摘要）
[原文内容或核心观点摘要]
# 为什么火
[你的分析：时机、情绪、表达、平台特性等]
# 可复用点
- [要点1]
- [要点2]
# 关联选题
- [[01-topics/xxx|相关选题]]
```
---
## 5) 内容生产流水线（阶段 -> skill -> obs 命令）
> 说明：以下命令是编排约定，默认在已注册 Vault 环境执行。
| 阶段 | 输入/输出 | Skill | obs 命令（最小可执行） |
|---|---|---|---|
| S0 选题入库 | 输入：灵感/素材；输出：`01-topics/*.md` | `social-media-pipeline`（方法论） | `obsidian create path="01-topics/2026-03-01-.md"` |
| S1 外链采集（可选） | 输入：URL；输出：Markdown 摘要并入 topic | `url-to-markdown` | `obsidian read path="01-topics/2026-03-01-.md"` |
| S2 草稿生成 | 输入：topic；输出：`02-drafts/*.md` | `write-article` | `obsidian create path="02-drafts/2026-03-01-.md"` |
| S3 状态标记 | 输入：draft；输出：frontmatter 完整化 | `write-article` | `obsidian property:set path="02-drafts/2026-03-01-.md" name="status" value="draft"` |
| S4 格式清洗 | 输入：draft；输出：发布友好 Markdown | `format-markdown` | `obsidian read path="02-drafts/2026-03-01-.md"` |
| S5 视觉资产生成 | 输入：final markdown；输出：`05-assets//...` | `baoyu-cover-image` / `baoyu-article-illustrator` / `baoyu-xhs-images` / `baoyu-infographic` -> `image-gen-orchestrator` -> `basic-image-gen` | `obsidian property:set path="02-drafts/2026-03-01-.md" name="assets" value='["05-assets//cover.png"]'` |
| S6 审核入列 | 输入：draft+assets；输出：`03-review/*.md` | `/review` 命令 + `/multi-review` + `/challenge` | `obsidian move path="02-drafts/2026-03-01-.md" to="03-review"` |
| S6.1 四维审核 | 输入：review 稿；输出：`review_status: passed/failed` | 结构审+事实审+文风审+格式审 | `obsidian property:set path="03-review/2026-03-01-.md" name="review_status" value="passed"` |
| S6.2 revision 闭环 | 输入：failed 稿；输出：修复后重审 | revision_count ≤ 3，超限进 blocked | `obsidian property:set path="03-review/2026-03-01-.md" name="status" value="revision"` |
| S7 润色优化 | 输入：passed 稿；输出：`polish_status: done/skipped` | 文风统一、可读性提升、SEO 优化 | `obsidian property:set path="03-review/2026-03-01-.md" name="polish_status" value="done"` |
| S8 发布微信 | 输入：polished 稿；输出：公众号文章 | `post-to-wechat`（依赖 `baoyu-markdown-to-html`） | `obsidian property:set path="03-review/2026-03-01-.md" name="channels" value='["wechat","x"]'` |
| S9 发布 X | 输入：polished 稿；输出：X 帖子 | `post-to-x` | `obsidian property:set path="03-review/2026-03-01-.md" name="status" value="published"` |
| S10 发布归档 | 输入：发布结果；输出：`04-published/*.md` | 发布后归档流程 | `obsidian move path="03-review/2026-03-01-.md" to="04-published"` |
### 5.1 常用命令速查
```bash
# 选题
obsidian create path="01-topics/YYYY-MM-DD-.md" content=""
obsidian read path="01-topics/YYYY-MM-DD-.md"
# 草稿
obsidian create path="02-drafts/YYYY-MM-DD-.md" content=""
obsidian property:set path="02-drafts/YYYY-MM-DD-.md" name="status" value="draft"
# 阶段流转
obsidian move path="02-drafts/YYYY-MM-DD-.md" to="03-review"
obsidian move path="03-review/YYYY-MM-DD-.md" to="04-published"
# 查找
obsidian search query=""
# 资产关联
obsidian property:set path="" name="assets" value='["05-assets//cover.png"]'
```
### 5.2 端到端最小验证链路
```bash
obsidian vault
obsidian create path="01-topics/2026-03-01-demo.md" content="# Demo Topic"
obsidian read path="01-topics/2026-03-01-demo.md"
obsidian create path="02-drafts/2026-03-01-demo.md" content="# Demo Draft"
obsidian property:set path="02-drafts/2026-03-01-demo.md" name="status" value="draft"
obsidian search query="2026-03-01-demo"
```
---
## 6) Obsidian CLI 使用规范与故障排查
### 6.1 使用规范（强制）
1. **先 cd 再执行**：所有 CLI 命令必须在 `cd /home/kang/apps/content-forge/content-forge` 之后执行。
2. 所有写入必须使用 Vault 相对路径，禁止绝对路径。
3. 写入前先创建文件，再写 frontmatter 属性，避免属性写入到不存在文件。
4. 每次阶段切换都要更新 `status` 与 `updated_at`。
5. 资产路径统一写入 `assets` 数组，不在正文硬编码临时 URL。
6. 发布前必须能通过 `obsidian search query=""` 找到 topic/draft/review/published 至少一个节点。
### 6.1.1 NEVER 规则（踩坑编纂）
- **NEVER** 使用 `vault=` 参数 — 已知 bug，静默失效，总是 cd 到 vault 目录。
- **NEVER** 用 `find`/`ls`/`cat` 替代 CLI — `obsidian search`/`obsidian read` 效率高 70000 倍。
- **NEVER** 让 Agent 直接写入 Vault 笔记内容 — 黄金法则：Agents Read, Humans Write。通过 `obsidian create`/`obsidian property:set` 的结构化命令操作 frontmatter 和流水线状态是允许的。
- **NEVER** 在 Vault 中存放非内容文件（脚本、zip、临时文件） — Vault 只放 markdown 笔记和资产。
- **NEVER** 跳过 frontmatter — 每个 01-04 目录的文件必须有完整 frontmatter。
### 6.2 故障排查（按优先级）
| 症状 | 根因 | 诊断命令 | 处理动作 |
|---|---|---|---|
| `obsidian: command not found` | CLI 未安装或 PATH 未注入 | `command -v obsidian` | 按 obsidian-setup skill 安装 |
| `obsidian vault` 无输出或报错 | Vault 未注册 | `obsidian vault` | 运行 `scripts/init-vault.sh` 或手动注册 |
| `obsidian read` 失败 | 路径拼写或文件不存在 | `obsidian search query=""` | 先 `obsidian create` 再 `obsidian read` |
| `obsidian property:set` 不生效 | frontmatter 块损坏或 name 拼写错误 | `obsidian read path=""` | 修复 frontmatter 结构后重试 |
| `obsidian vault` 段错误（segfault） | `~/.local/bin/obsidian` 是 symlink 而非 wrapper，缺少 `DISPLAY` 注入 | `file ~/.local/bin/obsidian` 应显示 shell script | 重新部署 wrapper：见 `obsidian-setup` skill Step 2；wrapper 会自动注入 `DISPLAY=:42` |
| 配图 skill 调用失败 | `basic-image-gen` API key 缺失 | 检查环境变量 | 补齐 `OPENAI_API_KEY/GOOGLE_API_KEY/DASHSCOPE_API_KEY` |
| 微信/X 发布失败 | 登录态失效或接口凭证过期 | 检查浏览器登录态/API 凭证 | 重新登录或刷新凭证 |
### 6.3 运行前检查清单
```bash
command -v obsidian
obsidian vault
obsidian search query="templates"
```
通过后再执行流水线，避免中途失败回滚。
---
## 7) Git 仓库与数据同步
项目代码和 Vault 数据使用**独立仓库**管理：
| 仓库 | 地址 | 内容 | 同步方式 |
|---|---|---|---|
| `content-forge` | `http://gitea.towards-agi.cn/zhukang/content-forge.git` | CLAUDE.md、skills、scripts | 手动 commit + push |
| `content-forge-vault` | `http://gitea.towards-agi.cn/zhukang/content-forge-vault.git` | Vault 数据（选题、草稿、资产） | cron 每天凌晨 2 点自动 |
### 7.1 认证方式
- 使用 `git credential store`，token 统一存放在 `~/.git-credentials`（权限 600）。
- Token 更换时只需修改 `~/.git-credentials` 一个文件。
- Remote URL 中不含 token。
### 7.2 自动同步
`scripts/vault-sync.sh` 由 cron 每天执行，逻辑：有变更时 `git add -A && commit && push`，无变更时跳过。
```bash
# 查看 cron 配置
crontab -l | grep vault-sync
# 手动触发同步
bash scripts/vault-sync.sh
# 查看同步日志
tail -20 /tmp/vault-sync.log
```
### 7.3 其他设备 clone
```bash
git clone http://gitea.towards-agi.cn/zhukang/content-forge-vault.git
# 首次 push 时 credential store 会提示输入用户名和 token
```
---
## 8) 已知问题与限制（含 NEVER 规则踩坑记录）
| 问题 | 影响 | 状态 | 降级方案 |
|---|---|---|---|
| ~~`obsidian vault` segfault~~ | ~~无法通过 CLI 操作~~ | **已修复**（wrapper 脚本注入 DISPLAY） | — |
| `obsidian` CLI 与桌面客户端为独立进程 | 桌面端修改不会自动触发 CLI 事件 | 设计如此 | 以文件系统为准，CLI 和桌面端都会读取同一目录 |
| `vault=` 参数静默失效 | CLI 命令作用到错误 vault | **已确认** | 必须 `cd` 到 vault 目录内执行 CLI 命令 |
---
## 9) 自定义命令（`.claude/commands/`）
基于 Vin Obsidian Workflows 理念构建的思维工具，详见 `my-commands.md`。
| 命令 | 用途 | 使用时机 |
|------|------|----------|
| `/my-world` | 一键加载 vault 全量上下文 | 每次 session 开始 |
| `/emerge` | 从笔记中发现隐藏模式 | 周回顾、新增多篇笔记后 |
| `/challenge` | 用 vault 历史压力测试信念 | 发布前、重大决策前 |
| `/connect` | 跨领域桥接两个不相关主题 | 寻找新内容角度 |
待建：`/today`（晨间仪式）、`/close`（晚间仪式）。
---
## 10) Agent 行为准则
基于 `00-inbox/ai-agent-best-practices.md` 整理的执行纪律，与 Linus-Enhanced 输出风格互补。
### 1. Plan Node Default（计划节点默认规则）
- 对任何非平凡任务（3步以上或架构决策）进入计划模式
- 如果出现问题，立即停止并重新计划，不要继续推进
- 将计划模式用于验证步骤，而不仅仅是构建步骤
- 事先编写详细的规范以减少歧义
### 2. Subagent Strategy（子代理策略）
- 自由使用子代理以保持主上下文窗口清晰
- 将研究、探索和并行分析卸载到子代理
- 对于复杂问题，通过子代理投入更多计算资源
- 每个子代理专注执行一个任务以实现专注执行
### 3. Self-Improvement Loop（自我改进循环）
- 在用户进行任何修正后：按照模式更新 `tasks/lessons.md`
- 为自己编写防止犯同样错误的规则
- 严格迭代这些经验教训直到错误率下降
- 在会话开始时回顾相关项目的经验教训
### 4. Verification Before Done（完成前验证）
- **NEVER 在未证明其有效前，将任务标记为完成**
- 当相关时，比较主流程与更改的行为差异
- 自问："资深工程师会批准这个吗？"
- 运行测试、检查日志、证明正确性
### 5. Demand Elegance (Balanced)（追求优雅（平衡））
- 对于非平凡的更改：暂停并自问"是否有更优雅的方式？"
- 如果一个修复感觉是临时的："基于我现在知道的一切，实现优雅的解决方案"
- 对于简单、明显的修复则跳过此步骤——不要过度工程化
- 在展示工作前挑战自己的工作
### 6. Autonomous Bug Fixing（自动错误修复）
- 当收到错误报告时：**直接修复它，不要寻求手把手指导**
- 指出日志、错误、失败的测试——然后解决它们
- 不需要用户切换上下文
- 在未被告知如何操作的情况下修复失败的 CI 测试
### 任务管理
1. **先计划**：编写计划到 `tasks/todo.md`，包含可检查的项
2. **验证计划**：在开始实施前确认计划
3. **跟踪进度**：在推进过程中标记项为完成
4. **解释变更**：每个步骤的高层摘要
5. **记录结果**：在 `tasks/todo.md` 中添加审查部分
6. **捕捉经验**：在修正后更新 `tasks/lessons.md`
### 核心原则
- **简单优先**：让每次更改尽可能简单。影响最少的代码。
- **不偷懒**：找到根本原因。没有临时修复。符合资深开发者标准。
- **最小化影响**：更改应仅触及必要的内容。避免引入错误。
> 来源: `00-inbox/ai-agent-best-practices.md`
### 7. 三条设计原则（源自 Claudable System Prompt 分析）
**原则 A: 约束 > 能力**
- 定义 Agent 行为时，70% 精力花在"不做什么"（NEVER 清单），30% 花在"怎么做"
- 在内容生产中：write-article 的黑名单零容忍、frontmatter 字段约束、阶段退出标准——都是约束驱动设计
- 新增 skill/命令时，先写 NEVER 规则，再写执行步骤
**原则 B: 一次 inline，两次抽象**
- 一个选题角度/写作模板/配图风格只用过一次 → 不急着模板化，inline 即可
- 同一模式出现两次以上 → 提炼为 `templates/` 模板或 `references/` 规范
- 避免"预防性抽象"：不要为假想的复用场景提前建模板
**原则 C: Frontmatter-First（Content-First 的 Vault 实现）**
- 任何内容单元（选题/草稿/案例），先定义 frontmatter 结构，再填充正文
- frontmatter 是机器可读的契约层，正文是人类可读的内容层
- 新增内容类型时，先在 §4.2 定义 frontmatter 规范，再写正文模板
> 来源: `00-inbox/claudable-system-prompt.md` 道法术器分析（2026-03-05）
---
## 版本
- **CLAUDE.md 版本**：1.6.0
- **最后更新**：2026-03-05
- **变更**：新增三条设计原则（§10.7）——约束>能力、一次inline两次抽象、Frontmatter-First，源自 Claudable System Prompt 道法术器分析
- **项目阶段**：环境就绪，CLI 验证通过，双仓库同步已配置，思维工具命令已部署，Agent 行为准则已融入，审稿润色流程已定义，设计原则体系已建立