Skip to content

docs: define clear explanations for agent-authored code and reviews #72

Closed

Description

@yeongseon

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 #123 for traceability is acceptable.

Small task

  1. 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.md if needed. Cover source comments, tests, PR descriptions, reviews, and status comments; distinguish explanatory prose from machine-readable identifiers, error codes and scenario IDs.
  2. 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.
  3. 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.
  4. 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.
  5. 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.md discovers 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions