From 5a81e1b3a072f030409308df6f961cf15bc704cd Mon Sep 17 00:00:00 2001 From: "Sakamoto, Kazunori" Date: Tue, 15 Sep 2026 22:33:39 +0900 Subject: [PATCH 1/2] feat(wbfy): generate a comment policy that forbids restating the code Co-authored-by: WillBooster (Claude Code) --- packages/wbfy/src/generators/agents.ts | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/packages/wbfy/src/generators/agents.ts b/packages/wbfy/src/generators/agents.ts index 62da952f9..8c79f31f0 100644 --- a/packages/wbfy/src/generators/agents.ts +++ b/packages/wbfy/src/generators/agents.ts @@ -175,6 +175,12 @@ export function generateAgentCodingStyle(rootConfig: PackageConfig, allConfigs: // isPublicRepo=false and therefore keeps the restrictive default. const isGeneralPublicOss = rootConfig.isPublicRepo && allConfigs.every((c) => !c.packageJson?.name?.startsWith('@willbooster/')); + // Only public repositories publish packages to the public npm registry, whose users read the + // JSDoc without the source; private repositories are read only by agents that have the source. + const npmApiException = rootConfig.isPublicRepo + ? ' Exception: the exported API of a package published to npm may carry JSDoc describing what it does and how to call it, because its users read it without the source.' + : ''; + const commentInstruction = `- Comments and JSDoc: every reader has the source, so never restate what the code, its names, or its types already say (e.g., \`@param name The name\`, \`@returns the result\`, a narration of the control flow). Write one only when a plausible edit (simplifying, deleting, reordering, replacing) would break something without that knowledge and no type check, lint rule, or existing test would catch the breakage; first try to encode the knowledge in code (a name such as \`timeoutMs\`, a type, an \`assert\`, a test) and comment only what cannot be encoded: a deliberately odd-looking workaround, a dependency on a fact outside the repository (an external API's behavior, an agreement with another system), or a rejected alternative and why. Put it in JSDoc when it is a contract of the declared symbol, so callers see it, and in an inline comment when it concerns specific lines. Delete comments that fail this test in files you touch.${npmApiException}`; const osCompatibilityInstruction = isGeneralPublicOss ? '' : hasDesktopApp @@ -209,7 +215,7 @@ export function generateAgentCodingStyle(rootConfig: PackageConfig, allConfigs: - Simplify code as much as possible to eliminate redundancy. - Design modules and directories with high cohesion and low coupling; split large modules when needed. - Place calling functions above the functions they call (top-down order); place variable and type declarations above their usage. -- Write comments and JSDoc only for hard-to-understand code: explain "why" in comments and "what" in JSDoc. +${commentInstruction} - 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). - If lint errors or warnings cannot be fixed, use ignore comments with reasons (e.g., \`// oxlint-disable-next-line -- \`). - Prefer \`undefined\` over \`null\` unless required by APIs or libraries. From 406fab51ea3a142005bfae5756e25f22142f57ee Mon Sep 17 00:00:00 2001 From: "Sakamoto, Kazunori" Date: Tue, 15 Sep 2026 22:48:53 +0900 Subject: [PATCH 2/2] chore: regenerate agent instructions with the new comment policy Co-authored-by: WillBooster (Claude Code) --- .cursor/rules/general.mdc | 2 +- .gemini/styleguide.md | 2 +- AGENTS.md | 2 +- CLAUDE.md | 2 +- GEMINI.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.cursor/rules/general.mdc b/.cursor/rules/general.mdc index 65f6bd682..ee076e608 100644 --- a/.cursor/rules/general.mdc +++ b/.cursor/rules/general.mdc @@ -49,7 +49,7 @@ alwaysApply: true - Simplify code as much as possible to eliminate redundancy. - Design modules and directories with high cohesion and low coupling; split large modules when needed. - Place calling functions above the functions they call (top-down order); place variable and type declarations above their usage. -- Write comments and JSDoc only for hard-to-understand code: explain "why" in comments and "what" in JSDoc. +- Comments and JSDoc: every reader has the source, so never restate what the code, its names, or its types already say (e.g., `@param name The name`, `@returns the result`, a narration of the control flow). Write one only when a plausible edit (simplifying, deleting, reordering, replacing) would break something without that knowledge and no type check, lint rule, or existing test would catch the breakage; first try to encode the knowledge in code (a name such as `timeoutMs`, a type, an `assert`, a test) and comment only what cannot be encoded: a deliberately odd-looking workaround, a dependency on a fact outside the repository (an external API's behavior, an agreement with another system), or a rejected alternative and why. Put it in JSDoc when it is a contract of the declared symbol, so callers see it, and in an inline comment when it concerns specific lines. Delete comments that fail this test in files you touch. Exception: the exported API of a package published to npm may carry JSDoc describing what it does and how to call it, because its users read it without the source. - 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). - If lint errors or warnings cannot be fixed, use ignore comments with reasons (e.g., `// oxlint-disable-next-line -- `). - Prefer `undefined` over `null` unless required by APIs or libraries. diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md index 45e626e09..ec1260bcc 100644 --- a/.gemini/styleguide.md +++ b/.gemini/styleguide.md @@ -6,7 +6,7 @@ Review in English based on the following coding standards. - Simplify code as much as possible to eliminate redundancy. - Design modules and directories with high cohesion and low coupling; split large modules when needed. - Place calling functions above the functions they call (top-down order); place variable and type declarations above their usage. -- Write comments and JSDoc only for hard-to-understand code: explain "why" in comments and "what" in JSDoc. +- Comments and JSDoc: every reader has the source, so never restate what the code, its names, or its types already say (e.g., `@param name The name`, `@returns the result`, a narration of the control flow). Write one only when a plausible edit (simplifying, deleting, reordering, replacing) would break something without that knowledge and no type check, lint rule, or existing test would catch the breakage; first try to encode the knowledge in code (a name such as `timeoutMs`, a type, an `assert`, a test) and comment only what cannot be encoded: a deliberately odd-looking workaround, a dependency on a fact outside the repository (an external API's behavior, an agreement with another system), or a rejected alternative and why. Put it in JSDoc when it is a contract of the declared symbol, so callers see it, and in an inline comment when it concerns specific lines. Delete comments that fail this test in files you touch. Exception: the exported API of a package published to npm may carry JSDoc describing what it does and how to call it, because its users read it without the source. - 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). - If lint errors or warnings cannot be fixed, use ignore comments with reasons (e.g., `// oxlint-disable-next-line -- `). - Prefer `undefined` over `null` unless required by APIs or libraries. diff --git a/AGENTS.md b/AGENTS.md index 84b2aecbb..859cfa0f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,7 +43,7 @@ - Simplify code as much as possible to eliminate redundancy. - Design modules and directories with high cohesion and low coupling; split large modules when needed. - Place calling functions above the functions they call (top-down order); place variable and type declarations above their usage. -- Write comments and JSDoc only for hard-to-understand code: explain "why" in comments and "what" in JSDoc. +- Comments and JSDoc: every reader has the source, so never restate what the code, its names, or its types already say (e.g., `@param name The name`, `@returns the result`, a narration of the control flow). Write one only when a plausible edit (simplifying, deleting, reordering, replacing) would break something without that knowledge and no type check, lint rule, or existing test would catch the breakage; first try to encode the knowledge in code (a name such as `timeoutMs`, a type, an `assert`, a test) and comment only what cannot be encoded: a deliberately odd-looking workaround, a dependency on a fact outside the repository (an external API's behavior, an agreement with another system), or a rejected alternative and why. Put it in JSDoc when it is a contract of the declared symbol, so callers see it, and in an inline comment when it concerns specific lines. Delete comments that fail this test in files you touch. Exception: the exported API of a package published to npm may carry JSDoc describing what it does and how to call it, because its users read it without the source. - 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). - If lint errors or warnings cannot be fixed, use ignore comments with reasons (e.g., `// oxlint-disable-next-line -- `). - Prefer `undefined` over `null` unless required by APIs or libraries. diff --git a/CLAUDE.md b/CLAUDE.md index 1c920f51b..1b51f47e6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -43,7 +43,7 @@ - Simplify code as much as possible to eliminate redundancy. - Design modules and directories with high cohesion and low coupling; split large modules when needed. - Place calling functions above the functions they call (top-down order); place variable and type declarations above their usage. -- Write comments and JSDoc only for hard-to-understand code: explain "why" in comments and "what" in JSDoc. +- Comments and JSDoc: every reader has the source, so never restate what the code, its names, or its types already say (e.g., `@param name The name`, `@returns the result`, a narration of the control flow). Write one only when a plausible edit (simplifying, deleting, reordering, replacing) would break something without that knowledge and no type check, lint rule, or existing test would catch the breakage; first try to encode the knowledge in code (a name such as `timeoutMs`, a type, an `assert`, a test) and comment only what cannot be encoded: a deliberately odd-looking workaround, a dependency on a fact outside the repository (an external API's behavior, an agreement with another system), or a rejected alternative and why. Put it in JSDoc when it is a contract of the declared symbol, so callers see it, and in an inline comment when it concerns specific lines. Delete comments that fail this test in files you touch. Exception: the exported API of a package published to npm may carry JSDoc describing what it does and how to call it, because its users read it without the source. - 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). - If lint errors or warnings cannot be fixed, use ignore comments with reasons (e.g., `// oxlint-disable-next-line -- `). - Prefer `undefined` over `null` unless required by APIs or libraries. diff --git a/GEMINI.md b/GEMINI.md index 0ebf314ba..9deef63d6 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -43,7 +43,7 @@ - Simplify code as much as possible to eliminate redundancy. - Design modules and directories with high cohesion and low coupling; split large modules when needed. - Place calling functions above the functions they call (top-down order); place variable and type declarations above their usage. -- Write comments and JSDoc only for hard-to-understand code: explain "why" in comments and "what" in JSDoc. +- Comments and JSDoc: every reader has the source, so never restate what the code, its names, or its types already say (e.g., `@param name The name`, `@returns the result`, a narration of the control flow). Write one only when a plausible edit (simplifying, deleting, reordering, replacing) would break something without that knowledge and no type check, lint rule, or existing test would catch the breakage; first try to encode the knowledge in code (a name such as `timeoutMs`, a type, an `assert`, a test) and comment only what cannot be encoded: a deliberately odd-looking workaround, a dependency on a fact outside the repository (an external API's behavior, an agreement with another system), or a rejected alternative and why. Put it in JSDoc when it is a contract of the declared symbol, so callers see it, and in an inline comment when it concerns specific lines. Delete comments that fail this test in files you touch. Exception: the exported API of a package published to npm may carry JSDoc describing what it does and how to call it, because its users read it without the source. - 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). - If lint errors or warnings cannot be fixed, use ignore comments with reasons (e.g., `// oxlint-disable-next-line -- `). - Prefer `undefined` over `null` unless required by APIs or libraries.