Documentation Governance¶
目的¶
Documentation は code から確実に復元できない知識を保存し、人間が AI Teams を理解・監督・ 統治するための coherent view を提供します。第二の implementation や project tracker ではありません。
Specification governanceは、user intent、active change、current behavior、design rationale、verification evidence の authoritative な保存先を定めます。この page は reader-facing documentation の maintenance と publication の authoritative policy のままです。
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¶
Specification → current accepted behavior と durable invariant
Tests/gates → enforceable evidence
Code/config → actual behavior と reconstructable fact
GitHub → active change contract、decision、agreement history、mutable project state
機械的に検証可能な invariant を文書化する場合、owning change は test/quality gate を追加または 特定します。Specification が contract、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 を、
repository の Cloudflare Pages project を通じて publish します。repository Markdown と maintained
machine-readable/generated source が canonical であり、Cloudflare Pages は discoverable な distribution
projection であって第二の documentation source ではありません。Cloudflare は
python3 scripts/docs.py build を実行するため、publication path は既存の generated-reference、
translation、navigation、link、strict-rendering check を保持します。https://ai-teams.pages.dev/ の
published surface は、本 repository の language policy が維持する English/Japanese documentation を
公開します。
repository は scripts/docs_inputs.py の canonical inventory から Cloudflare build-watch の
include/exclude path だけを同期し、project-scoped token は専用 GitHub Actions Secret が供給します。
domain、DNS、credential、build command、deployment authorization、その他すべての Cloudflare setting
は repository source delivery の外側にある administrator-owned effect のままです。hosted
Cloudflare Pages check と production URL の exact readback が publication を立証し、repository build
の成功だけでは publication を立証しません。
Cloudflare build-watch synchronization¶
目的と設計意図: provider dashboard を第二の設定sourceにせず、Cloudflare build-watch pathを documentation builderのcanonical input inventoryに一致させます。
不変条件: scripts/docs_inputs.pyが唯一のinclude/exclude集合を所有します。同期はexact accountと
projectを読み、drift時だけsource.config.path_includesとsource.config.path_excludesを書き、
書いた後にprojectを再読します。pull-request codeへcredentialを渡しません。domain、DNS、build
command、environment、deployment、その他のsettingは変更しません。trusted main/manual jobはrepositoryの
isolated self-hosted ai-teams-ci runner contractを再利用し、有料GitHub-hosted runnerへ依存しません。
想定失敗とcontainment: credential欠落、authentication/API error、malformed response、invalidな desired path、final readback不一致はfail closedとし、retryせずconvergenceを主張しません。initial readの失敗時はwriteを0回にします。
定量上限: converged時はGETをexactly 1回、drift時はinitial GETを1回、PATCHを最大1回、final GETを 1回実行します。各request timeoutは15秒で、自動retryは0回です。
権限: Issue #806がexact account、project、許可する2 field、project-scoped Pages write tokenへのowner authorizationを記録します。権限が欠ける、またはより広いeffectはmutationを0回にします。credential valueはGitHubが所有し、repository codeはSecret identifierだけを指定します。
観測証拠はchanged/unchanged、request count、非secretのnormalized pathを報告し、tokenやauthorization headerを出力しません。recoveryはcredential、provider availability、canonical inputを修正してから 明示的に再同期します。rollbackは同じreview済みownerを通じて以前のwatch pathを復元し、unboundedな catch-allを暗黙には戻しません。
互換性はproject-localで、既存path semanticsを変えずdashboard管理のbuild-watch listを置き換えます。 acceptance testはno-driftのzero-write、3-request drift path、initial-read failure、malformed response、 final readback不一致を網羅します。
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 や意味の同一性を
主張しません。