Skip to content

docs: narrow documentation sync rules for system extensions #49

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
wklken merged 1 commit into from
Oct 21, 2026
Merged

docs: narrow documentation sync rules for system extensions #49

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
16 changes: 6 additions & 10 deletions .agents/skills/create-bk-cli-system/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -591,15 +591,11 @@ subsystem YAML 的 `gateway_name` 必须独立声明，不从父 system 继承
- `cmd/system/<system>/<system>_suite_test.go`：该 system 有测试时必须存在
- `cmd/system/<system>/<subsystem>/<subsystem>_suite_test.go`：该 subsystem 有测试时必须存在

如果新增公开 system，同步更新：
文档更新范围统一遵循 `AGENTS.md` 的“Documentation sync rules”，不要维护另一份无条件同步清单：

- `AGENTS.md`
- `README.md`
- `README_EN.md`
- `tests/integration/AGENTS.md`
- `skills/bk-cli-<system>/SKILL.md`

如果只是改动已有命令或参数，也要同步更新 `AGENTS.md`、`README.md`、`README_EN.md`、`tests/integration/AGENTS.md` 和相关 skill。
- 新增公开 system 时，补齐中文 `skills/bk-cli-<system>/SKILL.md`；新增 subsystem、action 或改动已有命令、参数时，更新对应 system skill 的用法、示例和必要排障说明。
- 普通 system/subsystem/action 扩展默认只同步对应 system skill 和必要集成用例，不为了增加命令列表而修改 README、用户指南或设计文档。
- 其他文档仅在各自承载的规则或已记载事实变化时按主规则更新；例如新增公开 system 后更新 `AGENTS.md` 的 system 清单，集成用例作者约定变化时更新 `tests/integration/AGENTS.md`。

如果变更影响公开 system 的可见行为，补充或更新：

Expand All @@ -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-<system>/SKILL.md`
11. 新增公开 system 已补中文 `skills/bk-cli-<system>/SKILL.md`；已有 system 的命令用法已按本次变更同步
12. 相关 system 的集成用例已在 `tests/integration/cases/system/<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/<system>/<subsystem>/...`
16. 如果新增 subsystem，确认 subsystem YAML 顶层 `name` 是 `<subsystem>`，并且独立声明 `gateway_name`
Expand Down
33 changes: 19 additions & 14 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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/<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:

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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.

Expand All @@ -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

Expand Down
Loading