Skip to content

feat: AGENTS.md 自動生成スクリプトを追加し repo-maintenance に組み込み #615

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
keito4 merged 3 commits into from
Mar 22, 2026
Merged

feat: AGENTS.md 自動生成スクリプトを追加し repo-maintenance に組み込み #615

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c1b2dff
feat: AGENTS.md 自動生成スクリプトを追加し repo-maintenance に組み込み
github-actions[bot] Mar 22, 2026
64b069b
fix: BATS テストを SHA 固定された actions に対応させる
github-actions[bot] Mar 22, 2026
3820347
fix: main マージのコンフリクトを解消し AGENTS.md を再生成
github-actions[bot] Mar 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 29 additions & 9 deletions .claude/commands/repo-maintenance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -807,22 +807,42 @@ echo "$AUTO_CONTENT" >> AGENTS.md
echo "$TAIL" >> AGENTS.md
```

**重要:** 上記のシェルスクリプトは参考ロジック。実際の実行は Claude Code が以下の手順で行う:
**実行スクリプト:** `script/update-agents-md.sh`

1. リポジトリの現在の状態を読み取る（コマンド、ワークフロー、スクリプト、フック）
2. 各セクションの内容を生成
3. AGENTS.md の `<!-- BEGIN AUTO-GENERATED -->` 〜 `<!-- END AUTO-GENERATED -->` 間を置換
4. `CLAUDE.md` が `AGENTS.md` へのシンボリックリンクであることを確認（Step 3.4 で実施済み）
このスクリプトは以下を自動収集し、マーカー間を置換する:

**Hooks の情報取得:**
1. Tech stack（`package.json` の engines、ロックファイルからパッケージマネージャー検出、`nix/flake.nix` の有無）
2. Project Structure（dot ディレクトリ + 通常ディレクトリを列挙し、既知のディレクトリには説明を付与）
3. Available Commands（`.claude/commands/*.md` の frontmatter description を取得）
4. CI/CD Workflows（`.github/workflows/*.yml` の `name:` を取得）
5. Quality Gates（`package.json` scripts から `format:check`, `lint`, `test`, `shellcheck`, `typecheck` 等を検出）
6. Hooks（`.claude/hooks/*.py` のファイル名からトリガーと目的を推定）
7. Development Standards（release-types ルール等の固定セクション）

`.claude/hooks/README.md` が存在する場合はそこから説明を取得。
存在しない場合はファイル名から推測（`pre_` = Pre trigger, `post_` = Post trigger, `block_` = Pre blocker, `stop_` = Stop trigger）。
生成後に Prettier でフォーマットし、冪等性を保証する。

**実行方法:**

```bash
# 更新を適用
bash script/update-agents-md.sh

# 差分チェックのみ（変更なし、差分があれば exit 1）
bash script/update-agents-md.sh --check
```

**MODE ごとの動作:**

| MODE | 動作 |
| ---------- | ------------------------------------------------------------ |
| full | `bash script/update-agents-md.sh` を実行し、差分があれば更新 |
| quick | `bash script/update-agents-md.sh --check` で差分を報告のみ |
| check-only | `bash script/update-agents-md.sh --check` で差分を報告のみ |

**結果:**

- ✅ AGENTS.md 自動生成セクション: 最新に更新済み
- 🔧 AGENTS.md 自動生成セクション: X 件のセクションを更新
- 🔧 AGENTS.md 自動生成セクション: 更新しました
- ⏭️ スキップ（AGENTS.md 未対応 / マーカーなし）

### 3.5 CI/CD Setup Check (full mode only)
Expand Down
117 changes: 59 additions & 58 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,14 +40,14 @@ Development infrastructure template repository providing DevContainer images, CI
| Directory | Purpose |
| -------------------- | ------------------------------------------------ |
| `.agents/` | AI agent skills and configurations |
| `.claude/commands/` | Claude Code slash commands (28 commands) |
| `.claude/commands/` | Claude Code slash commands |
| `.claude/hooks/` | Pre/post hook scripts for quality enforcement |
| `.claude/rules/` | Claude Code rules for development standards |
| `.codex/` | Codex AI agent configuration |
| `.cursor/` | Cursor editor settings |
| `.devcontainer/` | DevContainer configuration and Dockerfile |
| `.gemini/` | Gemini AI agent configuration |
| `.github/workflows/` | GitHub Actions CI/CD workflows (15 workflows) |
| `.github/workflows/` | GitHub Actions CI/CD workflows (20 workflows) |
| `.husky/` | Git hooks (pre-commit, commit-msg) |
| `.vscode/` | VS Code workspace settings |
| `brew/` | Homebrew package management (Linux only) |
Expand All @@ -56,6 +56,7 @@ Development infrastructure template repository providing DevContainer images, CI
| `dot/` | Dotfiles (DevContainer .zshrc, peco) |
| `eslint/` | ESLint configuration and plugins |
| `git/` | Git hooks and configuration |
| `next/` | Next.js project templates |
| `nix/` | nix-darwin + home-manager (macOS environment) |
| `npm/` | npm global configuration and library management |
| `script/` | Utility shell scripts |
Expand All @@ -65,84 +66,84 @@ Development infrastructure template repository providing DevContainer images, CI

## Available Commands

| Command | Description |
| ------------------------------- | ------------------------------------------------------------------------ |
| `/repo-maintenance` | Comprehensive repository maintenance - run all health checks and updates |
| `/setup-new-repo` | Setup new repository with DevContainer, CI/CD, and development tools |
| `/setup-ci` | Setup comprehensive CI/CD workflows |
| `/setup-tests` | Setup comprehensive testing infrastructure for Next.js projects |
| `/setup-husky` | Husky + lint-staged + commitlint setup |
| `/setup-team-protection` | GitHub repository protection rules |
| `/setup-doppler` | Setup Doppler secret management |
| `/create-pr` | Create PR with latest base branch changes merged |
| `/create-codespace` | Create GitHub Codespace |
| `/config-base-sync-check` | Check current and latest config-base image versions |
| `/config-base-sync-update` | Update DevContainer to latest config-base image and create PR |
| `/config-contribution-discover` | Discover useful features and create issues for config repo |
| `/sync-settings` | Sync Claude & Codex settings to DevContainer configuration |
| `/update-claude-code` | Update Claude Code version |
| `/update-actions` | Update GitHub Actions versions |
| `/container-health` | Container environment health check |
| `/codespaces-secrets` | Codespaces secrets management |
| `/branch-cleanup` | Clean up merged and stale branches |
| `/pre-pr-checklist` | Pre-PR validation checklist |
| `/devcontainer-checklist` | DevContainer restart verification checklist |
| `/git-sync` | Git sync commands |
| `/changelog-generator` | Generate changelog |
| `/dependency-health-check` | Check dependency health |
| `/security-credential-scan` | Scan for leaked credentials |
| `/security-review` | Security review with improvement suggestions |
| `/similarity-analysis` | Analyze code similarity to detect duplicate functions and patterns |
| `/code-complexity-check` | Code complexity analysis |
| `/test-coverage-trend` | Test coverage trend analysis |
| Command | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------- |
| `/branch-cleanup` | (no description) |
| `/changelog-generator` | (no description) |
| `/code-complexity-check` | (no description) |
| `/codespaces-secrets` | (no description) |
| `/config-base-sync-check` | Check current and latest config-base image versions |
| `/config-base-sync-update` | Update DevContainer to latest config-base image, sync recommended features, and create PR |
| `/config-contribution-discover` | Discover useful features in current repository and create issues for config repository |
| `/container-health` | (no description) |
| `/create-codespace` | (no description) |
| `/create-pr` | Create PR with latest base branch changes merged |
| `/dependency-health-check` | (no description) |
| `/devcontainer-checklist` | (no description) |
| `/git-sync` | (no description) |
| `/pre-pr-checklist` | (no description) |
| `/repo-maintenance` | Comprehensive repository maintenance - run all health checks and updates |
| `/security-credential-scan` | (no description) |
| `/security-review` | (no description) |
| `/setup-ci` | Setup comprehensive CI/CD workflows for your repository |
| `/setup-doppler` | Setup Doppler secret management with dev/dev_personal configuration |
| `/setup-husky` | (no description) |
| `/setup-new-repo` | Setup new repository with DevContainer, CI/CD, and development tools from config template |
| `/setup-team-protection` | (no description) |
| `/setup-tests` | Setup comprehensive testing infrastructure for Next.js projects |
| `/similarity-analysis` | Analyze code similarity in the repository to detect duplicate functions and patterns |
| `/sync-settings` | Sync Claude & Codex settings from your-org projects to DevContainer configuration |
| `/test-coverage-trend` | (no description) |
| `/update-actions` | (no description) |
| `/update-claude-code` | (no description) |

## CI/CD Workflows

| Workflow | Purpose |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| `ci.yml` | Code quality validation (lint, format, test, build). Required status check: `Quality Gate` |
| `docker-image.yml` | Build and Release DevContainer Image with semantic versioning |
| `security.yml` | Dependency review, license compliance, secret detection, npm audit |
| `claude.yml` | AI assistance triggered by `@claude` mentions in issues/PRs |
| `claude-code-review.yml` | Automated AI code review on PRs |
| `update-libraries.yml` | Scheduled `npm run update:libs` with auto PR |
| `update-dev-tools.yml` | Update development tools |
| `update-claude-plugins.yml` | Update Claude plugins |
| `container-security.yml` | Container security scanning (Trivy, CodeQL, SBOM) |
| `coverage-report.yml` | Coverage report generation |
| `label-sync.yml` | GitHub label IaC management |
| `dependabot-auto-merge.yml` | Dependabot PR auto-merge |
| `quality-gate-fallback.yml` | CI quality gate fallback for non-code changes |
| `manual-release.yml` | Manual release trigger |
| `rebuild-docker-cache.yml` | Weekly Docker cache rebuild |
| Workflow | Purpose |
| --------------------------- | ------------------------------------ |
| `ci.yml` | CI |
| `claude-code-review.yml` | Claude Code Review |
| `claude.yml` | Claude Code |
| `container-security.yml` | Container Security Scan |
| `coverage-report.yml` | Coverage Report |
| `dependabot-auto-merge.yml` | Dependabot Auto-merge |
| `docker-image.yml` | Build and Release DevContainer Image |
| `label-sync.yml` | Label Sync |
| `manual-release.yml` | Manual Release |
| `quality-gate-fallback.yml` | CI |
| `rebuild-docker-cache.yml` | Rebuild Docker Cache (Weekly) |
| `security.yml` | Security Scans |
| `update-claude-plugins.yml` | Update Claude Plugins |
| `update-dev-tools.yml` | Update Development Tools |
| `update-libraries.yml` | Auto Update Libraries |

## Quality Gates

The following scripts are auto-detected and run before git commit/push:

| Script | Command | Purpose |
| -------------- | ---------------------------------------------------------------------------------------------------- | -------------------------- |
| `format:check` | `prettier --check .` | Code formatting validation |
| `lint` | `eslint . --ext .js` | Code quality validation |
| `test` | `jest --runInBand` | Unit test execution |
| `shellcheck` | `find script -name '*.sh' -type f \| grep -vFf script/.shellcheck-exclude \| xargs -r shellcheck -x` | Shell script validation |
| Script | Command | Purpose |
| -------------- | ---------------------------------- | ------------------------------------ | ----------------------- | ----------------------- |
| `format:check` | `prettier --check .` | Code formatting validation |
| `lint` | `eslint . --ext .js` | Code quality validation |
| `test` | `jest --runInBand` | Unit test execution |
| `shellcheck` | `find script -name '\*.sh' -type f | grep -vFf script/.shellcheck-exclude | xargs -r shellcheck -x` | Shell script validation |

Comment on lines +124 to 130

@coderabbitai coderabbitai Bot Mar 22, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Markdown table is malformed due to unescaped pipe characters.

The shellcheck command value contains literal | characters that break the table structure:

  • Line 125 defines a 3-column table separator
  • Line 129 has unescaped pipes in the command: find ... | grep ... | xargs ...

This causes the Markdown renderer to interpret pipes as column delimiters, breaking the table layout.

The root cause is in script/update-agents-md.sh at collect_quality_gates() (lines 120-134) where $val from package.json scripts is inserted directly without escaping.

🐛 Fix in script/update-agents-md.sh 
 for i in "${!scripts[@]}"; do
   local key="${scripts[$i]}"
   local val
   val=$(jq -r --arg k "$key" '.scripts[$k] // empty' package.json 2>/dev/null)
   if [[ -n "$val" ]]; then
+    # Escape pipe characters for Markdown table
+    val="${val//|/\\|}"
     gates+="| \`$key\` | \`$val\` | ${purposes[$i]} |"$'\n'
   fi
 done
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
| Script | Command | Purpose |
| -------------- | ---------------------------------- | ------------------------------------ | ----------------------- | ----------------------- |
| `format:check` | `prettier --check .` | Code formatting validation |
| `lint` | `eslint . --ext .js` | Code quality validation |
| `test` | `jest --runInBand` | Unit test execution |
| `shellcheck` | `find script -name '\*.sh' -type f | grep -vFf script/.shellcheck-exclude | xargs -r shellcheck -x` | Shell script validation |
| Script | Command | Purpose |
| -------------- | ---------------------------------- | ------------------------------------ |
| `format:check` | `prettier --check .` | Code formatting validation |
| `lint` | `eslint . --ext .js` | Code quality validation |
| `test` | `jest --runInBand` | Unit test execution |
| `shellcheck` | `find script -name '\*.sh' -type f \| grep -vFf script/.shellcheck-exclude \| xargs -r shellcheck -x` | Shell script validation |
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` around lines 124 - 130, The Markdown table is broken because
unescaped pipe characters from script values are inserted into the table cell;
update the collect_quality_gates() function in script/update-agents-md.sh to
sanitize $val before writing it into AGENTS.md by either escaping all '|'
characters (replace '|' with '\|') or enclosing the command string in a code
span/backticks so pipes are treated as literal content; ensure the transformed
value is what gets written to the table generation logic (where $val is used) so
the rendered Markdown table remains intact.

Additional test commands: `test:integration` (BATS), `test:coverage` (Jest + coverage), `test:all` (unit + integration)

## Hooks

| Hook | Trigger | Purpose |
| ----------------------------- | ------------------- | ------------------------------------ |
| `block_git_no_verify.py` | Pre git commit/push | Block `--no-verify` and `HUSKY=0` |
| `pre_git_quality_gates.py` | Pre git commit/push | Auto-detect and run quality gates |
| `block_config_edit.py` | Pre edit | Protect configuration files |
| `block_dangerous_commands.py` | Pre Bash | Block destructive commands |
| `block_git_no_verify.py` | Pre git commit/push | Block `--no-verify` and `HUSKY=0` |
| `post_commit_adr_reminder.py` | Post git commit | Remind ADR for architectural changes |
| `post_edit_auto_lint.py` | Post edit | Auto-format and lint |
| `post_git_push_ci.py` | Post git push | Monitor CI status |
| `post_pr_ai_review.py` | Post PR creation | Run AI code review |
| `post_pr_ci_watch.py` | Post PR creation | Monitor PR CI status |
| `post_commit_adr_reminder.py` | Post git commit | Remind ADR for architectural changes |
| `pre_exit_plan_ai_review.py` | Pre ExitPlanMode | AI review before plan exit |
| `pre_git_quality_gates.py` | Pre git commit/push | Auto-detect and run quality gates |
| `stop_test_verification.py` | Stop | Verify test results on session end |

## Development Standards
Expand Down
Loading
Loading