diff --git a/.github/workflows/book-qa.yml b/.github/workflows/book-qa.yml index db60d28..c27d4ed 100644 --- a/.github/workflows/book-qa.yml +++ b/.github/workflows/book-qa.yml @@ -39,6 +39,9 @@ jobs: - name: Book metadata consistency check run: node scripts/check-metadata-consistency.js + - name: Check reader-facing checklist and figure contracts + run: node scripts/check-issue-240-ux.js + - name: Install dependencies (book-formatter) working-directory: book-formatter run: npm ci diff --git a/book-config.json b/book-config.json index 08f72a0..994c7f7 100644 --- a/book-config.json +++ b/book-config.json @@ -193,10 +193,10 @@ "modules": { "quickStart": false, "readingGuide": true, - "checklistPack": false, + "checklistPack": true, "troubleshootingFlow": true, "conceptMap": false, - "figureIndex": false, + "figureIndex": true, "legalNotice": true, "glossary": true } diff --git a/docs/_data/navigation.yml b/docs/_data/navigation.yml index bc95e1a..f4c878d 100644 --- a/docs/_data/navigation.yml +++ b/docs/_data/navigation.yml @@ -51,6 +51,10 @@ appendices: path: /appendices/appendix-f/ - title: 付録G：参考資料 path: /appendices/appendix-g/ +- title: 独立チェックリスト集 + path: /appendices/checklist-pack/ +- title: 図表索引 + path: /appendices/figure-index/ afterword: - title: あとがき path: /afterword/ diff --git a/docs/appendices/checklist-pack/index.md b/docs/appendices/checklist-pack/index.md new file mode 100644 index 0000000..9a3a568 --- /dev/null +++ b/docs/appendices/checklist-pack/index.md @@ -0,0 +1,57 @@ +--- +layout: book +title: "独立チェックリスト集" +--- + +# 独立チェックリスト集 + +この付録は、章内に点在する確認事項を実運用の目的別に再編したものです。各項目は未実施の確認作業として扱います。章内のコードブロックや設定例は、実施済みを示すものではありません。 + +## 準備 + +- [ ] 対象リポジトリ、責任者、利用するGitHubアカウントまたは組織を確認した。根拠: [第1章](../../chapters/chapter01/)、[第5章](../../chapters/chapter05/) +- [ ] Gitのユーザー設定、認証方法、必要な開発環境をプロジェクトのルールに合わせた。根拠: [第3章](../../chapters/chapter03/) +- [ ] 機密情報、学習データ、ライセンスの扱いを公開前に確認した。根拠: [第5章](../../chapters/chapter05/)、[第17章](../../chapters/chapter17/)、[付録G](../appendix-g/) + +## Issue と計画 + +- [ ] Issueに目的、受入基準、制約、変更禁止領域を記録した。根拠: [第2章](../../chapters/chapter02/)、[第4章](../../chapters/chapter04/) +- [ ] 影響範囲、検証方法、ロールバック方針を作業開始前に合意した。根拠: [第2章](../../chapters/chapter02/)、[第11章](../../chapters/chapter11/) +- [ ] AI支援を使う場合は、入力可能な情報と人間の確認責任を明確にした。根拠: [第2章](../../chapters/chapter02/)、[第6章](../../chapters/chapter06/) + +## ブランチとコミット + +- [ ] 変更目的に対応する短命ブランチを作成し、mainへの直接変更を避けた。根拠: [第1章](../../chapters/chapter01/)、[第12章](../../chapters/chapter12/) +- [ ] コミットをレビュー可能な単位に分け、意図と検証結果を説明できる状態にした。根拠: [第1章](../../chapters/chapter01/)、[第3章](../../chapters/chapter03/) +- [ ] 実験、release、不要になったブランチの扱いをチームで定義した。根拠: [第12章](../../chapters/chapter12/) + +## Pull Request とレビュー + +- [ ] PRに変更内容、影響範囲、検証、ロールバック、AI利用の有無を記載した。根拠: [第2章](../../chapters/chapter02/)、[第7章](../../chapters/chapter07/) +- [ ] 人間が仕様、リスク、セキュリティ上の判断を確認し、AIレビューだけで承認しない。根拠: [第7章](../../chapters/chapter07/) +- [ ] CODEOWNERS、必須レビュアー、承認条件が対象変更に適用されることを確認した。根拠: [第9章](../../chapters/chapter09/) + +## CI/CD + +- [ ] 必須テスト、静的解析、依存関係確認をPRの品質ゲートとして実行した。根拠: [第7章](../../chapters/chapter07/)、[第13章](../../chapters/chapter13/) +- [ ] デプロイ対象環境、承認者、Secretsの参照範囲を確認した。根拠: [第11章](../../chapters/chapter11/)、[第13章](../../chapters/chapter13/) +- [ ] 失敗時の停止、再実行、ロールバックの手順を検証可能な形で残した。根拠: [第11章](../../chapters/chapter11/)、[付録B](../appendix-b/) + +## セキュリティ + +- [ ] トークン、パスワード、個人情報、機密データをコード、ログ、Issue、PRへ含めていない。根拠: [第8章](../../chapters/chapter08/)、[第11章](../../chapters/chapter11/) +- [ ] 入力検証、認証・認可、依存関係更新、破壊的変更のリスクを確認した。根拠: [第7章](../../chapters/chapter07/)、[第8章](../../chapters/chapter08/) +- [ ] Secret scanning、code scanning、dependency reviewの結果を確認し、例外があれば記録した。根拠: [第8章](../../chapters/chapter08/) + +## 組織・大規模運用 + +- [ ] 組織、チーム、リポジトリの権限継承と直接付与を監査した。根拠: [第9章](../../chapters/chapter09/)、[第10章](../../chapters/chapter10/) +- [ ] Outside Collaborator、SAML SSO、監査ログの運用を組織ポリシーと照合した。根拠: [第10章](../../chapters/chapter10/) +- [ ] 大規模データ、モデル、外部協力者、コンプライアンスの責任分界を確認した。根拠: [第14章](../../chapters/chapter14/)、[第16章](../../chapters/chapter16/)、[第17章](../../chapters/chapter17/) + +## 関連資料 + +次の資料はリポジトリ内の導入例であり、この公開チェックリストの実施済み項目ではありません。対象リポジトリの公開範囲と運用文脈を確認したうえで参照してください。 + +- — AIエージェント向けSecurity checklist: AIレビューの見落としを前提に人間が確認する最小例。 +- — self-hosted runner運用チェックリスト: trusted input、runner分離、ephemeral運用を扱う導入例。 diff --git a/docs/appendices/figure-index/index.md b/docs/appendices/figure-index/index.md new file mode 100644 index 0000000..886136d --- /dev/null +++ b/docs/appendices/figure-index/index.md @@ -0,0 +1,16 @@ +--- +layout: book +title: "図表索引" +--- + +# 図表索引 + +この索引は、本書の公開本文に掲載する自己完結SVG図版のexact inventoryです。スクリーンショット用コード例、badge、favicon、logoは含めません。 + +1. [図1.1：ローカルとリモートの同期](../../chapters/chapter01/#figure-chapter01-repository-sync) — 作業ディレクトリ、ステージング、ローカルリポジトリ、GitHubの同期。 +2. [図5.1：Public / Privateリポジトリの判断フロー](../../chapters/chapter05/#figure-chapter05-repository-visibility) — 公開制約と公開目的に基づく可視性の選択。 +3. [図7.1：ハイブリッドレビューワークフロー](../../chapters/chapter07/#figure-chapter07-hybrid-review-flow) — AIレビュー、人間レビュー、CIの品質ゲート。 +4. [図9.1：組織からリポジトリへの権限継承](../../chapters/chapter09/#figure-chapter09-permission-inheritance) — Organization、Team、Repositoryの権限経路。 +5. [図12.1：ML開発向けGit Flow](../../chapters/chapter12/#figure-chapter12-ml-git-flow) — feature、experiment、releaseを含む統合フロー。 + +各リンクは該当する`figure`要素のstable anchorへ直接移動します。図版はJavaScriptを必要とせず、SVG内のtitleと説明、captionを備えます。 diff --git a/docs/assets/css/main.css b/docs/assets/css/main.css index 130ff02..5c85766 100644 --- a/docs/assets/css/main.css +++ b/docs/assets/css/main.css @@ -382,6 +382,23 @@ a:hover { height: auto; } +.book-figure { + margin: 1.5rem 0; +} + +@media (max-width: 640px) { + .book-figure:not(.book-figure--narrow) { + overflow-x: auto; + overscroll-behavior-inline: contain; + padding-bottom: 0.5rem; + } + + .book-figure:not(.book-figure--narrow) > svg { + min-width: 720px; + max-width: none !important; + } +} + .page-content table { width: 100%; border-collapse: collapse; diff --git a/docs/chapters/chapter01/index.md b/docs/chapters/chapter01/index.md index 5bbb1d1..d9adb78 100644 --- a/docs/chapters/chapter01/index.md +++ b/docs/chapters/chapter01/index.md @@ -149,17 +149,22 @@ main ### 同期の仕組み -```mermaid -graph LR - A[作業ディレクトリ] -->|add| B[ステージングエリア] - B -->|commit| C[ローカルリポジトリ] - C <-->|push/pull| D[リモートリポジトリ
GitHub] - - style A fill:#f9f9f9,stroke:#333,stroke-width:2px - style B fill:#e1f5e1,stroke:#333,stroke-width:2px - style C fill:#e1e5f5,stroke:#333,stroke-width:2px - style D fill:#ffe1e1,stroke:#333,stroke-width:2px -``` +
+ + ローカルとリモートの同期 + 作業ディレクトリからステージングエリア、ローカルリポジトリへ進み、ローカルリポジトリとGitHub上のリモートリポジトリをpushとpullで双方向に同期する流れ。 + + + 作業ディレクトリ + ステージングエリア + ローカルリポジトリ + リモートリポジトリ（GitHub） + add + commit + pushpull + +
図1.1：ローカル作業からGitHub上のリモートリポジトリまでの同期。矢印のラベルは実行するGit操作を示す。
+
### リモートブランチの追跡 - ローカルブランチとリモートブランチの対応 diff --git a/docs/chapters/chapter05/index.md b/docs/chapters/chapter05/index.md index 7ffd058..6d259aa 100644 --- a/docs/chapters/chapter05/index.md +++ b/docs/chapters/chapter05/index.md @@ -152,30 +152,34 @@ policies: ### AI協働を含む判断フローチャート -```mermaid -flowchart TD - A[リポジトリ作成] --> B{機密情報を含むか？} - B -->|Yes| C[Private] - B -->|No| D{AI生成コードの
知的財産権が懸念されるか？} - D -->|Yes| E[Private + AI使用ポリシー明記] - D -->|No| F{特許や独自アルゴリズムを含むか？} - F -->|Yes| G[Private] - F -->|No| H{オープンソースとして
公開する意図があるか？} - H -->|Yes| I[Public + AI協働の明示] - H -->|No| J{AI協働の学習事例として
共有したいか？} - J -->|Yes| K[Public + AI協働ドキュメント] - J -->|No| L{教育目的や
ポートフォリオか？} - L -->|Yes| M[Public] - L -->|No| N[Private] - - style C fill:#ffcccc - style E fill:#ffcccc - style G fill:#ffcccc - style N fill:#ffcccc - style I fill:#ccffcc - style K fill:#ccffcc - style M fill:#ccffcc -``` +
+ + PublicとPrivateリポジトリの判断 + 機密情報、AI生成コードの知的財産権、特許・独自アルゴリズム、オープンソース公開の意図、AI協働の学習事例共有、教育・ポートフォリオの順に確認する。各質問のはい側でPrivateまたは目的別のPublicを選び、すべていいえの場合はPrivateを選ぶ判断フロー。 + + + リポジトリ作成 + 機密情報を含むか？ + Privateはい + いいえ + AI生成コードの知的財産権が懸念されるか？ + Private＋AI使用ポリシーはい + いいえ + 特許や独自アルゴリズムを含むか？ + Privateはい + いいえ + オープンソースとして公開する意図があるか？ + Public＋AI協働の明示はい + いいえ + AI協働の学習事例として共有したいか？ + Public＋AI協働文書はい + いいえ + 教育目的またはポートフォリオか？ + Publicはい + いいえPrivate + +
図5.1：Public / Private リポジトリの判断フロー。機密性、知的財産、公開意図、共有・教育目的を順に確認し、公開時はAI協働の方針を明示する。
+
### Publicリポジトリの利点 - **コミュニティ貢献**: オープンソースエコシステムへの参加 diff --git a/docs/chapters/chapter07/index.md b/docs/chapters/chapter07/index.md index 734d7a8..06f85e0 100644 --- a/docs/chapters/chapter07/index.md +++ b/docs/chapters/chapter07/index.md @@ -236,15 +236,23 @@ def calculate_metrics(y_true, y_pred, threshold=0.5): ### ハイブリッドレビューワークフロー -```mermaid -graph LR - A[PR作成] --> B[（任意）Copilot code review] - B --> C[人間レビュー（仕様/リスク判断）] - C --> D[CI（テスト/静的解析）] - D --> E{要修正?} - E -->|Yes| F[修正→再レビュー] - E -->|No| G[承認→マージ] -``` +
+ + ハイブリッドレビューワークフロー + PR作成後、任意のAIレビュー、人間による仕様とリスクのレビュー、CIを順番に実施する。要修正なら修正と再レビューへ戻り、不要なら承認してマージする。 + + + PR作成 + 任意：AIレビューCopilot code review + 人間レビュー仕様・リスク判断 + CIテスト・静的解析 + 要修正？ + 修正・再レビュー + 承認・マージ + いいえはい + +
図7.1：AIレビューを補助として使い、人間の仕様・リスク判断とCIを必須の品質ゲートとして組み合わせるハイブリッドレビュー。
+
### レビュー優先順位の設定 diff --git a/docs/chapters/chapter09/index.md b/docs/chapters/chapter09/index.md index 1e22703..143f705 100644 --- a/docs/chapters/chapter09/index.md +++ b/docs/chapters/chapter09/index.md @@ -630,18 +630,22 @@ class ReviewBot: ### 組織からリポジトリへの権限継承 #### 継承の仕組み -```mermaid -graph TD - A[Organization Owner] --> B[Organization Member] - B --> C[Team Member] - C --> D[Repository Access] - - A --> E[Direct Repository Admin] - E --> D - - C --> F[Team Repository Permission] - F --> D -``` +
+ + 組織からリポジトリへの権限継承 + Organization OwnerからOrganization Member、Team Member、Repository Accessへ継承する経路と、直接のRepository AdminおよびTeam Repository PermissionからRepository Accessへ到達する経路。 + + + Organization Owner + Organization Member + Team Member + Direct Repository Admin + Team RepositoryPermission + Repository Access + + +
図9.1：組織、チーム、直接付与の経路からリポジトリ権限へ至る関係。実効権限は組織ポリシーとリポジトリ設定も併せて確認する。
+
### 権限の優先順位 diff --git a/docs/chapters/chapter12/index.md b/docs/chapters/chapter12/index.md index 3c1530c..bbcebe9 100644 --- a/docs/chapters/chapter12/index.md +++ b/docs/chapters/chapter12/index.md @@ -136,43 +136,22 @@ image-classification/ - `hotfix/`（本番障害対応。第11章とセット） #### ML開発向けGit Flow -```mermaid -gitGraph - commit id: "Initial" - branch develop - checkout develop - commit id: "Setup" - - branch feature/data-pipeline - checkout feature/data-pipeline - commit id: "Add loader" - commit id: "Add augmentation" - checkout develop - merge feature/data-pipeline - - branch experiment/resnet50 - checkout experiment/resnet50 - commit id: "ResNet50 base" - commit id: "Tune hyperparams" - - branch experiment/efficientnet - checkout experiment/efficientnet - commit id: "EfficientNet base" - commit id: "Optimize" - - checkout develop - merge experiment/resnet50 - - branch release/v1.0 - checkout release/v1.0 - commit id: "Prepare release" - - checkout main - merge release/v1.0 tag: "v1.0" - - checkout develop - merge release/v1.0 -``` +
+ + ML開発向けGit Flow + mainからdevelopを作成する。data pipelineのfeatureブランチ、ResNet50とEfficientNetのexperimentブランチをdevelopから分岐する。採用した実験をdevelopへ統合し、release v1.0をmainへマージしてタグ付けし、developへ戻す流れ。 + + + mainInitialv1.0 + developSetup + feature/data-pipelineloader・augmentation + experiment/resnet50base・tuning + experiment/efficientnetbase・optimize + release/v1.0Prepare release + + +
図12.1：ML開発向けGit Flow。実験ブランチをdevelopから分岐し、採用した実験だけを統合してrelease経由でmainへリリースする。
+
### rulesets と merge queue を前提にした統制 diff --git a/docs/index.md b/docs/index.md index 0c9ad17..56f503d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -195,6 +195,8 @@ ChatGPT/GitHub Copilot/Claude等のAI開発者ツールとGitHubを統合した #### [付録E：便利なGitエイリアス集](appendices/appendix-e/) #### [付録F：推奨VS Code拡張機能](appendices/appendix-f/) #### [付録G：参考資料](appendices/appendix-g/) +#### [独立チェックリスト集](appendices/checklist-pack/) +#### [図表索引](appendices/figure-index/) ### あとがき diff --git a/package.json b/package.json index d94e0ae..d716b5e 100644 --- a/package.json +++ b/package.json @@ -19,11 +19,12 @@ "deploy": "bash scripts/deploy.sh", "clean": "rm -rf _site public output temp", "lint:light": "markdownlint --config .markdownlint-src.json 'src/**/*.md' --ignore node_modules", - "test:light": "npm run check:security && npm run check:metadata && npm run lint:light && npm run build", + "test:light": "npm run check:security && npm run check:metadata && npm run check:issue-240-ux && npm run lint:light && npm run build", "help": "echo 'Available commands:\n npm run setup - Interactive setup\n npm run build - Build the book\n npm run preview - Local preview\n npm run deploy - Deploy to GitHub Pages'", "build:generate": "node scripts/build-simple.js", "check:metadata": "node scripts/check-metadata-consistency.js", - "check:security": "npm audit" + "check:security": "npm audit", + "check:issue-240-ux": "node scripts/check-issue-240-ux.js" }, "dependencies": { "fs-extra": "^11.3.5", diff --git a/scripts/check-issue-240-ux.js b/scripts/check-issue-240-ux.js new file mode 100755 index 0000000..9587638 --- /dev/null +++ b/scripts/check-issue-240-ux.js @@ -0,0 +1,119 @@ +#!/usr/bin/env node + +const fs = require('fs'); +const path = require('path'); +const errors = []; +const routes = ['/appendices/checklist-pack/', '/appendices/figure-index/']; +const figures = [ + ['chapter01', 'figure-chapter01-repository-sync', '図1.1：ローカルとリモートの同期'], + ['chapter05', 'figure-chapter05-repository-visibility', '図5.1：Public / Privateリポジトリの判断フロー'], + ['chapter07', 'figure-chapter07-hybrid-review-flow', '図7.1：ハイブリッドレビューワークフロー'], + ['chapter09', 'figure-chapter09-permission-inheritance', '図9.1：組織からリポジトリへの権限継承'], + ['chapter12', 'figure-chapter12-ml-git-flow', '図12.1：ML開発向けGit Flow'] +]; + +const read = (file) => { + try { return fs.readFileSync(file, 'utf8'); } + catch (error) { errors.push(`${file}: read failed (${error.message})`); return ''; } +}; +const expect = (condition, message) => { if (!condition) errors.push(message); }; +const normalize = (content) => content.replace(/\r\n/g, '\n'); +const stripFrontMatter = (content) => normalize(content).replace(/^---\n[\s\S]*?\n---\n/, ''); + +let config = {}; +try { + config = JSON.parse(read('book-config.json')); +} catch (error) { + errors.push(`book-config.json: JSON parse failed (${error.message})`); +} +expect(config.ux?.modules?.checklistPack === true, 'book-config.json: checklistPack must be true'); +expect(config.ux?.modules?.figureIndex === true, 'book-config.json: figureIndex must be true'); + +const navigation = read('docs/_data/navigation.yml'); +const top = read('docs/index.md'); +for (const route of routes) { + expect(fs.existsSync(path.join('docs', route.slice(1), 'index.md')), `missing public canonical route ${route}`); + expect(fs.existsSync(path.join('src', route.slice(1), 'index.md')), `missing source canonical route ${route}`); + expect(navigation.includes(`path: ${route}`), `navigation is missing ${route}`); + expect(top.includes(`](${route.slice(1)})`), `top page is missing ${route}`); +} +const appendixG = navigation.indexOf('path: /appendices/appendix-g/'); +const checklist = navigation.indexOf('path: /appendices/checklist-pack/'); +const figureIndexRoute = navigation.indexOf('path: /appendices/figure-index/'); +const afterword = navigation.indexOf('afterword:'); +expect(appendixG >= 0 && appendixG < checklist && checklist < figureIndexRoute && figureIndexRoute < afterword, + 'new routes must follow appendix G and precede afterword'); +expect((navigation.match(/path: \/appendices\/checklist-pack\//g) || []).length === 1, + 'checklist-pack route must occur exactly once in navigation'); +expect((navigation.match(/path: \/appendices\/figure-index\//g) || []).length === 1, + 'figure-index route must occur exactly once in navigation'); + +const publicFigureIndex = read('docs/appendices/figure-index/index.md'); +const sourceFigureIndex = read('src/appendices/figure-index/index.md'); +expect(stripFrontMatter(publicFigureIndex) === stripFrontMatter(sourceFigureIndex), + 'source and public figure indexes must have matching bodies'); +const expectedIndexEntries = figures.map(([chapter, id, title], index) => + `${index + 1}. [${title}](../../chapters/${chapter}/#${id})`); +const actualIndexEntries = publicFigureIndex.match(/^\d+\. \[[^\]]+\]\([^)]+\).*$/gm) || []; +expect(JSON.stringify(actualIndexEntries.map((line) => line.split(' — ')[0])) === JSON.stringify(expectedIndexEntries), + 'figure index must contain the exact five entries in source order with contracted deep links'); +expect(!/(?:favicon|badge|logo|screenshot)/i.test(actualIndexEntries.join('\n')), + 'figure index must not include UI assets or screenshot examples'); + +const allPublicMarkdown = []; +for (const [chapter, id] of figures) { + const publicFile = `docs/chapters/${chapter}/index.md`; + const sourceFile = `src/chapters/${chapter}/index.md`; + const publicContent = read(publicFile); + const sourceContent = read(sourceFile); + allPublicMarkdown.push(publicContent); + const pattern = new RegExp(`
`); + const publicMatch = publicContent.match(pattern); + const sourceMatch = sourceContent.match(pattern); + expect(Boolean(publicMatch), `${publicFile}: missing stable figure ${id}`); + expect(Boolean(sourceMatch), `${sourceFile}: missing stable figure ${id}`); + expect(Boolean(publicMatch && sourceMatch) && normalize(publicMatch[0]) === normalize(sourceMatch[0]), + `${chapter}: source/public figure blocks must match`); + if (publicMatch) { + for (const value of ['']) { + expect(publicMatch[0].includes(value), `${publicFile}: ${id} lacks ${value}`); + } + } + expect(!publicContent.includes('```mermaid'), `${publicFile}: Mermaid must be removed`); + expect(!sourceContent.includes('```mermaid'), `${sourceFile}: Mermaid must be removed`); +} +const publicFigureIds = allPublicMarkdown.join('\n').match(/
= 21, 'checklist pack must contain at least 21 actionable checks'); +expect(checklistItems.every((item) => item.includes('根拠:') && /\.\.\/\.\.\/chapters\/chapter\d{2}\//.test(item)), + 'every checklist item must link to at least one grounding chapter'); +expect(publicChecklist.includes('実施済み項目ではありません'), + 'checklist pack must distinguish repository examples from completed checks'); + +const hasMobileFigureCss = (content) => + content.includes('.book-figure:not(.book-figure--narrow)') && content.includes('min-width: 720px'); +const publicCss = read('docs/assets/css/main.css'); +const sourceCss = read('templates/styles/main.css'); +expect(hasMobileFigureCss(publicCss), + 'public mobile figure CSS must preserve text readability with a horizontal scroll viewport'); +expect(hasMobileFigureCss(sourceCss), + 'generated stylesheet source must preserve the mobile figure horizontal scroll contract'); +const workflow = read('.github/workflows/book-qa.yml'); +expect(workflow.includes('node scripts/check-issue-240-ux.js'), + 'Book QA must execute the Issue #240 UX contract'); + +if (errors.length) { + console.error('Issue #240 UX contract failed:'); + errors.forEach((error) => console.error(`- ${error}`)); + process.exit(1); +} +console.log('Issue #240 UX contract passed.'); diff --git a/scripts/check-metadata-consistency.js b/scripts/check-metadata-consistency.js index 0e7971d..a6e6930 100755 --- a/scripts/check-metadata-consistency.js +++ b/scripts/check-metadata-consistency.js @@ -24,7 +24,11 @@ const EXPECTED = { const EXPECTED_NAV = { introduction: ['/introduction/'], chapters: Array.from({ length: 17 }, (_, i) => `/chapters/chapter${String(i + 1).padStart(2, '0')}/`), - appendices: ['a', 'b', 'c', 'd', 'e', 'f', 'g'].map((letter) => `/appendices/appendix-${letter}/`), + appendices: [ + ...['a', 'b', 'c', 'd', 'e', 'f', 'g'].map((letter) => `/appendices/appendix-${letter}/`), + '/appendices/checklist-pack/', + '/appendices/figure-index/' + ], afterword: ['/afterword/'] }; diff --git a/src/appendices/checklist-pack/index.md b/src/appendices/checklist-pack/index.md new file mode 100644 index 0000000..9a3a568 --- /dev/null +++ b/src/appendices/checklist-pack/index.md @@ -0,0 +1,57 @@ +--- +layout: book +title: "独立チェックリスト集" +--- + +# 独立チェックリスト集 + +この付録は、章内に点在する確認事項を実運用の目的別に再編したものです。各項目は未実施の確認作業として扱います。章内のコードブロックや設定例は、実施済みを示すものではありません。 + +## 準備 + +- [ ] 対象リポジトリ、責任者、利用するGitHubアカウントまたは組織を確認した。根拠: [第1章](../../chapters/chapter01/)、[第5章](../../chapters/chapter05/) +- [ ] Gitのユーザー設定、認証方法、必要な開発環境をプロジェクトのルールに合わせた。根拠: [第3章](../../chapters/chapter03/) +- [ ] 機密情報、学習データ、ライセンスの扱いを公開前に確認した。根拠: [第5章](../../chapters/chapter05/)、[第17章](../../chapters/chapter17/)、[付録G](../appendix-g/) + +## Issue と計画 + +- [ ] Issueに目的、受入基準、制約、変更禁止領域を記録した。根拠: [第2章](../../chapters/chapter02/)、[第4章](../../chapters/chapter04/) +- [ ] 影響範囲、検証方法、ロールバック方針を作業開始前に合意した。根拠: [第2章](../../chapters/chapter02/)、[第11章](../../chapters/chapter11/) +- [ ] AI支援を使う場合は、入力可能な情報と人間の確認責任を明確にした。根拠: [第2章](../../chapters/chapter02/)、[第6章](../../chapters/chapter06/) + +## ブランチとコミット + +- [ ] 変更目的に対応する短命ブランチを作成し、mainへの直接変更を避けた。根拠: [第1章](../../chapters/chapter01/)、[第12章](../../chapters/chapter12/) +- [ ] コミットをレビュー可能な単位に分け、意図と検証結果を説明できる状態にした。根拠: [第1章](../../chapters/chapter01/)、[第3章](../../chapters/chapter03/) +- [ ] 実験、release、不要になったブランチの扱いをチームで定義した。根拠: [第12章](../../chapters/chapter12/) + +## Pull Request とレビュー + +- [ ] PRに変更内容、影響範囲、検証、ロールバック、AI利用の有無を記載した。根拠: [第2章](../../chapters/chapter02/)、[第7章](../../chapters/chapter07/) +- [ ] 人間が仕様、リスク、セキュリティ上の判断を確認し、AIレビューだけで承認しない。根拠: [第7章](../../chapters/chapter07/) +- [ ] CODEOWNERS、必須レビュアー、承認条件が対象変更に適用されることを確認した。根拠: [第9章](../../chapters/chapter09/) + +## CI/CD + +- [ ] 必須テスト、静的解析、依存関係確認をPRの品質ゲートとして実行した。根拠: [第7章](../../chapters/chapter07/)、[第13章](../../chapters/chapter13/) +- [ ] デプロイ対象環境、承認者、Secretsの参照範囲を確認した。根拠: [第11章](../../chapters/chapter11/)、[第13章](../../chapters/chapter13/) +- [ ] 失敗時の停止、再実行、ロールバックの手順を検証可能な形で残した。根拠: [第11章](../../chapters/chapter11/)、[付録B](../appendix-b/) + +## セキュリティ + +- [ ] トークン、パスワード、個人情報、機密データをコード、ログ、Issue、PRへ含めていない。根拠: [第8章](../../chapters/chapter08/)、[第11章](../../chapters/chapter11/) +- [ ] 入力検証、認証・認可、依存関係更新、破壊的変更のリスクを確認した。根拠: [第7章](../../chapters/chapter07/)、[第8章](../../chapters/chapter08/) +- [ ] Secret scanning、code scanning、dependency reviewの結果を確認し、例外があれば記録した。根拠: [第8章](../../chapters/chapter08/) + +## 組織・大規模運用 + +- [ ] 組織、チーム、リポジトリの権限継承と直接付与を監査した。根拠: [第9章](../../chapters/chapter09/)、[第10章](../../chapters/chapter10/) +- [ ] Outside Collaborator、SAML SSO、監査ログの運用を組織ポリシーと照合した。根拠: [第10章](../../chapters/chapter10/) +- [ ] 大規模データ、モデル、外部協力者、コンプライアンスの責任分界を確認した。根拠: [第14章](../../chapters/chapter14/)、[第16章](../../chapters/chapter16/)、[第17章](../../chapters/chapter17/) + +## 関連資料 + +次の資料はリポジトリ内の導入例であり、この公開チェックリストの実施済み項目ではありません。対象リポジトリの公開範囲と運用文脈を確認したうえで参照してください。 + +- — AIエージェント向けSecurity checklist: AIレビューの見落としを前提に人間が確認する最小例。 +- — self-hosted runner運用チェックリスト: trusted input、runner分離、ephemeral運用を扱う導入例。 diff --git a/src/appendices/figure-index/index.md b/src/appendices/figure-index/index.md new file mode 100644 index 0000000..886136d --- /dev/null +++ b/src/appendices/figure-index/index.md @@ -0,0 +1,16 @@ +--- +layout: book +title: "図表索引" +--- + +# 図表索引 + +この索引は、本書の公開本文に掲載する自己完結SVG図版のexact inventoryです。スクリーンショット用コード例、badge、favicon、logoは含めません。 + +1. [図1.1：ローカルとリモートの同期](../../chapters/chapter01/#figure-chapter01-repository-sync) — 作業ディレクトリ、ステージング、ローカルリポジトリ、GitHubの同期。 +2. [図5.1：Public / Privateリポジトリの判断フロー](../../chapters/chapter05/#figure-chapter05-repository-visibility) — 公開制約と公開目的に基づく可視性の選択。 +3. [図7.1：ハイブリッドレビューワークフロー](../../chapters/chapter07/#figure-chapter07-hybrid-review-flow) — AIレビュー、人間レビュー、CIの品質ゲート。 +4. [図9.1：組織からリポジトリへの権限継承](../../chapters/chapter09/#figure-chapter09-permission-inheritance) — Organization、Team、Repositoryの権限経路。 +5. [図12.1：ML開発向けGit Flow](../../chapters/chapter12/#figure-chapter12-ml-git-flow) — feature、experiment、releaseを含む統合フロー。 + +各リンクは該当する`figure`要素のstable anchorへ直接移動します。図版はJavaScriptを必要とせず、SVG内のtitleと説明、captionを備えます。 diff --git a/src/chapters/chapter01/index.md b/src/chapters/chapter01/index.md index 35a0255..63ba064 100644 --- a/src/chapters/chapter01/index.md +++ b/src/chapters/chapter01/index.md @@ -144,17 +144,24 @@ main ### 同期の仕組み -```mermaid -graph LR - A[作業ディレクトリ] -->|add| B[ステージングエリア] - B -->|commit| C[ローカルリポジトリ] - C <-->|push/pull| D[リモートリポジトリ

GitHub] - - style A fill:#f9f9f9,stroke:#333,stroke-width:2px - style B fill:#e1f5e1,stroke:#333,stroke-width:2px - style C fill:#e1e5f5,stroke:#333,stroke-width:2px - style D fill:#ffe1e1,stroke:#333,stroke-width:2px -``` + +
+ + ローカルとリモートの同期 + 作業ディレクトリからステージングエリア、ローカルリポジトリへ進み、ローカルリポジトリとGitHub上のリモートリポジトリをpushとpullで双方向に同期する流れ。 + + + 作業ディレクトリ + ステージングエリア + ローカルリポジトリ + リモートリポジトリ（GitHub） + add + commit + pushpull + +
図1.1：ローカル作業からGitHub上のリモートリポジトリまでの同期。矢印のラベルは実行するGit操作を示す。
+
+ ### リモートブランチの追跡 - ローカルブランチとリモートブランチの対応 diff --git a/src/chapters/chapter05/index.md b/src/chapters/chapter05/index.md index a8d7c26..3ee8d4c 100644 --- a/src/chapters/chapter05/index.md +++ b/src/chapters/chapter05/index.md @@ -147,30 +147,36 @@ policies: ### AI協働を含む判断フローチャート -```mermaid -flowchart TD - A[リポジトリ作成] --> B{機密情報を含むか？} - B -->|Yes| C[Private] - B -->|No| D{AI生成コードの
知的財産権が懸念されるか？} - D -->|Yes| E[Private + AI使用ポリシー明記] - D -->|No| F{特許や独自アルゴリズムを含むか？} - F -->|Yes| G[Private] - F -->|No| H{オープンソースとして
公開する意図があるか？} - H -->|Yes| I[Public + AI協働の明示] - H -->|No| J{AI協働の学習事例として
共有したいか？} - J -->|Yes| K[Public + AI協働ドキュメント] - J -->|No| L{教育目的や
ポートフォリオか？} - L -->|Yes| M[Public] - L -->|No| N[Private] - - style C fill:#ffcccc - style E fill:#ffcccc - style G fill:#ffcccc - style N fill:#ffcccc - style I fill:#ccffcc - style K fill:#ccffcc - style M fill:#ccffcc -``` + +
+ + PublicとPrivateリポジトリの判断 + 機密情報、AI生成コードの知的財産権、特許・独自アルゴリズム、オープンソース公開の意図、AI協働の学習事例共有、教育・ポートフォリオの順に確認する。各質問のはい側でPrivateまたは目的別のPublicを選び、すべていいえの場合はPrivateを選ぶ判断フロー。 + + + リポジトリ作成 + 機密情報を含むか？ + Privateはい + いいえ + AI生成コードの知的財産権が懸念されるか？ + Private＋AI使用ポリシーはい + いいえ + 特許や独自アルゴリズムを含むか？ + Privateはい + いいえ + オープンソースとして公開する意図があるか？ + Public＋AI協働の明示はい + いいえ + AI協働の学習事例として共有したいか？ + Public＋AI協働文書はい + いいえ + 教育目的またはポートフォリオか？ + Publicはい + いいえPrivate + +
図5.1：Public / Private リポジトリの判断フロー。機密性、知的財産、公開意図、共有・教育目的を順に確認し、公開時はAI協働の方針を明示する。
+
+ ### Publicリポジトリの利点 - **コミュニティ貢献**: オープンソースエコシステムへの参加 diff --git a/src/chapters/chapter07/index.md b/src/chapters/chapter07/index.md index c5bd4a2..f6ad869 100644 --- a/src/chapters/chapter07/index.md +++ b/src/chapters/chapter07/index.md @@ -233,16 +233,25 @@ def calculate_metrics(y_true, y_pred, threshold=0.5): ### ハイブリッドレビューワークフロー -```mermaid -graph LR - A[PR作成] --> B[AI自動レビュー] - B --> C{重大な問題?} - C -->|Yes| D[自動ブロック] - C -->|No| E[人間レビュー待ち] - E --> F[人間がAIコメント確認] - F --> G[追加レビュー] - G --> H[承認/要修正] -``` + +
+ + ハイブリッドレビューワークフロー + PR作成後、任意のAIレビュー、人間による仕様とリスクのレビュー、CIを順番に実施する。要修正なら修正と再レビューへ戻り、不要なら承認してマージする。 + + + PR作成 + 任意：AIレビューCopilot code review + 人間レビュー仕様・リスク判断 + CIテスト・静的解析 + 要修正？ + 修正・再レビュー + 承認・マージ + いいえはい + +
図7.1：AIレビューを補助として使い、人間の仕様・リスク判断とCIを必須の品質ゲートとして組み合わせるハイブリッドレビュー。
+
+ ### レビュー優先順位の設定 diff --git a/src/chapters/chapter09/index.md b/src/chapters/chapter09/index.md index c2d1e30..c58d1d1 100644 --- a/src/chapters/chapter09/index.md +++ b/src/chapters/chapter09/index.md @@ -586,18 +586,24 @@ class ReviewBot: ### 組織からリポジトリへの権限継承 #### 継承の仕組み -```mermaid -graph TD - A[Organization Owner] --> B[Organization Member] - B --> C[Team Member] - C --> D[Repository Access] - - A --> E[Direct Repository Admin] - E --> D - - C --> F[Team Repository Permission] - F --> D -``` + +
+ + 組織からリポジトリへの権限継承 + Organization OwnerからOrganization Member、Team Member、Repository Accessへ継承する経路と、直接のRepository AdminおよびTeam Repository PermissionからRepository Accessへ到達する経路。 + + + Organization Owner + Organization Member + Team Member + Direct Repository Admin + Team RepositoryPermission + Repository Access + + +
図9.1：組織、チーム、直接付与の経路からリポジトリ権限へ至る関係。実効権限は組織ポリシーとリポジトリ設定も併せて確認する。
+
+ ### 権限の優先順位 diff --git a/src/chapters/chapter12/index.md b/src/chapters/chapter12/index.md index d6acc97..e537134 100644 --- a/src/chapters/chapter12/index.md +++ b/src/chapters/chapter12/index.md @@ -107,43 +107,24 @@ image-classification/ ### ブランチ戦略 #### ML開発向けGit Flow -```mermaid -gitGraph - commit id: "Initial" - branch develop - checkout develop - commit id: "Setup" - - branch feature/data-pipeline - checkout feature/data-pipeline - commit id: "Add loader" - commit id: "Add augmentation" - checkout develop - merge feature/data-pipeline - - branch experiment/resnet50 - checkout experiment/resnet50 - commit id: "ResNet50 base" - commit id: "Tune hyperparams" - - branch experiment/efficientnet - checkout experiment/efficientnet - commit id: "EfficientNet base" - commit id: "Optimize" - - checkout develop - merge experiment/resnet50 - - branch release/v1.0 - checkout release/v1.0 - commit id: "Prepare release" - - checkout main - merge release/v1.0 tag: "v1.0" - - checkout develop - merge release/v1.0 -``` + +
+ + ML開発向けGit Flow + mainからdevelopを作成する。data pipelineのfeatureブランチ、ResNet50とEfficientNetのexperimentブランチをdevelopから分岐する。採用した実験をdevelopへ統合し、release v1.0をmainへマージしてタグ付けし、developへ戻す流れ。 + + + mainInitialv1.0 + developSetup + feature/data-pipelineloader・augmentation + experiment/resnet50base・tuning + experiment/efficientnetbase・optimize + release/v1.0Prepare release + + +
図12.1：ML開発向けGit Flow。実験ブランチをdevelopから分岐し、採用した実験だけを統合してrelease経由でmainへリリースする。
+
+ ### 実装例 diff --git a/templates/styles/main.css b/templates/styles/main.css index 89d1154..5f227d7 100644 --- a/templates/styles/main.css +++ b/templates/styles/main.css @@ -353,6 +353,23 @@ img { box-shadow: var(--shadow-md); } +.book-figure { + margin: 1.5rem 0; +} + +@media (max-width: 640px) { + .book-figure:not(.book-figure--narrow) { + overflow-x: auto; + overscroll-behavior-inline: contain; + padding-bottom: 0.5rem; + } + + .book-figure:not(.book-figure--narrow) > svg { + min-width: 720px; + max-width: none !important; + } +} + /* Responsive Design */ @media (max-width: 768px) { :root { @@ -444,4 +461,4 @@ img { pre, blockquote { page-break-inside: avoid; } -} \ No newline at end of file +}