skill-design-lineage

主机：Codex CLI — 此技能专为 Claude Code 设计，并适配了 Codex。 交叉引用命令在 Codex 中使用已安装的技能名称，而不是 /octo:* 斜杠命令。 使用当前 Codex shell 和子 Agent 工具。除非当前会话已提供相应能力，否则不要声称有可用的服务提供方、模型或宿主子 Agent。 宿主工具的对应项请参阅 skills/blocks/codex-host-adapter.md。

设计文档沿革

当设计引入或更改领域术语时，加载 skills/blocks/domain-modeling.md。在现有设计沿革产物中记录每项定义及其证据来源、 核查时间和范围。定义一旦更改，依赖它的决策即失效。应链接并重新审视这些决策，而不是将过时的实现指导继续标记为当前有效。

概述

通过分支跟踪、修订链和跨会话可发现性，持久保存头脑风暴和规划会话中的设计文档。设计文档创建后不可变——新修订会取代先前版本，而不是原地编辑。

存储位置

所有设计文档都存储在以下位置：

~/.claude-octopus/designs/<project-slug>/

项目 slug 根据当前 Git 仓库名称或工作目录的基本名称生成：

SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
DESIGNS_DIR="${HOME}/.claude-octopus/designs/${SLUG}"
mkdir -p "$DESIGNS_DIR"

文件名格式

设计文档遵循严格的命名约定：

{user}-{branch}-design-{datetime}.md

其中：

• {user} —— 当前操作系统用户名（$USER 或 whoami）
• {branch} —— 当前 Git 分支，经清理后使用（将斜杠替换为短横线）
• {datetime} —— ISO 8601 紧凑时间戳（YYYYMMDD-HHmmss）

示例：

chris-feature-auth-refactor-design-20260321-143022.md

解析：

BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo "no-branch")
DATETIME=$(date -u +"%Y%m%d-%H%M%S")
FILENAME="${USER}-${BRANCH}-design-${DATETIME}.md"

设计文档模板

每份设计文档都包含 YAML 前置元数据，后接结构化章节。

前置元数据

branch: feature/auth-refactor
user: chris
created: 2026-03-21T14:30:22Z
supersedes: chris-feature-auth-refactor-design-20260320-091500.md

字段：

• branch —— 创建时所在的 Git 分支
• user —— 创建文档的操作系统用户名
• created —— 创建时间的 ISO 8601 时间戳
• supersedes —— 此修订所替代的先前设计文档文件名（如果这是该分支的首份设计，则省略）

文档章节

# Design: [Title]

## Problem Statement
[What problem does this design solve? Why does it matter?]

## Constraints
[Technical, timeline, resource, or organizational constraints that bound the solution space.]

## Approaches Considered
[List each approach evaluated, with brief pros/cons for each.]

### Approach A: [Name]
- **Pros:** ...
- **Cons:** ...

### Approach B: [Name]
- **Pros:** ...
- **Cons:** ...

## Recommendation
[Which approach is recommended and why. Include the key trade-off that drove the decision.]

## Open Questions
[Unresolved questions that may affect implementation or require follow-up.]

第 1 步：保存设计

头脑风暴、规划或 define 工作流生成设计内容后，使用元数据将其保存到标准位置。

SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
DESIGNS_DIR="${HOME}/.claude-octopus/designs/${SLUG}"
mkdir -p "$DESIGNS_DIR"

BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo "no-branch")
DATETIME=$(date -u +"%Y%m%d-%H%M%S")
FILENAME="${USER}-${BRANCH}-design-${DATETIME}.md"
FILEPATH="${DESIGNS_DIR}/${FILENAME}"

cat > "$FILEPATH" <<EOF
branch: $(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "no-branch")
user: ${USER}
created: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
${SUPERSEDES:+supersedes: ${SUPERSEDES}}

# Design: [Title]

## Problem Statement
[Content from brainstorm/planning session]

## Constraints
[Identified constraints]

## Approaches Considered
[Evaluated approaches]

## Recommendation
[Selected approach and rationale]

## Open Questions
[Unresolved items]
EOF

设计文档创建后只读。如需修订设计，请创建新文档，并通过 supersedes 引用先前版本。

第 2 步：发现先前设计

撰写新设计之前，使用关键词匹配搜索相关的先前设计。

SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
DESIGNS_DIR="${HOME}/.claude-octopus/designs/${SLUG}"

# Search for designs matching keywords (case-insensitive)
KEYWORDS="auth refactor"
grep -li "$KEYWORDS" "${DESIGNS_DIR}"/*.md 2>/dev/null | head -10

限制：

• 关键词搜索最多返回 10 个结果，以免上下文过载
• 通过 grep -li 执行不区分大小写的搜索
• 仅在当前项目 slug 的目录中搜索

找到先前设计后，将其呈现给用户：

Found 2 prior designs related to "auth refactor":
  1. chris-feature-auth-refactor-design-20260320-091500.md (2026-03-20)
  2. chris-main-design-20260315-140000.md (2026-03-15)

Would you like to review any of these before creating a new design?

第 3 步：链接修订链

如果同一分支存在先前设计，新设计文档的前置元数据中应包含 supersedes 字段，并指向先前文件名。

BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo "no-branch")

# Find the most recent design for this branch
PRIOR=$(ls -t "${DESIGNS_DIR}"/*-${BRANCH}-design-*.md 2>/dev/null | head -1)

if [[ -n "$PRIOR" ]]; then
  SUPERSEDES=$(basename "$PRIOR")
fi

这样就形成了相互链接的修订链：

v3 (supersedes: v2) -> v2 (supersedes: v1) -> v1 (no supersedes)

要遍历某个分支的完整修订历史：

current="$FILENAME"
while [[ -n "$current" ]]; do
  echo "$current"
  current=$(grep '^supersedes:' "${DESIGNS_DIR}/${current}" 2>/dev/null | sed 's/supersedes: *//' || true)
done

第 4 步：跨会话发现

下游命令（deliver、review、develop）会在开始工作前检查 designs 目录，自动发现设计上下文。

SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
DESIGNS_DIR="${HOME}/.claude-octopus/designs/${SLUG}"
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo "no-branch")

# Find designs for current branch
BRANCH_DESIGNS=$(ls -t "${DESIGNS_DIR}"/*-${BRANCH}-design-*.md 2>/dev/null | head -3)

if [[ -n "$BRANCH_DESIGNS" ]]; then
  echo "Design context found for branch ${BRANCH}:"
  for design in $BRANCH_DESIGNS; do
    echo "  - $(basename "$design")"
  done
  # Read the most recent design for context
  LATEST_DESIGN=$(echo "$BRANCH_DESIGNS" | head -1)
  DESIGN_CONTEXT=$(<"$LATEST_DESIGN")
fi

下游技能应在开始工作前检查设计：

• flow-discover：检查现有设计，避免重复研究
• flow-define：将先前设计的约束纳入需求
• flow-develop：从最新设计中读取建议方案
• skill-brainstorm：将先前设计作为初始上下文呈现

上限和限制

• 每个项目 slug 最多 50 份设计文档——达到上限时，警告用户并建议归档旧设计
• 关键词搜索最多返回 10 个结果——避免上下文过载
• 设计文档模板最多 500 行——鼓励编写简洁且可执行的设计

上限执行：

DOC_COUNT=$(ls "${DESIGNS_DIR}"/*.md 2>/dev/null | wc -l | tr -d ' ')
if [[ "$DOC_COUNT" -ge 50 ]]; then
  echo "Warning: ${DOC_COUNT} design docs in ${DESIGNS_DIR}. Consider archiving old designs."
fi

集成说明

协同工具

• flow-discover —— 设计文档记录研究结果，以便持久保存
• flow-define —— 设计约束为需求定义提供依据
• skill-brainstorm —— 可将头脑风暴结果保存为设计文档
• skill-thought-partner —— 探索会话可生成设计成果

下游发现

• flow-develop —— 实施前读取最新设计
• flow-deliver —— 审查时参考设计决策
• skill-code-review —— 检查实施是否符合设计建议

不可变规则

设计文档创建后为只读。如需更新设计：

1. 创建一份新的设计文档
2. 将 supersedes 设为先前文档的文件名
3. 先前文档保持不变，作为审计记录

这样可以始终保留完整的设计演进历史。