skill-design-lineage

ホスト：Codex CLI — このスキルは Claude Code 向けに設計され、Codex 用に適応されています。 相互参照コマンドでは、/octo:* スラッシュコマンドではなく、Codex でインストール済みのスキル名を使用します。 現在の Codex シェルとサブエージェントツールを使用してください。現在のセッションで利用可能であることが確認されるまでは、プロバイダー、モデル、ホストのサブエージェントが利用可能だと断言しないでください。 ホストツールの同等機能については、skills/blocks/codex-host-adapter.md を参照してください。

設計ドキュメントの系譜

設計でドメイン用語を導入または変更する場合は、 skills/blocks/domain-modeling.md を読み込んでください。各定義を、その根拠となる情報源、確認日時、適用範囲とともに、既存の設計系譜アーティファクトに記録します。定義が変更された場合、それに依存する判断は無効になります。古い実装ガイダンスを最新のものとして残さず、関連付けて再確認してください。

概要

ブランチ追跡、改訂履歴、セッションをまたいだ検索性を備えた設計ドキュメントを、ブレインストーミングや計画セッションから永続化します。設計ドキュメントは作成後に変更できません。直接編集するのではなく、新しい改訂版で以前のバージョンを置き換えます。

保存場所

すべての設計ドキュメントは、次の場所に保存されます。

~/.claude-octopus/designs/<project-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} — 現在の OS ユーザー名（$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 — ドキュメントを作成した OS ユーザー名
• 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：設計を保存する

ブレインストーミング、計画、または定義のワークフローで設計が作成されたら、メタデータを付けて標準の場所に保存します。

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 による大文字と小文字を区別しない検索です
• 現在のプロジェクトスラッグのディレクトリ内のみを検索します

以前の設計が見つかった場合は、ユーザーに提示します。

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：以前の設計を出発点となるコンテキストとして提示します

上限と制限

• プロジェクトスラッグごとに設計ドキュメントは最大 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. 以前のドキュメントは監査証跡として変更せずに残します

これにより、設計の変遷を完全な履歴としていつでも確認できます。