From 38f8741794f200a916fde66734983dd0085b3cfb Mon Sep 17 00:00:00 2001 From: robot-wklken Date: Wed, 21 Oct 2026 16:35:42 +0800 Subject: [PATCH] docs: narrow documentation sync rules for system extensions --- .agents/skills/create-bk-cli-system/SKILL.md | 16 ++++------ AGENTS.md | 33 +++++++++++--------- 2 files changed, 25 insertions(+), 24 deletions(-) diff --git a/.agents/skills/create-bk-cli-system/SKILL.md b/.agents/skills/create-bk-cli-system/SKILL.md index 90eed1f..dae031d 100644 --- a/.agents/skills/create-bk-cli-system/SKILL.md +++ b/.agents/skills/create-bk-cli-system/SKILL.md @@ -591,15 +591,11 @@ subsystem YAML 的 `gateway_name` 必须独立声明，不从父 system 继承 - `cmd/system//_suite_test.go`：该 system 有测试时必须存在 - `cmd/system///_suite_test.go`：该 subsystem 有测试时必须存在 -如果新增公开 system，同步更新： +文档更新范围统一遵循 `AGENTS.md` 的“Documentation sync rules”，不要维护另一份无条件同步清单： -- `AGENTS.md` -- `README.md` -- `README_EN.md` -- `tests/integration/AGENTS.md` -- `skills/bk-cli-/SKILL.md` - -如果只是改动已有命令或参数，也要同步更新 `AGENTS.md`、`README.md`、`README_EN.md`、`tests/integration/AGENTS.md` 和相关 skill。 +- 新增公开 system 时，补齐中文 `skills/bk-cli-/SKILL.md`；新增 subsystem、action 或改动已有命令、参数时，更新对应 system skill 的用法、示例和必要排障说明。 +- 普通 system/subsystem/action 扩展默认只同步对应 system skill 和必要集成用例，不为了增加命令列表而修改 README、用户指南或设计文档。 +- 其他文档仅在各自承载的规则或已记载事实变化时按主规则更新；例如新增公开 system 后更新 `AGENTS.md` 的 system 清单，集成用例作者约定变化时更新 `tests/integration/AGENTS.md`。 如果变更影响公开 system 的可见行为，补充或更新： @@ -618,9 +614,9 @@ subsystem YAML 的 `gateway_name` 必须独立声明，不从父 system 继承 8. Go-implemented action 使用 `systemcmd.ExecuteRequest` 或 `syslib.ExecuteRequest` 9. 共享 flags、校验、JSON 解析优先复用 `systemcmd` helper 10. 测试优先复用 `cmd/system/testutil` -11. 公开 system 已补 `skills/bk-cli-/SKILL.md` +11. 新增公开 system 已补中文 `skills/bk-cli-/SKILL.md`；已有 system 的命令用法已按本次变更同步 12. 相关 system 的集成用例已在 `tests/integration/cases/system//` 补齐或确认无需变更 -13. 如集成用例作者约定有变化，已更新 `tests/integration/AGENTS.md` +13. 已按 `AGENTS.md` 的“Documentation sync rules”确认其他文档的更新范围；如集成用例作者约定有变化，已更新 `tests/integration/AGENTS.md` 14. 如果新增 subsystem，确认只使用一层 subsystem 15. 如果新增 subsystem，确认 subsystem action 路径是 `cmd/system///...` 16. 如果新增 subsystem，确认 subsystem YAML 顶层 `name` 是 ``，并且独立声明 `gateway_name` diff --git a/AGENTS.md b/AGENTS.md index 4037dd8..8fdb39a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ Keep longer-form user and extension guides in: Keep the detailed design baseline in: -- `docs/design.md` — full design contract and rationale +- `docs/design.md` — overall architecture, module design decisions, and shared contracts Keep system-extension workflow guidance in: @@ -361,7 +361,7 @@ Before adding or changing a public system: 4. decide whether the action should be YAML, Go-implemented, or mixed 5. add or update integration coverage under `tests/integration/cases/system//` when the public behavior changes 6. update or add system skill docs in the same change when the public surface changes -7. update user-facing docs if command names, flags, or examples changed +7. apply the Documentation sync rules below to any other docs; ordinary system, subsystem, or action extensions do not require broad user-facing doc updates Use these repo-specific resources when relevant: @@ -399,6 +399,10 @@ Keep that file focused on: - prompting patterns and repo-specific expectations for agents extending the CLI - guardrails for when to stop and raise a proposal instead of changing shared contracts +### What belongs in `docs/design.md` + +Keep that file focused on overall architecture, module design proposals and decisions, and shared contracts. Ordinary API/action mappings do not require design-doc updates. + ### What belongs in `skills/*/SKILL.md` Keep those files focused on: @@ -440,16 +444,17 @@ Keep this file focused on: ### Documentation sync rules -If you change any public command behavior, update the relevant docs in the same change: +For ordinary system, subsystem, or action additions and command/flag changes, update the corresponding system usage skill under `skills/` and add or update necessary integration cases in the same change. Do not expand README command lists or update the user guide or design doc merely because an API/action was added. + +Update other docs only when the change affects their own scope or makes existing content inaccurate: -- `README.md` -- `README_EN.md` -- `docs/user-guide.md` when longer user workflows, examples, or troubleshooting changed -- `docs/develop-extension-guide.md` when developer extension workflow or prompting guidance changed -- `AGENTS.md` when internal guidance also changed -- `tests/integration/AGENTS.md` when integration-case authoring or layout guidance changed -- `.agents/skills/create-bk-cli-system/SKILL.md` when system-extension workflow or must-check guidance changed -- related skill docs under `skills/` +- `README.md` / `README_EN.md`: only when a module gains a significant feature of interest to users, or existing overview, installation, quick-start, common usage, or contributor guidance needs correction. A new subsystem or action alone does not trigger an update. +- `docs/user-guide.md`: leave unchanged by default; update the relevant sections only when the task explicitly calls for a complete user workflow, or the change invalidates an existing workflow, example, or troubleshooting step. +- `docs/design.md`: leave unchanged by default; update only when overall architecture, module design decisions, or shared contracts change. Ordinary API/action mappings do not trigger an update. +- `docs/develop-extension-guide.md`: only when developer extension workflow, prompting guidance, or recorded facts change. +- `AGENTS.md`: only when architecture, internal guidance, or recorded facts such as the public system catalog change. +- `tests/integration/AGENTS.md`: only when integration-case authoring or layout guidance changes. Adding integration cases alone does not trigger an update. +- `.agents/skills/create-bk-cli-system/SKILL.md`: only when system-extension workflow or must-check guidance changes; refer to this policy instead of maintaining a separate unconditional documentation checklist. If `README.md` changes, update `README_EN.md` too. @@ -462,9 +467,9 @@ When finishing a code or CLI-surface change, verify all relevant items: - run `make test` - run `make test-cover` when coverage-sensitive code or thresholds changed - run `make build` -- update user-facing docs for command/flag/example changes -- update agent guidance when architectural or extension rules changed -- update `tests/integration/AGENTS.md` or add system cases when system behavior changes +- update the corresponding system usage skill for command/flag/example changes; apply Documentation sync rules to other user-facing docs +- update agent guidance when architectural or extension rules or recorded facts changed +- add or update necessary system integration cases when system behavior changes; update `tests/integration/AGENTS.md` only when authoring or layout guidance changes - add a matching skill when introducing a new public system under `cmd/system/` - write new files under `skills/` in Chinese