architect について
architectは、ナレッジシステムの健全性、運用上の摩擦、研究根拠を分析し、改善案を優先順位付けします。ファイルを変更する前に、ユーザーの明示的な承認を求めます。
主な機能
- 01健全性とドリフトの分析
- 02運用上の摩擦パターンの調査
- 03研究に基づく改善案
- 04変更前のユーザー承認
活用シーン
- 01繰り返すシステム課題の診断
- 02設定ドリフトの確認
- 03根拠ある改善策の優先順位付け
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/ / github.com/ agenticnotetaking/ arscontexta --skill architectインストール後、Claude Code で/architectを入力して読み込まれたか確認します。
同梱ファイルskill.json
詳細
実行時設定(ステップ 0 — 処理開始前)
ドメイン固有の動作を設定するため、次のファイルを読み込みます。
-
ops/derivation-manifest.md— 用語マッピング、プラットフォームのヒント- ノートフォルダー名には
vocabulary.notesを使用します - ノートの種類に関する参照には
vocabulary.note/vocabulary.note_pluralを使用します - MOC に関する参照には
vocabulary.topic_map/vocabulary.topic_map_pluralを使用します - 受信箱フォルダー名には
vocabulary.inboxを使用します - 接続を見つけるコマンド名には
vocabulary.cmd_reflectを使用します - 後方パスのコマンド名には
vocabulary.cmd_reweaveを使用します - 検証コマンド名には
vocabulary.cmd_verifyを使用します - 出力内のコマンド名には
vocabulary.architectを使用します
- ノートフォルダー名には
-
ops/config.yaml— 処理の深さ、パイプラインの連結、自動化の設定 -
ops/derivation.md— 元の派生記録(設計意図の基準)
これらのファイルが存在しない場合は、汎用の既定値を使用し、ユーザーに警告します。
今すぐ実行
対象:$ARGUMENTS
直ちに解析します。
- 対象に特定の領域(例:「schema」「processing」「MOC structure」)が指定されている場合:その領域に分析を集中させます
- 対象が空の場合:すべての観点を対象に、システム全体を分析します
- 対象が
--dry-runの場合:分析を実行しますが、実装は提案しません
次のフェーズを順番に実行します。
- システムファイルを特定し、プラットフォームを検出します
- 設計意図を把握するため、派生記録を読み込みます
- 健全性データを分析します(最近のレポートまたはライブチェック)
- 運用面全体から摩擦パターンをスキャンします
- 主張の根拠を具体的な調査結果に求めます
- 根拠のつながりをすべて示した、優先順位付きの提案を 3~5 件作成します
- ユーザーに提示し、承認を得てから実装します
今すぐ開始してください。 以下の説明で、7 フェーズのワークフローを定義します。
基本方針
直感よりも証拠を重視します。習慣よりも調査を重視します。
コンテキストファイル内のルールはすべて仮説でした。スキルのワークフローはすべて設計上の選択でした。仮説は、運用の実態に照らして検証する必要があります。このスキルは、健全性データ、摩擦パターン、調査に基づく主張という 3 つの証拠の流れを結び付け、具体的で実行可能な提案を作成します。
役立つかもしれないことを推測するのではありません。実際に起きていること(健全性+摩擦)を診断し、調査結果が示す、起きるべきことを処方します。すべての提案は、具体的な証拠にたどれる必要があります。「こうしたほうがよいと思います」は提案ではありません。「健全性データでは孤立ノートが 12 件確認され、摩擦ログには孤立に関する苦情が繰り返し記録され、調査による主張 [[孤立したノートはつながりのあるノートより早く劣化する]] が、条件に応じて実行する再編パスの追加を支持しています」——これが提案です。
メタ作業の予算は 25%: 60 分のセッションでは、システムの進化に費やす時間は最大 15 分です。提案の実装に 15 分を超える見込みがある場合は、「次回のセッションまで延期する」という提案にします。システムは作業を支えるものであり、その逆ではありません。
不変条件:Architect は決して自動実装しません。 ファイルを変更する前に、すべての提案についてユーザーの明示的な承認を得る必要があります。これにより、認知を外部委託してしまう失敗パターンを防ぎ、システムの進化に関する判断に人間が関与し続けるようにします。
PHASE 1: 特定
自動で実行されます。ユーザーによる操作は不要です。
プラットフォームを検出し、システムの主要なファイルを見つけます。
Check filesystem:
.claude/ directory exists -> platform = "claude-code"
Neither -> platform = "minimal"
以下のファイルを特定します(パスはドメインの用語によって異なります)。
| ファイルの種類 | 探すもの | 一般的な場所 |
|---|---|---|
| コンテキストファイル | システムの方法論とルール | CLAUDE.md, README.md |
| 自己スペース | エージェントのアイデンティティとメモリー | self/identity.md, self/methodology.md, self/goals.md |
| Ops ディレクトリ | 運用インフラストラクチャ | ops/derivation.md, ops/config.yaml, ops/sessions/, ops/observations/, ops/health/ |
| ノートディレクトリ | 主要なナレッジディレクトリ | {vocabulary.notes}/(ドメイン固有の名称の場合があります:reflections/, concepts/ など) |
| キューシステム | パイプラインの状態 | ops/queue/queue.yaml or ops/queue/queue.json |
| テンプレート | ノートのスキーマ | ops/templates/ or templates/ |
| 方法論 | 学習したパターン | ops/methodology/ |
ops/derivation.md が存在しない場合: ユーザーに警告します:「導出記録が見つかりません。設計上の決定に関する過去のコンテキストを考慮せず、現在の状態分析のみに基づいて推奨を行います。」
ops/config.yaml が存在しない場合: 次のように警告します:「設定ファイルが見つかりません。観察された動作から現在の設定を推測します。」
後続のフェーズで使用できるよう、すべてのファイルの場所を記録します。
PHASE 2: 導出記録を読む
ops/derivation.md を読み、システムの当初の設計意図を把握します。これは、ドリフトを測定する際の基準になります。
導出記録から抽出する項目:
| 要素 | 確認する内容 | 重要な理由 |
|---|---|---|
| 次元の位置 | 8 つの設定次元と、それぞれの導出値 | ドリフト検出の基準 |
| 会話のシグナル | 各選択を促したユーザーの発言 | 当初の意図の理解 |
| パーソナリティ | 温かさ、形式ばり具合、意見の強さ、感情への配慮 | 声の一貫性の確認 |
| 用語マッピング | 汎用語からドメイン用語への翻訳 | 出力でドメインの言葉を使う必要があります |
| 一貫性の検証 | 導出時に適用されていた制約 | 再確認すべき制約の把握 |
| 失敗モードのリスク | 高リスクと判定された失敗モード | これらの監視を優先 |
ops/config.yaml も読みます。これは、導出記録から乖離している可能性のある、現在の運用設定です。導出記録と設定の次元の位置を比較します。
For each of the 8 dimensions:
derivation_value = [from ops/derivation.md]
config_value = [from ops/config.yaml]
drifted = derivation_value != config_value
フェーズ 6 で使用するため、ドリフトを記録します。ドリフトは必ずしも悪いものではなく、健全な進化を示す場合があります。しかし、認識されていないドリフトは一貫性の欠如を招きます。
特定の注目領域が指定されている場合($ARGUMENTS)は、その領域に最も関連する次元と失敗モードを書き留め、後続のフェーズで優先的に確認します。
フェーズ 3:健全性分析
ops/health/ に最近の健全性レポートがあるか確認します。
# Find health reports from the last 7 days
find ops/health/ -name "*.md" -mtime -7 2>/dev/null | sort -r | head -1
最近のレポートがある場合: 全体を読みます。すべての FAIL 項目と WARN 項目を、構造化された証拠として抽出します。
For each FAIL/WARN:
category: [schema | orphan | link | description | stale | moc | boundary | throughput]
severity: [FAIL | WARN]
detail: [specific finding — which notes, which fields, which links]
count: [how many instances]
最近のレポートがない場合: ライブ健全性評価を実行します。各カテゴリを確認します。
| カテゴリ | 確認方法 | FAIL のしきい値 | WARN のしきい値 |
|---|---|---|---|
| スキーマ準拠 | grep -rL '^description:' {vocabulary.notes}/*.md | 該当なし | 必須フィールドが欠けているノートがある |
| 孤立ノートの検出 | 被リンクの Wiki リンクが 0 件のノート(すべてのノートから [[filename]] を検索) | 該当なし | 孤立ノートがある |
| リンクの健全性 | 存在しないファイルを指す Wiki リンク | リンク切れがある | 該当なし |
| 3 つのスペースの境界 | 誤ったスペースにあるコンテンツ(ops/ 内のノート、notes/ 内の運用ファイル) | 該当なし | 違反がある |
| 処理スループット | inbox 項目数とノート数を比較 | 比率が >3:1 | 比率が >2:1 |
| 古いノート | 被リンクが 2 件未満で、最終更新から 30 日以上経過したノート | 該当なし | ノートの >15% |
| MOC の整合性 | MOC ごとのノート数 | 該当なし | >40 件(分割候補)または <5 件(統合候補) |
| 説明の品質 | 情報を追加せずにタイトルを言い換えている説明 | 該当なし | 該当する説明がある |
ライブチェックの実装:
# Count total notes
NOTE_COUNT=$(ls -1 {vocabulary.notes}/*.md 2>/dev/null | wc -l | tr -d ' ')
# Find orphans (notes with no incoming links)
for f in {vocabulary.notes}/*.md; do
NAME=$(basename "$f" .md)
LINKS=$(grep -rl "\[\[$NAME\]\]" {vocabulary.notes}/ 2>/dev/null | wc -l | tr -d ' ')
[[ "$LINKS" -eq 0 ]] && echo "ORPHAN: $NAME"
done
# Find dangling links
grep -ohP '\[\[([^\]]+)\]\]' {vocabulary.notes}/*.md | sort -u | while read -r link; do
NAME=$(echo "$link" | sed 's/\[\[//;s/\]\]//')
[[ ! -f "{vocabulary.notes}/$NAME.md" ]] && echo "DANGLING: $NAME"
done
# Count inbox items
INBOX_COUNT=$(ls -1 {vocabulary.inbox}/ 2>/dev/null | wc -l | tr -d ' ')
# MOC sizes
grep -rl '^type: moc' {vocabulary.notes}/*.md 2>/dev/null | while read -r moc; do
COUNT=$(grep -c '^\- \[\[' "$moc" 2>/dev/null)
echo "MOC: $(basename "$moc" .md) = $COUNT notes"
done
# Missing descriptions
grep -rL '^description:' {vocabulary.notes}/*.md 2>/dev/null
すべての検出事項を、フェーズ 6 の証拠として記録します。各検出事項には、件数だけでなく、影響を受ける具体的なノート、リンク、またはフィールドを含める必要があります。
フェーズ 4:作業上の摩擦
複数の運用面にわたって、摩擦のパターンをスキャンします。摩擦とは、システムのあるべき動作と実際の動作の隔たりです。
4a. 観察ノート
# Find all pending observations
grep -rl '^status: pending' ops/observations/ 2>/dev/null
保留中の観察をそれぞれ読みます。種類ごとに分類します。
| カテゴリ | シグナル | 証拠としての価値 |
|---|---|---|
| 摩擦 | 「想定以上に難しかった」 | 高 — ワークフローの不一致を示します |
| プロセスの欠落 | 「X を行う方法がない」 | 高 — 機能の不足を示します |
| 想定外の挙動 | 「このような動作をするとは思わなかった」 | 中 — 期待との不一致を示します |
| 方法論 | 「X はこうするとよりうまくいくと分かった」 | 中 — 運用上の知見です |
| 品質 | 「出力の品質が不十分だった」 | 高 — 品質ゲートの失敗を示します |
カテゴリごとに発生数を数えます。同じカテゴリに 3 件以上ある場合は、調査する価値のある摩擦パターンです。
4b. 方法論ノート
# Read all methodology notes
ls ops/methodology/*.md 2>/dev/null
各方法論ノートを読みます。次の点を確認します。
- 複数のノートに共通するテーマ
- 明示された方法論と実際の運用との間の矛盾
- 当初の設計が誤っていた可能性を示す行動の修正
- 複数の証拠項目を含む方法論ノート(強いシグナル)
4c. セッションログ
# Read recent session logs (last 5-10 sessions)
ls -t ops/sessions/*.md 2>/dev/null | head -10
セッションログをスキャンして、次の点を確認します。
- 繰り返される不満や回避策
- 一貫して省略される手順
- エージェントの行動とシステムの推奨事項との間に見られるパターン
- エラーのパターンやツールの失敗
4d. Self スペース
self/ が存在する場合、次を読みます。
self/methodology.md— エージェントが自身のプロセスをどう説明しているかself/goals.md— 現在の優先事項がシステムの機能と一致しているかself/memory/— ワークフローの不満に関するノートがあるか
4e. 摩擦一覧の作成
すべての摩擦に関する証拠を、構造化された一覧にまとめます。
Friction Inventory:
1. [category]: [description]
Frequency: [N observations across M sessions]
Sources: [filenames]
Impact: [what breaks or degrades]
System area: [which dimension/skill/workflow affected]
2. [category]: [description]
...
頻度 × 影響度で順位付けします。最も頻度が高く、影響度の大きい摩擦パターンをフェーズ 6 で優先します。
PHASE 5: 調査を参照する
調査に基づいてエビデンスを裏付けます。これが /architect とその場しのぎのトラブルシューティングを分ける点です。すべての推奨事項を、一般的な直感ではなく具体的な調査上の主張に結び付けます。
参照ファイルを読みます。
| 参照先 | 内容 | 使用するタイミング |
|---|---|---|
${CLAUDE_PLUGIN_ROOT}/reference/dimension-claim-map.md | どの調査上の主張がどの次元に関係するか | 摩擦を次元の調整に対応付けるとき |
${CLAUDE_PLUGIN_ROOT}/reference/interaction-constraints.md | 次元の選択がほかの次元にどのような圧力を与えるか | 提案する変更の連鎖的な影響を分析するとき |
${CLAUDE_PLUGIN_ROOT}/reference/methodology.md | 普遍的な原則と処理パイプライン | 推奨事項を第一原理に基づいて裏付けるとき |
${CLAUDE_PLUGIN_ROOT}/reference/failure-modes.md | 10 の失敗モードと、ドメインごとの脆弱性マトリクス | 摩擦を既知の失敗パターンに結び付けるとき |
${CLAUDE_PLUGIN_ROOT}/reference/tradition-presets.md | 設定空間における名前付きの位置 | 検討する代替設定を探すとき |
${CLAUDE_PLUGIN_ROOT}/reference/vocabulary-transforms.md | 普遍的な用語からドメイン固有の用語への対応付け | 出力にドメイン固有の用語を使用していることを確認するとき |
${CLAUDE_PLUGIN_ROOT}/reference/three-spaces.md | self/notes/ops のアーキテクチャと境界ルール | 3 空間の境界を分析するとき |
${CLAUDE_PLUGIN_ROOT}/reference/derivation-validation.md | 派生システムの検証テスト | 変更後の検証基準を確認するとき |
${CLAUDE_PLUGIN_ROOT}/reference/evolution-lifecycle.md | seed-evolve-reseed のパターンと、摩擦を起点とした導入 | 進化させるか、再シードするかを判断するとき |
${CLAUDE_PLUGIN_ROOT}/reference/self-space.md | エージェントのアイデンティティ生成と self/ アーキテクチャ | self-space に関する推奨事項を検討するとき |
調査の照合プロセス
フェーズ 3〜4 で特定した摩擦パターンや健全性の問題ごとに、次の手順を実施します。
Step 1: dimension-claim-map.md を確認する
- この問題に関係する調査上の主張はどれですか?
- それらの主張は、どの次元の位置を支持していますか?
- 現在の設定は、調査で推奨されている内容と矛盾していますか?
Step 2: interaction-constraints.md を確認する
- この摩擦は、次元の不一致による CASCADE 効果ですか?
- これを解決するためにある次元を変更すると、別の次元に圧力が生じますか?
- 文書化されている補償メカニズムはありますか?
Step 3: failure-modes.md を確認する
- これは既知の失敗モードのパターンに該当しますか?
- 派生時に、この失敗モードは HIGH リスクとしてフラグ付けされていましたか?
- 緩和策について、失敗モードの文書には何と書かれていますか?
Step 4: ナレッジグラフを検索する
mcp__qmd__deep_searchを使って、特定の摩擦に対処する主張を見つけます- ハイブリッド検索が利用できない場合は、
mcp__qmd__vector_searchに切り替えます - MCP が利用できない場合は、qmd CLI に切り替えます(まず
qmd query、次にqmd vsearch) - MCP と qmd CLI の両方が利用できない場合に限り、同梱の参照ファイルを直接読みます
- 自然言語で説明した摩擦パターンを検索します
- 影響を受けるシステム領域を検索します
- 提案する解決策の概念を検索します
mcp__qmd__deep_search query="[friction description in natural language]" limit=10
上位の検索結果を読みます。関連する主張ごとに、次の内容を記録します。
- 主張のタイトル(推奨事項で引用するため)
- 主張が示す内容
- 現在の摩擦にどのように当てはまるか
目標は、一般的な直感ではなく、すべての推奨事項を具体的な調査に結び付けることです。
PHASE 6: 推奨事項を作成する
フェーズ 2〜5 のエビデンスを統合し、影響度と労力の比率が高い順に、具体的な推奨事項を 3〜5 件提示します。
ランキング基準
| 基準 | 尺度 | 測定内容 |
|---|---|---|
| 影響度 | 高/中/低 | システムはどの程度改善されますか? |
| 労力 | 分/時間/日 | 実装にはどの程度の作業が必要ですか? |
| リスク | 可逆/一部可逆/不可逆 | どのような問題が起こり得ますか? |
| エビデンスの強さ | 強い(5 件以上のデータポイント)/中程度(3~4 件)/推測(1~2 件) | どの程度の裏付けとなるエビデンスがありますか? |
推奨事項は3~5件に制限してください。 5件を超えると、意思決定が難しくなります。ほかにも問題が見つかった場合は、容赦なく優先順位を付けてください。残りは次回の /architect パスで対応できます。
優先順位
- ヘルスチェックの FAIL 項目 — 壊れているため、最初に修正します
- 高頻度で発生する摩擦パターン — 繰り返し発生する問題に、次に対処します
- ドリフトの修正 — 理由なく導出結果から乖離した設定を修正します
- 調査に基づく最適化 — 強いエビデンスに裏付けられた改善です
- 推測に基づく改善 — エビデンスが乏しい興味深い案です(最大1件まで含めます)
実装時間の見積もり
すべての推奨事項には、具体的な時間の見積もりを必ず含めてください。
| 労力レベル | 典型的な変更 | 推定時間 |
|---|---|---|
| 分 | 設定値の変更、テンプレートへのフィールド追加、単一ファイルの編集 | 5~15分 |
| 時間 | スキルの再生成、MOC の再構成、スキーマの移行 | 30~120分 |
| 日 | 全体の再シード、アーキテクチャの変更、複数スキルの再設計 | 複数のセッション |
予算の25%ルールを適用してください。 実装時間の見積もりが一般的なセッションの25%を超える場合(60分のセッションなら15分超)、ヘルスチェックの FAIL レベルの問題でない限り、次のセッションまで延期することを推奨してください。
推奨事項の形式
推奨事項ごとに、分析全体を作成してください。
### [N]. [Specific change title]
**What:** [Concrete change — specific enough to implement without further clarification.
Name the exact file, section, and value that changes.]
**Why:** [Evidence chain from health analysis + friction patterns]
- Health: [specific FAIL/WARN from Phase 3, with note names/counts]
- Friction: [specific patterns from Phase 4, with observation filenames]
**Research:** [Specific claims supporting this change]
- From dimension-claim-map: [claim title and what it argues]
- From knowledge graph: [related claims found via search, with titles]
- From failure-modes: [if this matches a documented failure mode]
**Interaction effects:** [Cascade analysis from interaction-constraints.md]
- Changing [dimension X] from [current] to [proposed] creates pressure on [dimension Y]
- Compensating mechanism: [how to handle the cascade, or "none needed"]
- If no interaction effects: "No cascade effects detected for this change."
**Impact:** [effort] effort / [benefit] benefit / [risk] risk
**Estimated implementation time:** ~X minutes
**Expected benefit:** [Measurable outcome the user can verify]
**Recommendation:** implement now / defer to next session
**Reversible:** [yes / no / partially — with explanation]
**Steps:**
1. [First concrete step — exact file and change]
2. [Second concrete step]
3. [Update ops/derivation.md with change rationale]
4. [Run validation to confirm nothing broke]
推奨事項の品質ゲート
すべての推奨事項には、次の項目が必須です。
- 具体的なファイル参照 — 「コンテキストファイルを更新する」ではなく、「CLAUDE.md の「Processing Pipeline」セクション、150行目付近を更新する」と記載します
- エビデンスによる裏付け — 少なくとも2つのデータポイント(ヘルスチェックの所見と摩擦の観察、または2つ以上の摩擦の観察)
- 調査の引用 — ナレッジベースからの具体的な主張を少なくとも1つ記載します
- リスクへの配慮 — 起こり得る問題を明示します
- 可逆性の評価 — 問題が悪化した場合に元に戻せるかを示します
- 時間の見積もり — 曖昧にせず、具体的に記載します
- 実装手順 — 順序を付け、各手順で正確なファイルを参照します
これらのゲートを1つでも満たさない推奨事項は却下してください。 内容の薄い推奨は信頼を損ないます。弱い推奨を5件提示するより、強い推奨を2件提示する方が適切です。
PHASE 7: ユーザーに提示する
優先順位を付けた推奨事項を提示します。全体を通じて、ユーザーのドメイン用語(derivation.md の用語マッピングに基づく)を使用し、ドメインユーザーに一般用語を見せないでください。
出力形式
=== ARCHITECT REPORT ===
System: [domain name from derivation]
Platform: [detected platform]
Focus: [specific area if requested, or "full system"]
Date: [YYYY-MM-DD]
Evidence Summary:
Health: [N FAIL, N WARN, N PASS — from Phase 3]
Friction: [top 3 friction patterns with frequency counts]
Drift: [dimensions that shifted from derivation, if any, or "none detected"]
Failure modes: [HIGH-risk modes from derivation that show activity, or "none active"]
--- Recommendations (ranked by impact-to-effort) ---
[Recommendation 1 — full format from Phase 6]
[Recommendation 2 — full format from Phase 6]
[Recommendation 3 — full format from Phase 6]
[Optional: Recommendations 4-5]
--- Next Steps ---
Which recommendations would you like to implement? I will execute the steps
and update ops/derivation.md with the rationale.
Options:
- "all" — implement all recommendations
- "1, 3" — implement specific recommendations
- "none" — defer all to next session
- "explain 2" — get more detail on a specific recommendation
=== END REPORT ===
ユーザーが承認した場合
記載された手順に従って、選択された推奨事項を実装します。実装ごとに、次の操作を行います。
- 変更を実施する — 「手順」に記載された具体的なファイルを編集します
- 重要な変更(セクションの置き換え、設定の変更など)について、変更前と変更後を示す
- 次の内容を含めて
ops/derivation.mdを更新する:- 変更内容
- 変更理由(エビデンスの概要 — ヘルスチェックの所見と摩擦パターン)
- 調査による裏付け(ナレッジベースの主張への参照)
- 変更日
- 確認された相互作用(あれば)
ops/changelog.mdに記録する(存在しない場合は作成します):## YYYY-MM-DD: [change title] **Source:** /architect — [evidence summary] **Change:** [what was modified, which files] **Research:** [supporting claims] **Risk:** [risk assessment]- 変更後の検証を実行する:
- すべての Wiki リンクが引き続き解決される
- すべてのノートに必須のスキーマフィールドが引き続き存在する
- MOC の階層が維持されている
- 新たな3スペース境界違反が発生していない
- セッションのオリエンテーションが引き続き正しく読み込まれる
検証結果を報告します。
Implementation complete.
Changed: [list of files modified]
Validation: [N]/[N] checks PASS
[Any warnings or issues]
却下された場合
- 新たなエビデンスがない限り、同じ変更を再提案しないでください
- 必要に応じて理由を尋ねてください。設計思想が明らかになる場合は、その理由を新たな観察として記録します
- 推奨事項に「検討済み・延期」と印を付け、繰り返し提示しないでください
証拠が /reseed を示唆する場合
分析により以下が明らかになった場合:
- 3 次元以上にわたる次元の不一致
- 語彙がユーザーの実際の言語と一致しなくなっている
- 三空間の境界が消失している
- テンプレートの乖離が 40% 超
その場合は、漸進的なパッチではなく /reseed を推奨してください:
NOTICE: The evidence suggests systemic drift across multiple dimensions.
Incremental patching may create more incoherence. Consider running /reseed
for a principled re-derivation from first principles.
Drift detected in: [list dimensions]
Evidence: [key observations]
エッジケース
ops/derivation.md がない場合
現在の状態分析のみに基づく推奨を行います。レポートに次のように記載してください: 「導出履歴がないため、推奨はドリフトや設計意図を評価できません。導出のベースラインを確立するために /reseed の実行を検討してください。」
ops/observations/ または ops/sessions/ がない場合
フリクション分析が制限されます。次のように記載してください: 「運用上のフリクションデータがありません。推奨はヘルス分析とリサーチのみに基づいています。フリクションベースの進化を可能にするために、作業中に観察の記録を開始してください。」
小規模な Vault (10 ノート未満)
グラフ分析の指標 (密度、孤立ノード、クラスター) は小規模ではあまり意味を持ちません。次のように記載してください: 「Vault は初期段階です。グラフヘルスの指標は、ナレッジグラフが成長するにつれてより意味を持つようになります。構造の最適化よりも、記録と処理に注力してください。」
リサーチ結果がない場合
MCP ツールが失敗し、同梱の参照ファイルのみが情報源である場合:
- 関連するすべての参照ファイルを直接読む
- レポートに次のように記載してください: 「リサーチの根拠は同梱の参照のみです。セマンティック検索は利用できません。」
- 推奨は依然として有効です — 参照ファイルには中核となるリサーチが含まれています
フォーカスエリアが指定された場合
$ARGUMENTS が特定のエリアを指定している場合:
- すべてのフェーズを実行しつつ、所見をフォーカスエリアに重み付けする
- フォーカス外であっても、他の FAIL レベルのヘルス問題は引き続き報告する
- 次のように記載してください: 「[エリア] に焦点を当てました。他の所見は記録しましたが、優先順位は付けていません。」
品質基準
- すべての推奨を具体的な証拠 (ヘルスデータ + フリクションパターン + リサーチの主張) に根拠付ける — 直感だけの推奨は行わない
- 一貫してドメイン語彙を使用する — ドメインユーザーに汎用用語を決して露出させない
- 意見を明確に持つ — リサーチには立場があり、それを共有する — ただしその根拠を説明する
- 証拠が薄い場合はそれを認める: 「これは限られたフリクションデータに基づく推測です」は誠実です
- 緊急の修正 (FAIL 項目) と戦略的な改善 (最適化の機会) を区別する
- システムの成熟度が正当化する以上のインフラを決して推奨しない — 現在の自動化レベルを確認する
- すべての工数見積もりは誠実であるべき — 過小評価は過大評価よりも信頼を損なう
- 25% バジェットルールはガイドラインであり束縛ではない — FAIL レベルの問題はそれを超えることを正当化する