Documentation Governance¶
目的¶
Documentation は code から確実に復元できない知識を保存し、人間が AI Teams を理解・監督・ 統治するための coherent view を提供します。第二の implementation や project tracker ではありません。
Canonical language と translation¶
英語が normative/canonical です。日本語は owner の review と理解のために維持する正式な reader-facing translation で、未確認の機械翻訳 artifact ではありません。矛盾時は英語が優先です。
site navigation に含む authored 日本語 page は対応する英語 path と相互 language link を持ちます。 normative English を変更する outcome は同時に日本語を更新するか、その page を公式 translation surface から明示的に外します。generated page は同一 machine source から両言語へ再生成します。 validator は path/link 対応を、review は semantic fidelity を保証します。
保存する情報¶
hand-maintained documentation は次を扱います。
- product intent と engineering principle
- current accepted architecture と system-level sequence
- responsibility/trust boundary
- design constraint と major invariant
- decision rationale、agreement history、revisit condition
- code だけから安全に復元できない user task
code/config/test から復元できる function、class、file、option、schema、supported value は再記述せず、 generate または link します。
Source-of-truth model¶
Documentation → intent, policy, current accepted architecture
Tests/gates → enforceable invariants
Code/config → actual behavior and reconstructable facts
GitHub → decisions, agreement history, and mutable project state
機械的に検証可能な invariant を文書化する場合、owning change は test/quality gate を追加または 特定します。documentation は why、test は代表 success/failure path、code は behavior を担います。
Architecture と Decision¶
Architecture page は major component、sequence、responsibility/trust boundary、invariant、external dependency、runtime/verification/delivery の関係を現在形で説明し、function/class manual を含めません。
design rationale と合意履歴は decision label の GitHub Issue が正本です。Decision Issue は
Context、Problem、Options considered、Decision、Rationale、Trade-offs、Rejected alternatives、
Revisit conditions、Affected architecture、Status を持ちます。Status は Proposed、Accepted、
Superseded のいずれかで、Superseded は successor へ link します。
相互 link contract は次です。
Architecture → Why? → Decision Issue
Decision Issue → Current state? → Architecture page and stable heading
Accepted にする前に Decision Issue へ Architecture link を追加し、同じ architecture PR で Issue link を追加・更新します。Issue は PR または accepted commit を記録します。 Decision templateが必須 field を収集します。
Diagram policy¶
architecture diagram の第一目的は、人間が system や変更を短時間で正しく理解・review・議論できる ことです。AI の context として利用できることは二次的な利点で、diagram 作成の目的ではありません。 文章だけでは responsibility、boundary、順序、state、domain semantics、trust flow を誤解しやすい 場合に、一つの重要な問いへ答える最小の living view を作ります。
理解が難しい問いから view を選びます。
| 問い | 第一選択 |
|---|---|
| structure、responsibility、system boundary、高レベル topology | C4 Context または Container |
| 時間に沿った interaction と effect | UML Sequence |
| lifecycle と transition condition | UML State |
| material な domain relationship、ownership、cardinality | UML Class または domain diagram |
| credential、untrusted input、identity、privilege、data movement | Data-flow または trust-boundary diagram |
C4 は architecture overview の第一選択です。Context は人、system boundary、external system を示し、 Container は主要 application、runtime、service、data store の responsibility を示します。Component は 内部 responsibility、security、authority boundary が material な場合だけ使い、全 component を機械的に 図示しません。Code view や網羅的 class diagram は、code から復元でき drift しやすいため durable documentation の default にしません。
Sequence、State、domain、data-flow view は C4 を補完します。caller の順序と effect timing が重要なら Sequence、transition condition が文章では曖昧なら State、複雑な domain semantics には Class/domain を 使いますが、codebase をコピーしません。security-sensitive な変更では、credential、process identity、 privilege、authority transition を C4/UML より明確にできるなら trust boundary を優先します。 diagram 手法を reader に選ばせず、問いから author が選びます。
最小で proportional な利用¶
cross-component architecture、async/distributed interaction、lifecycle state machine、security/authority boundary、deployment topology、複数 external provider、複雑な domain relationship、onboarding cost が 高い構造では diagram を推奨します。trivial または単一 component の変更、code から自明な構造、 数行で正確に説明できる問い、implementation detail のコピー、current に保てない volatile な詳細では 通常不要です。
Documentation risk tier は検討の強さを変えますが、artifact を強制しません。
- Tier 0 は通常 diagram 不要です。
- Tier 1 は理解を material に改善する場合だけ使います。
- Tier 2 は material design review に有効な最小の C4、Sequence、State、domain、data-flow view を検討します。
- Tier 3 は independent な security/authority review を可能にする trust、state、interaction view を強く検討します。
Tier 2 であることだけを理由に C4 を必須にしません。diagram が human understanding または independent review を material に改善するかを問います。responsibility split が難しいなら Container 1枚、release flow が難しいなら Sequence 1枚を選び、Context、Container、Component、Class、Sequence、State を 一式で作りません。
Format、authority、maintenance¶
既存 project の diagram standard に従います。指定がなければ Mermaid、次に PlantUML、さらに他の version 管理可能で maintainable な text format を選びます。source は human-readable かつ machine-editable であるべきです。project は既存 policy で selection や format を override できます。 指定がない場合の compact default は次です。
documentation:
diagrams:
architecture_default: c4
text_format: mermaid
uml:
sequence: preferred_for_interaction
state: preferred_for_lifecycle
class: optional
default を再記述するためだけに configuration を増やしません。各 view は、一つの問いへ答えられる
十分な detail を持ち、stable に保てる高レベルにします。既存 documentation structure に従い、適合する
場合だけ docs/architecture/ を作ります。README は高レベル Context/Container 1枚までと詳細 page への
link に留めます。
Principle、Decision record、contract、schema、code、test が authority を保ちます。diagram は visual compression であり、security invariant、API、schema、behavior の唯一の contract にしません。material architecture view は Decision Issue と link し、理由を失わないようにします。proposed architecture は 明示して current accepted view と分離し、proposal を current fact として描きません。
component/service の追加、responsibility/boundary の移動、provider/external integration の変更、state transition の変更、security flow の変更、deployment topology の変更時に関連 diagram を確認します。 すべての code edit で全 diagram を検査しません。stale view は誤情報のまま維持せず、update、simplify、 delete、supersede します。
AI-generated view は actual implementation と authority contract に照らして review します。ownership、 arrow の意味、trust boundary、component の実在、current/proposed status を確認します。syntax、link、 referenced-file check は有用な軽量 validation ですが、architecture correctness は semantic review が 判断します。この policy は厳密 UML enforcement、modeling tool、diagram database、automatic generation、 repository-wide image generation を導入しません。
Human / machine documentation boundary¶
human-facing docs は purpose、concept、accepted structure、task journey、governance を説明します。
distributed SKILL.md と一階層の references/ は machine-facing canonical execution contract、
test は enforceable boundary です。必要な横断だけ link し、procedure 全体を複製しません。
AGENTS.md と SKILL.md は manual ではなく map です。repository/Skill purpose、essential
constraint、validation entry point、authoritative source location、task routing に限定し、詳細な
conditional guidance は linked canonical document に置きます。
Generated reference¶
machine-derived fact にも human-readable reference を提供します。現行 target は installed capability
surface（Plugin identity、Skill、MCP server、accepted provider operation）です。Plugin manifest、
Skill front matter、MCP manifest、versioned capability registry を input とし、
python3 scripts/docs.py generate が英日 page を生成、python3 scripts/docs.py check が freshness
を検証します。
将来候補は CLI、configuration、schema、compatibility、supported profile values です。一つの authoritative machine source、deterministic ordering、freshness check、human use case がある場合だけ target に追加します。
Mutable project state¶
backlog、active work、短期 migration、release preparation、unresolved defect、planned change は GitHub Issue/PR/Milestone/Release に置きます。恒久 docs は stable policy と tracker query への link だけを持ち、state を mirror しません。
Maintenance decision¶
documentation change ごとに一つを選びます。
KEEP: unique durable intent を canonical location に残すMOVE: より明確な canonical location へ移すMERGE: 別 source が同じ intent を所有するGENERATE: deterministic machine source から生成するLINK: 別 canonical source を authoritative に保つDELETE: obsolete、temporary、reconstructable、または価値がない
deletion/supersession は通常 maintenance です。Git history と Decision Issue が証拠を保存するため、 obsolete page を「念のため」残しません。
初期 inventory disposition¶
| Existing source | 用途 | Disposition | 結果 |
|---|---|---|---|
README.md |
USER と混在した operation/development 詳細 | MERGE/MOVE | concise English entry point、詳細は docs/contract へ route |
旧日本語 README.md |
USER と混在詳細 | MOVE/MERGE | concise official README.ja.md |
旧 docs/self-hosting.md |
USER operation | MOVE | paired docs/en|ja/user/self-hosting.md、旧 path は削除 |
plugins/ai-teams/skills/*/SKILL.md |
MACHINE CONTRACT / routing | KEEP/LINK | distributed source のまま conditional reference へ link |
plugins/ai-teams/skills/*/references/*.md |
MACHINE CONTRACT | KEEP/LINK | executable task contract の正本として維持 |
plugins/ai-teams/capabilities/**/references/*.md |
MACHINE CONTRACT | KEEP/LINK | owning capability の隣に維持 |
| Plugin/MCP manifest、capability registry | REFERENCE source | GENERATE | paired capability reference を生成 |
| integration/deployment reference | MACHINE CONTRACT | KEEP/LINK | optional runtime component の隣に維持 |
| release-management reference | MACHINE CONTRACT | KEEP/LINK | release Skill の隣に維持 |
| evaluation fixture Markdown | test fixture | KEEP | reader navigation から除外し test data として扱う |
| backlog/migration/release preparation | PROJECT STATE | DELETE from docs/LINK | GitHub object を authoritative に維持 |
場所だけを根拠に obsolete と判断できる現行 machine contract はありませんでした。retired capability または architecture divergence は documentation 作業で黙って変更せず、別 Issue にします。
Site と validation¶
Markdown が source です。MkDocs は English/Japanese navigation、search、anchor permalink、code highlight を持つ disposable HTML を生成します。生成 HTML は commit/edit しません。
Publication policy¶
AI Teams は、accepted main の documentation state から検証済み MkDocs site/ artifact を
GitHub Pages に publish します。repository Markdown と maintained machine-readable/generated source が
canonical であり、GitHub Pages は discoverable な distribution projection であって第二の
documentation source ではありません。deployment workflow は scripts/docs.py build だけを
documentation build command として使うため、既存の generated-reference、translation、navigation、link、
strict-rendering check を保持します。Pages の search surface は、本 repository の language policy が
維持する English/Japanese documentation を publish します。
workflow は artifact を build/submit できますが、GitHub Pages の有効化、deployment source の選択、 repository permission の付与、domain 設定、DNS 変更の authority を想定できません。accepted change の後に GitHub Pages が GitHub Actions 用に設定されていなければ、repository administrator がその deployment source を有効化してから hosted result を verify する必要があります。default Pages URL が observable に なるまで publication path は configured であり published ではありません。custom domain は別 work です。
required quality path は generated freshness、translation/language link pair、navigation coverage、
safe internal Markdown link/anchor を確認し、mkdocs build --strict を実行します。external URL
availability と semantic translation quality は review 対象で、CI は network crawl や意味の同一性を
主張しません。