zhukang/content-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
content-forge/CLAUDE.md

559 lines
26 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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<br/>新建] --> 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<br/>硬依赖]
AUTO --> BIMG[baoyu-image-gen<br/>备选]
PTW[post-to-wechat] --> M2H[baoyu-markdown-to-html<br/>硬依赖]
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 路径：`<PROJECT_ROOT>/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
<VAULT_ROOT>/
├── 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-<slug>.md`
- 资产目录：`05-assets/<slug>/...`
- 一个内容单元（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-<slug>.md"` |
| S1 外链采集（可选） | 输入：URL；输出：Markdown 摘要并入 topic | `url-to-markdown` | `obsidian read path="01-topics/2026-03-01-<slug>.md"` |
| S2 草稿生成 | 输入：topic；输出：`02-drafts/*.md` | `write-article` | `obsidian create path="02-drafts/2026-03-01-<slug>.md"` |
| S3 状态标记 | 输入：draft；输出：frontmatter 完整化 | `write-article` | `obsidian property:set path="02-drafts/2026-03-01-<slug>.md" name="status" value="draft"` |
| S4 格式清洗 | 输入：draft；输出：发布友好 Markdown | `format-markdown` | `obsidian read path="02-drafts/2026-03-01-<slug>.md"` |
| S5 视觉资产生成 | 输入：final markdown；输出：`05-assets/<slug>/...` | `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-<slug>.md" name="assets" value='["05-assets/<slug>/cover.png"]'` |
| S6 审核入列 | 输入：draft+assets；输出：`03-review/*.md` | `/review` 命令 + `/multi-review` + `/challenge` | `obsidian move path="02-drafts/2026-03-01-<slug>.md" to="03-review"` |
| S6.1 四维审核 | 输入：review 稿；输出：`review_status: passed/failed` | 结构审+事实审+文风审+格式审 | `obsidian property:set path="03-review/2026-03-01-<slug>.md" name="review_status" value="passed"` |
| S6.2 revision 闭环 | 输入：failed 稿；输出：修复后重审 | revision_count ≤ 3，超限进 blocked | `obsidian property:set path="03-review/2026-03-01-<slug>.md" name="status" value="revision"` |
| S7 润色优化 | 输入：passed 稿；输出：`polish_status: done/skipped` | 文风统一、可读性提升、SEO 优化 | `obsidian property:set path="03-review/2026-03-01-<slug>.md" name="polish_status" value="done"` |
| S8 发布微信 | 输入：polished 稿；输出：公众号文章 | `post-to-wechat`（依赖 `baoyu-markdown-to-html`） | `obsidian property:set path="03-review/2026-03-01-<slug>.md" name="channels" value='["wechat","x"]'` |
| S9 发布 X | 输入：polished 稿；输出：X 帖子 | `post-to-x` | `obsidian property:set path="03-review/2026-03-01-<slug>.md" name="status" value="published"` |
| S10 发布归档 | 输入：发布结果；输出：`04-published/*.md` | 发布后归档流程 | `obsidian move path="03-review/2026-03-01-<slug>.md" to="04-published"` |
### 5.1 常用命令速查
```bash
# 选题
obsidian create path="01-topics/YYYY-MM-DD-<slug>.md" content="<MARKDOWN>"
obsidian read path="01-topics/YYYY-MM-DD-<slug>.md"
# 草稿
obsidian create path="02-drafts/YYYY-MM-DD-<slug>.md" content="<MARKDOWN>"
obsidian property:set path="02-drafts/YYYY-MM-DD-<slug>.md" name="status" value="draft"
# 阶段流转
obsidian move path="02-drafts/YYYY-MM-DD-<slug>.md" to="03-review"
obsidian move path="03-review/YYYY-MM-DD-<slug>.md" to="04-published"
# 查找
obsidian search query="<slug>"
# 资产关联
obsidian property:set path="<path>" name="assets" value='["05-assets/<slug>/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="<slug>"` 找到 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="<slug>"` | 先 `obsidian create` 再 `obsidian read` |
| `obsidian property:set` 不生效 | frontmatter 块损坏或 name 拼写错误 | `obsidian read path="<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 行为准则已融入，审稿润色流程已定义，设计原则体系已建立
Reference in New Issue View Git Blame Copy Permalink