架构 · 难度：参考

工件与路径

全部 9 个工件目录、它们的文件命名约定，以及临时目录路径规则。

工件目录

以下所有路径都在 <root> 之下，<root> 由 .compound-engineering/config.yaml 中的 docs_root 解析得到（默认值：docs）。

目录所属技能文件命名约定
<root>/plans/ ce-brainstorm、ce-plan、ce-sweep YYYY-MM-DD-HHMM-<type>-<topic>-plan.{md,html}
Frontmatter：artifact_contract: ce-unified-plan/v1，product_contract_source: ce-brainstorm
<root>/solutions/ ce-compound、ce-compound-refresh 自由命名，需带 YAML frontmatter：title、date、category、module、problem_type、tags、last_updated
<root>/ideation/ ce-ideate 自由命名，通常为 .md
<root>/explainers/ ce-explain、ce-commit-push-pr YYYY-MM-DD-<concept-slug>.md
<root>/dogfood-reports/ ce-dogfood YYYY-MM-DD-<branch-slug>-dogfood.md
branch-slug = 分支名小写化后，非字母数字字符合并为单个 -
<root>/pulse-reports/ ce-product-pulse YYYY-MM-DD_HH-MM.md（30–40 行，单页）
<root>/feedback-sweep/ ce-sweep feedback-sweep-plan.md
<root>/handoffs/ ce-handoff 默认进入受管仓库；用户指定的路径优先。Frontmatter：ce-handoff/v1
<root>/personas/ ce-dogfood（仅读取） 由 Compound Packs 提供 personas 与 criteria

仓库根级的文件

文件所属用途
STRATEGY.mdce-strategy项目战略：产品是什么、服务谁、如何取胜、团队投入何处
CONCEPTS.mdce-compound-refresh领域词汇表（仅为术语表，非规范文档）

临时目录路径

每个 CE 技能都使用同一套临时根目录模式：

SCRATCH_ROOT="/tmp/compound-engineering-$(id -u)"
[ ! -L "$SCRATCH_ROOT" ] && (umask 077; mkdir -p "$SCRATCH_ROOT") 2>/dev/null \
  && [ ! -L "$SCRATCH_ROOT" ] && [ -O "$SCRATCH_ROOT" ] && [ -w "$SCRATCH_ROOT" ] \
  || SCRATCH_ROOT="${TMPDIR:-/tmp}/compound-engineering-$(id -u)"
反符号链接安全检查

如果 /tmp 中已存在同名符号链接指向其他用户的目录，将触发向 $TMPDIR 的回退。若仍失败（同样是符号链接或属主错误），技能中止。这避免了通过可预测缓存路径发起的提示注入攻击 —— 详见 docs/solutions/best-practices/predictable-tmp-cache-ownership-check.md。

原型工作区

ce-prototype 使用 .context/ 目录（仅当工件必须跨会话存活以便后续实现跟随时）：

# 默认
.context/compound-engineering/ce-prototype/<date>-<slug>/

# 回退（尽力持久化）
/tmp/compound-engineering-<uid>/ce-prototype/<date>-<slug>/

在创建前必须先以 git check-ignore -q 校验 .context/。若未被忽略，技能会询问是否将其加入 .gitignore 后再继续。

浏览器测试运行目录

ce-test-browser 与 ce-dogfood 将截图放入 OS 临时目录：

mktemp -d "${TMPDIR:-/tmp}/ce-dogfood-XXXXXX"

截图与瞬态工件仅在被嵌入 dogfood 报告时，才会复制回仓库。

按技能划分的运行目录

许多技能会在临时目录下创建各自本次运行的目录。模式如下：

RUN_DIR="$SCRATCH_ROOT/<skill-name>/$(date +%Y%m%d)-$(openssl rand -hex 3)"
(umask 077; mkdir -p "$RUN_DIR") || exit 1; chmod 700 "$RUN_DIR" || exit 1
echo "$RUN_DIR"

使用此模式的技能：ce-explain、ce-ideate、ce-optimize、ce-code-review、ce-bakeoff。

提交约定

ce-commit 始终遵循以下规则：