Skip to content

Commit 794fbca

Browse files
ootakazuhikoootakazuhiko
authored
Issue #194: Agent-ready整合性改善 (#195)
* Issue #194: AGENTS追加とbidi検出/CI整合 * Issue #194: テンプレ/CODEOWNERS/章7-8の整合
1 parent ffdc24e commit 794fbca

10 files changed

Lines changed: 435 additions & 59 deletions

File tree

‎.github/CODEOWNERS‎

Lines changed: 17 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,21 @@
1-
# CODEOWNERS (standardized for book repos)
2-
# 共同フォーマッタ資産・下部ナビ共通インクルード
3-
/book-formatter-contrib/** @itdojp/book-formatter
4-
/docs/_includes/page-navigation.html @itdojp/book-formatter
1+
# CODEOWNERS
2+
#
3+
# NOTE:
4+
# - Order matters. The last matching pattern takes precedence.
5+
# - 本文の正（Single Source of Truth）は `manuscript/**`。
56

6-
# 本文（GitHub Pages）
7-
/docs/src/** @itdojp/book-editors
8-
/docs/index.md @itdojp/book-editors
7+
# Default owners (repo-wide)
8+
* @itdojp/book-editors
99

10-
# 書籍の元原稿（必要なら運用）
11-
/src/** @itdojp/book-editors
10+
# GitHub Pages（公開サイト）
11+
/docs/** @itdojp/book-editors
1212

13-
# 上記以外（コンテンツ/設定/CI含む全般）
13+
# 共同フォーマッタ資産・下部ナビ共通インクルード
14+
/.book-formatter/** @itdojp/book-formatter
15+
/docs/_includes/page-navigation.html @itdojp/book-formatter
1416

15-
/.book-formatter/** @itdojp/book-formatter
16-
* @itdojp/book-editors
17+
# 本文（正）
18+
/manuscript/** @itdojp/book-editors
19+
20+
# 書籍の元原稿（互換/残骸。必要な場合のみ運用）
21+
/src/** @itdojp/book-editors

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,39 @@ body:
4747
validations:
4848
required: true
4949

50+
- type: textarea
51+
id: acceptance
52+
attributes:
53+
label: 受入基準（任意）
54+
description: 修正が完了したと判断できる条件（チェック可能な形）を記載してください
55+
placeholder: |
56+
- [ ] ...
57+
- [ ] ...
58+
validations:
59+
required: false
60+
61+
- type: textarea
62+
id: constraints
63+
attributes:
64+
label: 制約・変更禁止領域（任意）
65+
description: 触ってはいけないファイル/設定や制約があれば明記してください
66+
placeholder: |
67+
- 変更してよい:
68+
- 変更してはいけない:
69+
validations:
70+
required: false
71+
72+
- type: textarea
73+
id: test
74+
attributes:
75+
label: テスト方法（任意）
76+
description: 最低限の確認コマンドや手動確認手順を書いてください
77+
placeholder: |
78+
- コマンド:
79+
- 手動確認:
80+
validations:
81+
required: false
82+
5083
- type: textarea
5184
id: environment
5285
attributes:
@@ -67,4 +100,3 @@ body:
67100
description: スクリーンショット、関連リンク、原因の見当など
68101
validations:
69102
required: false
70-

‎.github/ISSUE_TEMPLATE/docs_change.yml‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,11 +33,43 @@ body:
3333
validations:
3434
required: true
3535

36+
- type: textarea
37+
id: acceptance
38+
attributes:
39+
label: 受入基準（DoD）
40+
description: 変更が完了したと判断できる条件を、チェック可能な形で箇条書きにしてください
41+
placeholder: |
42+
- [ ] （例）誤字が修正されている
43+
- [ ] （例）リンク先が有効で、意図したページに到達する
44+
validations:
45+
required: true
46+
47+
- type: textarea
48+
id: constraints
49+
attributes:
50+
label: 制約・変更禁止領域（任意）
51+
description: 触ってはいけないファイル/設定や、変更方針の制約があれば明記してください
52+
placeholder: |
53+
- 変更してよい:
54+
- 変更してはいけない:
55+
validations:
56+
required: false
57+
58+
- type: textarea
59+
id: test
60+
attributes:
61+
label: テスト方法（任意）
62+
description: 最低限の確認コマンドや手動確認手順（例：CI/リンク確認）を書いてください
63+
placeholder: |
64+
- コマンド:
65+
- 手動確認:
66+
validations:
67+
required: false
68+
3669
- type: textarea
3770
id: additional
3871
attributes:
3972
label: 補足（任意）
4073
description: スクリーンショット、関連Issue/PR、参考リンクなど
4174
validations:
4275
required: false
43-

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,51 @@ body:
2525
validations:
2626
required: true
2727

28+
- type: textarea
29+
id: acceptance
30+
attributes:
31+
label: 受入基準（DoD）
32+
description: 変更が完了したと判断できる条件を、チェック可能な形で箇条書きにしてください
33+
placeholder: |
34+
- [ ] ...
35+
- [ ] ...
36+
validations:
37+
required: true
38+
39+
- type: textarea
40+
id: nonfunctional
41+
attributes:
42+
label: 非機能要件（任意）
43+
description: 性能/セキュリティ/互換性など、必要があれば記載してください
44+
placeholder: |
45+
- セキュリティ:
46+
- 互換性:
47+
- 性能:
48+
validations:
49+
required: false
50+
51+
- type: textarea
52+
id: constraints
53+
attributes:
54+
label: 制約・変更禁止領域（任意）
55+
description: 触ってはいけないファイル/設定や、変更方針の制約があれば明記してください
56+
placeholder: |
57+
- 変更してよい:
58+
- 変更してはいけない:
59+
validations:
60+
required: false
61+
62+
- type: textarea
63+
id: test
64+
attributes:
65+
label: テスト方法（任意）
66+
description: 最低限の確認コマンドや手動確認手順を書いてください
67+
placeholder: |
68+
- コマンド:
69+
- 手動確認:
70+
validations:
71+
required: false
72+
2873
- type: textarea
2974
id: scope
3075
attributes:
@@ -48,4 +93,3 @@ body:
4893
description: 参考リンク、画面例、関連Issue/PRなど
4994
validations:
5095
required: false
51-

‎.github/workflows/book-qa.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@ jobs:
1616
- name: Checkout book
1717
uses: actions/checkout@v4
1818

19+
- name: Bidi/hidden Unicode check (tracked files)
20+
run: python3 scripts/check_bidi_unicode.py
21+
1922
- name: Checkout book-formatter (pinned)
2023
uses: actions/checkout@v4
2124
with:

‎.github/workflows/docs-quality-gate.yml‎

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,28 @@ on:
44
pull_request:
55
paths:
66
- "docs/**"
7+
- "manuscript/**"
78
- ".github/**"
89
- "scripts/**"
910
- "package.json"
11+
- "AI_USAGE_POLICY.md"
12+
- "AGENTS.md"
13+
- "CONTRIBUTING.md"
14+
- "UPDATE_POLICY.md"
15+
- "README.md"
1016
push:
1117
branches: [main]
1218
paths:
1319
- "docs/**"
20+
- "manuscript/**"
1421
- ".github/**"
1522
- "scripts/**"
1623
- "package.json"
24+
- "AI_USAGE_POLICY.md"
25+
- "AGENTS.md"
26+
- "CONTRIBUTING.md"
27+
- "UPDATE_POLICY.md"
28+
- "README.md"
1729
workflow_dispatch: {}
1830

1931
jobs:
@@ -33,7 +45,7 @@ jobs:
3345
- name: Install dependencies
3446
run: npm ci --no-fund --no-audit
3547

36-
- name: Collect changed Markdown files (docs/)
48+
- name: Collect changed Markdown files (docs/manuscript/etc)
3749
id: changes
3850
shell: bash
3951
run: |
@@ -55,16 +67,16 @@ jobs:
5567
fi
5668
5769
if [ "${invalid_base}" = true ]; then
58-
echo "Base SHA is invalid or unavailable; falling back to all tracked docs markdown files."
59-
git ls-files docs | grep -E '\.md$' > changed-docs-md.txt || true
70+
echo "Base SHA is invalid or unavailable; falling back to all tracked markdown files under target paths."
71+
git ls-files docs manuscript .github AI_USAGE_POLICY.md AGENTS.md CONTRIBUTING.md UPDATE_POLICY.md README.md | grep -E '\.md$' > changed-md.txt || true
6072
else
61-
# Exclude deleted files (e.g., moves out of docs/) to avoid lint/link-check failures on missing paths.
62-
git diff --name-only --diff-filter=ACMRT "$base" "$head" -- docs | grep -E '\.md$' > changed-docs-md.txt || true
73+
# Exclude deleted files to avoid lint/link-check failures on missing paths.
74+
git diff --name-only --diff-filter=ACMRT "$base" "$head" -- docs manuscript .github AI_USAGE_POLICY.md AGENTS.md CONTRIBUTING.md UPDATE_POLICY.md README.md | grep -E '\.md$' > changed-md.txt || true
6375
fi
6476
65-
echo "Changed docs markdown files:"
66-
if [ -s changed-docs-md.txt ]; then
67-
cat changed-docs-md.txt
77+
echo "Changed markdown files:"
78+
if [ -s changed-md.txt ]; then
79+
cat changed-md.txt
6880
else
6981
echo "(none)"
7082
fi
@@ -73,18 +85,18 @@ jobs:
7385
shell: bash
7486
run: |
7587
set -euo pipefail
76-
if [ ! -s changed-docs-md.txt ]; then
77-
echo "Skip: no docs markdown changes."
88+
if [ ! -s changed-md.txt ]; then
89+
echo "Skip: no markdown changes."
7890
exit 0
7991
fi
80-
cat changed-docs-md.txt | xargs -r npx markdownlint
92+
cat changed-md.txt | xargs -r npx markdownlint
8193
8294
- name: Internal link check (changed only)
8395
shell: bash
8496
run: |
8597
set -euo pipefail
86-
if [ ! -s changed-docs-md.txt ]; then
87-
echo "Skip: no docs markdown changes."
98+
if [ ! -s changed-md.txt ]; then
99+
echo "Skip: no markdown changes."
88100
exit 0
89101
fi
90-
cat changed-docs-md.txt | xargs -r python3 scripts/check_markdown_internal_links.py
102+
cat changed-md.txt | xargs -r python3 scripts/check_markdown_internal_links.py

‎AGENTS.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# AGENTS.md
2+
3+
このファイルは、Codex 等の AI/エージェントが本リポジトリで作業する際の「単一入口（Single Entry Point）」です。
4+
5+
## Single Source of Truth（正の原稿）
6+
7+
- **本文（正）**: `manuscript/**`
8+
- 章本文・図参照・章末チェック等は原則ここを編集します。
9+
- **公開サイト（GitHub Pages）**: `docs/**`
10+
- 互換や公開導線の都合で存在しますが、本文の正とは限りません。Issue で指示がない限り、本文改稿のために `docs/**` を直接編集しないでください。
11+
- **元原稿（互換/残骸）**: `src/**`
12+
- 過去の構造の名残です。原則編集対象外（必要な場合は Issue に理由を明記）。
13+
14+
## 変更禁止・注意事項（Must Not）
15+
16+
- **Secrets/個人情報/トークンを貼らない**
17+
- 例: API キー、PAT、秘密鍵、顧客情報、署名付き URL。
18+
- 詳細は `AI_USAGE_POLICY.md` を参照。
19+
- **生成物をコミットしない**
20+
- 例: `_site/`, `node_modules/`。
21+
- **大規模なリネームで互換性を壊さない**
22+
- slug 変更（ディレクトリ名変更）や URL 互換性に影響する改修は、別 Issue で計画して実施します。
23+
24+
## 必ず通すチェック（推奨）
25+
26+
最小セット（PR 作成前）:
27+
28+
- `npm ci`
29+
- 変更した Markdown に対して `npx markdownlint ...`
30+
- 変更した Markdown に対して `python3 scripts/check_markdown_internal_links.py ...`
31+
- Unicode 安全チェック: `python3 scripts/check_bidi_unicode.py`
32+
33+
CI の基準（必須）:
34+
35+
- GitHub Actions の `Book QA` が PASS
36+
- GitHub Actions の `Docs Quality Gate`（変更対象に応じて）が PASS
37+
38+
## hidden/bidirectional Unicode（再発防止）
39+
40+
差分に bidi 制御文字（不可視）が混入すると、レビュー時に見落としやすく、GitHub の表示警告対象になります。将来の自動処理（生成・変換・コピペ）でも事故要因になるため、CI で検出して失敗させます。
41+
42+
- 検出コマンド: `python3 scripts/check_bidi_unicode.py`（追跡ファイルを走査）
43+
- CI: `Book QA` で同チェックを実行
44+
45+
## PR/Issue 運用
46+
47+
- `.github/PULL_REQUEST_TEMPLATE.md` に従い、`Closes #xxx` を記載します。
48+
- `gh pr comment` / `gh issue comment` でコメント投稿する場合、Bash のバッククォート（コマンド置換）事故を避けるため、本文は **`--body-file`（`-F`）** で渡します（例は `AI_USAGE_POLICY.md`）。
49+
50+
## slug と章の対応（誤編集防止）
51+
52+
ディレクトリ名（slug）は、公開サイトの URL 互換や過去構造の名残により、章タイトルと一致しない場合があります。編集対象は「章タイトル」ではなく **ファイルパス（`manuscript/**`）** を基準に判断してください。
53+
54+
対応表（`manuscript/*/index.md` の `order` / `title` より）:
55+
56+
| パス（slug） | order | タイトル |
57+
| --- | ---: | --- |
58+
| `manuscript/chapter-introduction/` | 1 | 第1章：はじめに - なぜGitHubを学ぶのか |
59+
| `manuscript/chapter-git-basics/` | 2 | 第2章：Git基礎 - バージョン管理の仕組み |
60+
| `manuscript/chapter-github-account-setup/` | 3 | 第3章：初めてのリポジトリ作成 |
61+
| `manuscript/chapter-basic-operations/` | 4 | 第4章：アカウントセキュリティの基本 |
62+
| `manuscript/chapter-repository-management/` | 5 | 第5章：ファイルのアップロードと管理 |
63+
| `manuscript/chapter-collaboration-basics/` | 6 | 第6章：GitHub Desktop の活用 |
64+
| `manuscript/chapter-pull-requests/` | 7 | 第7章：ブランチの基本操作 |
65+
| `manuscript/chapter-issue-management/` | 8 | 第8章：Issue管理とプロジェクト管理 |
66+
| `manuscript/chapter-github-actions/` | 9 | 第9章：GitHub Actions入門 - 自動化の基礎 |
67+
| `manuscript/chapter-security-best-practices/` | 10 | 第10章：セキュリティのベストプラクティス |
68+
| `manuscript/chapter-advanced-features/` | 11 | 第11章：高度な機能活用 |
69+
| `manuscript/chapter-troubleshooting/` | 12 | 第12章：トラブルシューティング |
70+
| `manuscript/chapter-docs-as-code/` | 13 | 特別編：Docs-as-Code - GitHubをドキュメント管理・ナレッジ基盤として使う |
71+
| `manuscript/appendix-git-commands-reference/` | 100 | 付録A：Gitコマンドリファレンス |
72+
| `manuscript/appendix-github-shortcuts/` | 101 | 付録B：GitHubショートカット集 |
73+
| `manuscript/appendix-resources/` | 102 | 付録C：学習リソースと参考文献 |
74+
| `manuscript/chapter-security/` | 999 | 第10章：セキュリティ対策と安全なGitHub利用（互換/残骸。原則編集しない） |
75+
76+
slug 改名（ディレクトリ名変更）を行う場合は、公開サイトの既存 URL 互換（リダイレクト/リンク更新）と外部参照への影響を評価し、別 Issue で計画して段階的に実施します。

‎manuscript/chapter-issue-management/index.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,9 @@ Issueテンプレートが用意されているリポジトリでは、作成時
9999
- **トリアージがしやすい**：`bug` / `documentation` / `question` など、分類と初動が揃う
100100
- **やりとりの往復が減る**：「情報が足りないので聞き返す」回数が減り、解決が早くなる
101101

102-
このリポジトリでは例として、`bug` / `enhancement` / `documentation` / `question` のIssue Formsを `.github/ISSUE_TEMPLATE/` に同梱しています。自分のプロジェクトで使う場合は、まずは「バグ報告」と「ドキュメント改善」だけ導入するのがおすすめです。
102+
このリポジトリでは例として、`bug` / `enhancement` / `documentation` / `question` に対応する Issue Forms を `.github/ISSUE_TEMPLATE/` に同梱しています（例：`bug_report.yml` / `feature_request.yml` / `docs_change.yml` / `question.yml`）。
103+
104+
AI/エージェント支援で PR を作る前提の場合は、Issue の情報不足が運用事故や手戻りに直結します。最低限、**受入基準（DoD）**・**制約（変更禁止領域）**・**テスト方法** を埋める運用にすると安全です（本リポジトリのフォームにも同観点の欄を入れています）。
103105

104106
**Step 2: タイトルの設定**
105107

@@ -129,6 +131,9 @@ Issueテンプレートが用意されているリポジトリでは、作成時
129131
## 期待する動作
130132
メニューが画面内に収まって表示される
131133

134+
## 実際の動作
135+
メニューが画面外にはみ出し、右端が見切れる
136+
132137
## 環境情報
133138
- デバイス: iPhone 12
134139
- ブラウザ: Safari 15.0

0 commit comments

Comments
 (0)