Repository navigation
Description
Problem
CUBRID Lab's shared contributor/agent guidance covers issue/PR writing and tool-neutral review, but it does not yet provide a concise, discoverable human-first rule for comments inside source code, tests, examples, agent reviews, and published explanations. Repository-local AGENTS.md files vary: the Kubernetes Operator and showcase already have a human-readable communication section; several other repositories link the shared issue/PR writing standard without an equivalent code-comment principle.
A change to this repository's AGENTS.md is not automatically inherited by all other repositories' AGENTS.md, nor automatically read by every coding agent. Describe the actual adoption mechanism instead of promising implicit propagation.
Evidence
- Existing canonical guide: issue, PR, and commit standard, AGENTS.md.
- Operator PR #644: a comment refers to
S12 (#607)instead of making the HA-verdict rationale self-contained. Its local follow-up is #646. - Existing clear guidance in Operator AGENTS.md and showcase AGENTS.md should be reused, not duplicated verbatim in every repository.
- Issue-number references by themselves are not defects; a comment that clearly explains the invariant and includes
#123for traceability is acceptable.
Small task
- Add a short, canonical human-first code/comment and agent-written explanation rule to the most appropriate existing shared guide, linking it from this repository's
AGENTS.mdif needed. Cover source comments, tests, PR descriptions, reviews, and status comments; distinguish explanatory prose from machine-readable identifiers, error codes and scenario IDs. - State: explain what happens, why it matters, and the relevant invariant or constraint in ordinary English; an unexplained issue ID,
S06,see above,as discussed, or agent-only shorthand must not stand in for the explanation. Do not mandate redundant comments on self-explanatory code or remove useful history. - Document how each repository adopts it: link to the canonical policy from local agent instructions, keep repository-specific safety/build requirements, and check local guidance for conflicts during maintenance. Explicitly state that the org guide does not automatically update local files or guarantee agent compliance.
- Provide a small, manually runnable review checklist for maintainers/agents to verify newly authored comments and review text against this standard. Prefer existing review processes rather than new bots, workflows, or mandatory gates.
- Scope this issue to
cubrid-lab/.github; each product repository owns its own small adoption/cleanup issue and validation. Do not use this issue as a cross-repository approval gate.
Completion and validation
- One concise canonical rule exists and the local
AGENTS.mddiscovers it. - Adoption/precedence and lack of automatic inheritance are explained accurately.
- Example good/bad comments demonstrate a self-contained rationale with optional issue-ID traceability.
- Maintainers can review a new comment/PR description without looking up an agent's private notes or internal scenario mapping.
- Existing org writing/PR rules, local safety constraints and required CI remain unchanged; no agent-specific merge gate or mass code rewrite is introduced.
- Validate links/rendering and compare local guidance with existing Operator and Showcase rules before editing.
Non-goals
No automatic rewriting of code comments across the organization, no code behavior changes, no claim of guaranteed enforcement across every agent, and no additional CI bot solely for style.
Activity