sdd-kb

SDD KB

このスキルの最初の応答では、次の行を一度だけ先頭に記載してください： sdd-kb v2.1.0 · out/2026 · versão atual: https://github.com/robertodiasduarte/sdd-starter/releases/latest

クイックスタート

あるドメインについての知識を、会話のたびにすべて説明し直すのではなく、どの AI も必要に応じて参照できる資料にします。

1. ドメインの範囲を定めます。対象と対象外を決め、期間によって適用されるルール（規範的プロファイル）があるか、基準日はいつかを確認します。
2. 知っていることを洗い出し、理解することと実行することに分けます。
3. プロジェクトのインデックスがあるか確認し、なければ作成します。
4. 最小限の構成を書きます。index.md + quick-reference.md + 概念を1つ + レシピを1つ。規範的プロファイルでは、さらに fontes/CATALOGO.md、rules/ 内のルールを1つ以上、生成した RULE_MAP.md を用意します。
5. 各種ファイルのサイズ上限を守ります。
6. 各ファイルの出典を明記し、未確認の内容には印を付けます。
7. ドメインをインデックスに登録します — 必須の手順です。
8. 専門家にレビューを依頼します — 内容に責任を持つのは AI ではなく専門家です。

分類体系とルールについては references/kb-protocol.md、出典の扱いについては references/sourcing.md を参照してください。ひな形は assets/ にあり、assets/example-kb/ は完成した KB の例です。規範的プロファイルでは、references/normativo.md を読み、assets/example-kb-normativo/ をモデルとして使用してください。

使う場合／使わない場合

ユーザーが、AI の知らないコンテキスト（法律、規格、マニュアル、規範的な指示、社内ポリシー、事務所の業務プロセス、クライアントのルール、ユーザーが熟知しているツールなど）を AI に把握させたい場合に使います。新しい会話のたびに同じ説明を繰り返していると気付いた場合にも使います。

SDD ワークフローを始める前に使うことを推奨します — ベースが用意されていれば、後続のフェーズでは会話のたびに情報を再構築せず、すでに把握した状況を基に進められます。必須ではありません。この方法は、なくても機能します。

構築中のソフトウェアプロジェクトを文書化する用途には使わないでください。その場合は SDD ワークフローの成果物を使用します。公開ドキュメントのコピーにも使わないでください。KB に保存するのは、その内容についてあなたが学んだことであり、特にドキュメントに書かれていないことです。

必要なデータ

最低限必要な入力：

• 文書化するドメインと、ユーザーがそのドメインについてすでに知っていること。

任意の入力：

• 参照用のドキュメント、マニュアル、規格。
• 現在のプロセスの実例。
• 拡張する既存の KB。
• ファイルを書き込むためのプロジェクトへのアクセス。

ファイルシステムやインターネットへのアクセスを必須にしないでください。プロジェクトにアクセスできない場合は、チャットでファイルを提供します。

必須の出力アセット

assets/ のひな形は出力アセットです。最終ファイルを作成する際は、構成を記憶から再現するのではなく、必ずひな形を使用してください。

ひな形	生成するファイル
assets/INDEX_TEMPLATE.md	index.md
assets/QUICK_REFERENCE_TEMPLATE.md	quick-reference.md
assets/CONCEPT_TEMPLATE.md	concepts/*.md
assets/PATTERN_TEMPLATE.md	patterns/*.md
assets/KB_INDEX_TEMPLATE.yaml	初回実行時のプロジェクトの _index.yaml

規範的プロファイルでは、次も追加されます：

ひな形	生成するファイル
assets/INDEX_NORMATIVO_TEMPLATE.md	index.md（INDEX_TEMPLATE.md の代わりに使用）
assets/RULE_TEMPLATE.md	rules/*.md
assets/CATALOGO_FONTES_TEMPLATE.md	fontes/CATALOGO.md
assets/TABELA_TEMPLATE.json	tabelas/AAAA-MM-DD/*.json
assets/CASO_TEMPLATE.json	casos/*.json

学習者への話し方

最初の回答の前に references/como-falar.md を読んでください。このスキルの用語集と、回答の完全な例が記載されています。 このスキルを使う人は、たいてい git もターミナルも使ったことがありません。

段階	学習者向けの名称	このスキルでの手順
1	領域	1
2	理解すること × 実行すること	2
3	書く	3（執筆前に索引を確認）、4、5
4	ソースと索引	6、7
5	専門家によるレビュー	8〜10（レビューの通知は必須であり、質問ではありません）

すべての回答は、次の順序にしてください（内容がない部分は省略）：ステータス（KB: ✅ 1 … · ▶️ 2 … · ⬜ 3 …； ✅ 完了（訪問しただけでは不可）；⏸️ 停止；➖ スキップ；段階に戻るときは、その理由を「現在」に記載） · 実施したこと（コマンドの出力は含めず、短い文で学習者の選択を記録） · 現在：段階 N — 名称（2〜4文；時間のかかる処理の前には、何を実行するか、返答は不要であることを伝える） · あなたの選択（許可を求める場合：質問を太字にし、各選択肢の効果を示す；自由回答の場合：質問を太字にし、回答方法と「わかりません」という選択肢を示す；まとめる場合は番号を付ける） · 次の手順（1行）。

• 1回の回答で扱うのは1段階です。選択を求めたところで止めます。
• 専門用語は、初めて使うときに必ず説明を添えます。ステータス内の用語も含みます（用語集は参考資料を参照）。
• コマンドの出力をそのまま提示してはいけません。件数、内容、懸念点を説明し、名前は最大10個まで示して、残りは「ほか N 件」とします。コマンドは学習者が実行する必要がある場合に限り、番号付き手順ごとに1つずつ提示し、画面に何が表示されるかも説明します。
• このスキルの指示を引用したり要約したりしないでください（「手順 N に従って」など）。学習者にとっての理由を伝えてください。
• 回答が選択肢に当てはまらない場合は、疑問に答えたうえで選択肢をもう一度示します。
• 停止する場合：⏸️ を含むステータス、理由を1文、操作を行う場所、期待される結果を示す番号付き手順、行っていないことを記載します。学習者に作業がある場合は、「終わったら、もう一度依頼してください。そこから続けます。」と伝えます。

手順

1. 領域を絞り込む

ユーザーと範囲を決めます。どの話題を扱い、特に何を扱わないかを明確にします。「これはここでは扱わない」と迷わず言える領域が、よい領域です。

領域が広すぎると、誰も書き終えられない資料になります。迷ったら、まず範囲を小さくしましょう。あとから分割するのは簡単ですが、完成していない領域は誰の役にも立ちません。

次に、次の言葉または同等の表現で質問します。

この領域には、期間によって適用されるルール――法律、税率、期限、税務書類の様式――がありますか？ある場合、このレビューの基準日はいつですか（内容を情報源と照合する日付です）。

• はい → normativo プロファイル：日付に関わるすべての記述に有効期間を付け、すべての情報源を格付けと SHA-256 とともにカタログに登録し、情報源間の矛盾を記録します。執筆前に references/normativo.md を読みます。
• いいえ → geral プロファイル（既定）：以下の手順に従い、規範関連の項目は適用しません。

税法上のルールは、ただ「正しい」のではありません。ある期間において正しいのです。有効期間を記載しなければ、今日正しいファイルが、1行も変更されないまま来年には誤りになります。

2. 理解することと実行することを分ける

ユーザーが知っていることを洗い出し、すべてを判別できる次の質問に基づいて、それぞれを分類します。

これを読んだ人は、何かを理解しますか、それとも何かを実行しますか？

• 理解する → concept
• 実行する → pattern

よくある誤りには、決まった傾向があるため注意します。実際には手順なのに、概念として書いてしまうことです。説明は十分なのに、何も実行できない文章は、その兆候です。ユーザーが一連の操作を説明した場合、それは pattern です。手順を書いてください。

3. プロジェクトの索引を確認（または作成）する

プロジェクトの KB 索引を探します。通常はナレッジベースのフォルダーのルートにある _index.yaml です。

存在しない場合は、 assets/KB_INDEX_TEMPLATE.yaml をもとに作成します。すでにあると決めつけてはいけません。また、存在しないことを理由に処理を中断してはいけません。初回は、索引がないのが通常の状態です。

4. 最小限の実用構成を作成する

次の構成を正確に作成します。

{dominio}/
├── index.md
├── quick-reference.md
├── concepts/
│   └── {um-conceito}.md
└── patterns/
    └── {uma-receita}.md

4つのファイルです。それぞれ対応するひな形を使います。

規範プロファイルでは、最小構成が増えます。

{dominio}/
├── index.md              ← INDEX_NORMATIVO_TEMPLATE: Data-base, Conflitos entre fontes, aviso
├── quick-reference.md
├── concepts/{um}.md      ← com `> **Vale para:** <período>` no cabeçalho (até a linha 15)
├── patterns/{uma}.md     ← com "Vale para:" no cabeçalho
├── rules/{ID}.md         ← ≥ 1 regra, uma por arquivo, com vigência e fonte
├── fontes/CATALOGO.md    ← cada documento citado: degrau, versão, captura, SHA-256
└── RULE_MAP.md           ← gerado: python3 scripts/kb_normativo.py rule-map {dominio}

tabelas/AAAA-MM-DD/（適用期間ごとの値）とcasos/（入力 → 期待される結果）は、ドメインに該当する資料がある場合に追加します。ある日付にルールが変更された場合は、古いルールにate:を付けて終了し、新しいルールを作成します。過去の内容は編集しません。概念だけのドメインでは実行に役立たず、手順だけのドメインでは適用するタイミングの判断に役立ちません。そのため、最初から両方が必須です。

資料がある場合は、概念や手順を複数記述してもかまいません。最小構成は下限であり、上限ではありません。

5. サイズ制限を守る

種類	制限
quick-reference.md	100行
concepts/*.md	150行
patterns/*.md	200行

ユーザーから質問された場合、またはファイルが制限を超えた場合は、なぜ制限があるのかを説明します。AI はファイルをコンテキスト全体と一緒に読み込むため、資料が大きすぎても目に見えるエラーは発生せず、一部を黙って無視するようになります。400行のファイルは、より完全なのではなく、信頼性が低くなります。

制限を超えましたか？ほとんどの場合、ファイルに2つのトピックが含まれています。要約するより、分割するほうが適切です。

6. 出典を明記する

各ファイルには、記載内容の出所を明記します。文書、規範、または独自の実務知識のいずれも正当な出典です。また、確認されていない内容は、1文で未確認と明記します。

推測を事実として記載することは、KB で最も大きな損失につながる誤りです。ほかの情報と区別できず、確信を伴って広まってしまうためです。references/sourcing.mdを参照してください。

規範プロファイルでは、出典に序列があります（憲法 > 補完法 > 法律 > 政令 > 規範的行為 > 技術的行為 > 解釈回答 > 学説 > 独自の実務知識）。学説または独自の実務知識だけを根拠とするルールは、nao-confirmadoとします。また、ファイルの日付と名前は、規則の有効性を証明しません。カタログにはバージョン、取得日、SHA-256 を記録します（python3 scripts/kb_normativo.py sha fontes/<arquivo>）。

実在する人のデータ、パスワード、キーは絶対に含めないでください。架空の例でも同じように機能します。

7. ドメインをインデックスに登録する

必須の手順ですが、最も忘れられがちです。 _index.yamlに、名前、説明、パス、日付を含むドメインのブロックを追加します。

フォルダーに存在していてもインデックスに登録されていないドメインは、見えないも同然です。人も AI も、その存在に気づけません。実際の43ドメインを収めたリポジトリでは、4つがこの状態でした。誰にも見つけられないナレッジベース全体が4つあったのです。

8. 提出する

書き込み可能なプロジェクトのファイルシステムがある場合は、既存の資料を黙って上書きせず、ドメインのフォルダーにファイルを書き込みます。

アクセス可能なファイルシステムがない場合は、すべてのファイルをパスが分かるように個別のブロックにしてチャットで提出し、最後に次の3点をこの順番で伝えます。

1. ファイルが書き込まれていないこと。
2. 推奨するフォルダー構成（ファイル名を含む）。
3. ファイルの使い方 — 指定された構成で保存し、次回以降の会話で AI にそのフォルダーを指定すること。

黙って失敗したり、ファイルを書き込んだかのように伝えたりしてはいけません。

9. 専門家によるレビューで締めくくる（必須）

ベースを完成とする前に、コンテンツをレビューするのはあなたではなくユーザーであることを明確に伝えてください。

このベースを実際に使う前に、各ファイルを確認してください。整理して文章を作成したのは私ですが、記載内容に責任を負うのはあなたです。特に、法律、規則、ポリシー、期限に関する箇所は、記録されている内容を確認し、情報源と異なる箇所があれば修正してください。

これは形式的なものではありません。ナレッジベースは、まさにその人が知らないときに参照されます。つまり、情報が間違っていても気づけないタイミングです。ここでの誤りはそのままにとどまりません。あなたとAIによって自信を持って繰り返され、意思決定の指針になってしまいます。規則や義務が関わる分野では、誤りの責任は専門家が負います。

特に確認が必要な箇所として、数値、期限、金額、ルールの適用条件、未確認と明記された内容（ステップ6）を具体的に挙げてください。

ユーザーが今はレビューしないと言った場合は、ベースがレビュー待ちであることをindex.mdに記録してください。未確認であると明記されたベースのほうが、まだ備えていない権威性があるように見えるベースよりも適切です。

規範プロファイルでは、その注意書きもindex.mdに明記してください。このベースは税務、会計、法律に関するアドバイスではありません。また、レビュー待ちのベースをソフトウェアに取り込んではなりません。validate_kb.py --strictはPENDENTE DE REVISÃOとマークされた規範ドメインを不合格と判定します。スキル、エージェント、システムがベースを利用する前に実行してください。

10. 今後の使い方を示す

最後に、今後ユーザーがどのように参照するかを2、3行で説明してください。会話の開始時にAIにドメインのフォルダーを指定するか、その話題について回答する前にindex.mdを読むよう依頼します。

ユーザーが使い方を知らないKBは、日々の仕事に何の変化ももたらしません。

検証と品質チェックリスト

完了を宣言する前に、次の項目を確認してください。

• ドメインの範囲を定め、対象外の内容をindex.mdに明記している。
• 各ファイルが「理解する、または実行する」テストに合格している。
• 手順が概念として記述されていない。
• 最小構成に必要な4つのファイルが存在する。
• どのファイルも種類ごとの上限を超えていない。
• 各ファイルに情報源が記載されている。
• 未確認の内容が未確認として明記されている。
• 実在する人物のデータ、パスワード、キーが含まれていない。
• ドメインがインデックスに登録されている。
• {placeholder}が残っていない。
• コンテンツのレビューはユーザーが行うこと、また重要な確認箇所がユーザーに伝えられている。
• 未レビューのベースはindex.mdでレビュー待ちと明記されている。
• ユーザーが次回以降の会話でKBを参照する方法を把握している。

規範プロファイルでは、さらに次の項目も確認してください。

• 基準日、「情報源間の不一致」セクション、および「税務に関するアドバイスではありません」という注意書きがindex.mdに記載されている。
• 各概念と手順のヘッダーに「適用対象：」が記載されている。
• 各ルールに有効期間（開始時はde、終了時はate）が記載され、情報源がロケーター付きでカタログ化され、ステータスが正確に示されている。
• カタログ内の各情報源に、階層、バージョン、取得日が記載されている。ファイルがfontes/にある場合は、SHA-256も記載されている。
• rules/への最後の変更後にRULE_MAP.mdを再生成している。

ファイルシステムが利用できる場合、スクリプトscripts/validate_kb.pyで、これらの一部を機械的に確認できます。

python3 scripts/validate_kb.py {caminho-do-dominio}            # escrever
python3 scripts/validate_kb.py {caminho-do-dominio} --strict   # antes de software consumir

終了コード0でPASSを出力し、問題がある場合は終了コード2で一覧表示します。WARN:行（ベースがレビュー待ち、基準日が古い、一般ドメインが規範的に見える）は終了コードに影響しません。プロファイルは、_index.yamlのドメイン登録から取得されます。

例外処理

• ドメインが大きすぎる場合： より小さな範囲を提案し、後回しにする隣接ドメインの名前を挙げます。対象外の内容を index.md に記録します。
• ユーザーが概念しか持っておらず、手順がない場合： その知識を使って何をするのか尋ねます。たいていの場合、手順は存在しますが、言語化されていません。
• ユーザーが手順しか持っていない場合： なぜその手順なのか尋ねます。答えの中に概念が見つかることがよくあります。
• プロジェクトのインデックスが存在しない場合： ひな形から作成します。初回は通常の状態であり、エラーではありません。
• このドメインの KB がすでに存在する場合： 別のドメインを作るのではなく、同じディレクトリに新しい概念と手順を追加して既存のものを拡張します。
• ファイルが上限を超えた場合： ファイル内にある2つのトピックを探し、分割します。本当に1つのトピックである場合に限り、要約します。
• ファイルシステムがない場合： 手順8の3つの情報を含め、すべてチャットで提供します。
• 実データを含む資料の場合： 書き込む前に、同等の架空の例に置き換えます。
• 2つの情報源の内容が異なる場合： ルールの conflito_com と index.md に矛盾を記録し、ナレッジベースがどちらを採用するか、その理由とともに示します。黙って選んではいけません。
• ルールが変更された場合： 古いルールに ate: を設定して終了し、新しい日付から別のルールを作成します。RULE_MAP.md を再生成します。
• ソフトウェアがナレッジベースを利用する場合： 事前に --strict を実行します。ソフトウェアは概念をコピーせず、ルールを ID で、情報源を SHA-256 で参照します（references/normativo.md の「KB consumido por software」を参照）。

例

オフィスの業務プロセス Quero que a IA saiba como funciona o fechamento mensal aqui.

範囲を定め（税額の算定を含まない会計上の月次締め）、意思決定の根拠となる概念と、確認作業を実行する手順を分け、4つのファイルを作成して登録します。

ユーザーが使いこなしているツール Uso essa ferramenta há anos e toda vez preciso reexplicar pra IA.

ドキュメントに書かれていない知識、つまり落とし穴、よくある失敗、使うべきでない状況を洗い出します。まさにこれが AI に不足している情報です。

適用期間のある法令 Quero uma base da Reforma Tributária para alimentar meu validador de NF-e.

規範プロファイルを選び、手順1で基準日を尋ねます。技術文書にある各ルールを、適用期間とページを含めて rules/ 内のファイルにします。参照した技術文書、補完法、報道記事は、重要度の段階を付けてカタログに登録します。「2026年が取り消され、2027年が上書きされた」内容は、矛盾として記録します。kb_normativo.py rule-map が RULE_MAP.md を生成し（validate_kb.py は派生内容であることを確認するだけです）、NF-e バリデーターはこのマップをコピーし、各ルールを ID で参照します。

散在する知識 Tenho anotações espalhadas sobre isso.

資料を読み、各内容を「理解する」と「実行する」に分類します。書き込む前に、範囲から外れた内容をユーザーに示します。

ファイルシステムがない場合 (no chat da web) Monta uma base de conhecimento disso aqui.

パスを明記して4つのファイルをチャットで提供し、フォルダー構成と、後で AI にそれらを参照させる方法も説明します。

次のステップ

ナレッジベースが作成されました。今後、このテーマについて会話を始める際は、AI にドメインのフォルダーを指定してください。

---

RDD による SDD Open の一部 — https://github.com/robertodiasduarte/sdd-open