Skip to content

fix(wbfy): forbid explaining in-house tool specs outside the tool package - #1244

Merged
exKAZUu merged 4 commits into
mainfrom
docs/no-inhouse-tool-comments
Aug 15, 2026
Merged

fix(wbfy): forbid explaining in-house tool specs outside the tool package#1244
exKAZUu merged 4 commits into
mainfrom
docs/no-inhouse-tool-comments

Conversation

@exKAZUu

@exKAZUu exKAZUu commented Aug 15, 2026

Copy link
Copy Markdown
Member

Customer Summary

  • AI エージェントが、利用側リポジトリのコードコメントや README に wb / wbfy の仕様(例: 「wb が空きポートを自動探索するので PORT は設定しない」)を書き残さなくなります。
  • 社内では wb / wbfy の仕様は既知なので、こうした説明は読み手の役に立たず、実装が変わったときに古くなるだけでした。
  • 各リポジトリへは次回 wbfy 適用時に配布されます。既存の説明文が自動で削除されることはありません。

Technical Summary

  • generateAgentCodingStylepackages/wbfy/src/generators/agents.ts)のコーディングスタイルに 1 行追加しました。

    Never explain how WillBooster's in-house tools (e.g., wb, wbfy) work in code comments or documents outside the tool's own package, except in instructions for AI agents; e.g., do not note that PORT is unset because wb picks a free port.

  • 同ジェネレーターの出力である AGENTS.md / CLAUDE.md / GEMINI.md / .cursor/rules/general.mdc / .gemini/styleguide.md にも反映しました(5 ファイルの ## Coding Style 以降はハッシュ一致を確認済み)。

  • 適用範囲は「ツール自身のパッケージの外」なので、wb / wbfy パッケージ内の JSDoc やドキュメントは従来どおり書けます。wb/wbfy を同居させるこのモノレポでも、利用側パッケージだけが対象になります。

  • 「AI への指示文」を除外しているため、同じジェネレーターが AGENTS.md に出力している wb dotenv のプロファイル選択や wb gen-code の説明とは矛盾しません。

Why

  • 実例として exKAZUu-Dev/yutsugi#237 では、fnox.toml のコメント、playwright.config.ts のコメント、README.md の段落の 3 箇所に wb のポート自動探索の説明が生成され、手作業で削除する必要がありました。
  • 既存の「理解しにくいコードにのみコメントを書く」ルールだけでは、エージェントが「この設定は説明が要る」と判断してしまい抑止できませんでした。具体例(PORT)を明記したのはこのためです。
  • 除外の軸として「hand-written」も検討しましたが、AI が生成した README を「hand-written ではない」と解釈されると穴が空くため採用しませんでした。ファイル名の列挙ではなく「AI への指示文」という目的ベースの除外にしたのは、AGENTS_EXTRA.md やスキルファイルなど将来増えるものも含めて判定できるためです。

Testing

  • bun run verify(型チェック + Lint): 成功
  • 5 つの生成物の同期確認: awk '/^## Coding Style/,0' <file> | md5 が全ファイルで一致
  • review-booster 4 ラウンド(claude / codex / antigravity): 最終ラウンドは全エージェント指摘なし

Notes

  • 破壊的変更なし。ドキュメント(生成される指示文)のみの変更です。

…e sites

Co-authored-by: WillBooster (Claude Code) <agent@willbooster.com>
@gemini-code-assist

Copy link
Copy Markdown
Contributor

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

exKAZUu and others added 3 commits August 15, 2026 21:58
…tool comment rule

Co-authored-by: WillBooster (Claude Code) <agent@willbooster.com>
… documents

Co-authored-by: WillBooster (Claude Code) <agent@willbooster.com>
…and exempt AI instructions

Co-authored-by: WillBooster (Claude Code) <agent@willbooster.com>
@exKAZUu exKAZUu changed the title docs(wbfy): forbid explaining in-house tool specs in comments at usage sites docs(wbfy): forbid explaining in-house tool specs outside the tool package Aug 15, 2026
@exKAZUu exKAZUu self-assigned this Aug 15, 2026
@exKAZUu exKAZUu changed the title docs(wbfy): forbid explaining in-house tool specs outside the tool package fix(wbfy): forbid explaining in-house tool specs outside the tool package Aug 15, 2026
@exKAZUu
exKAZUu merged commit 0ef85eb into main Aug 15, 2026
7 checks passed
@exKAZUu
exKAZUu deleted the docs/no-inhouse-tool-comments branch August 15, 2026 13:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant