nevzheng commented on issue #12387: URL: https://github.com/apache/gravitino/issues/12387#issuecomment-5219860843
## Deep dive: how agent prompting works today **Bottom line:** Gravitino tells agents which rules and templates to follow, but not how to frame the story. The current system is optimized for structural compliance, so an otherwise uninstructed agent can turn the diff or chronology into a procedural inventory. Audited against `upstream/main` at [`e51be544`](https://github.com/apache/gravitino/tree/e51be54441cb72b7556d810f463b042fa0909775). ```mermaid flowchart TD U["User request"] --> R["Agent runtime"] A["AGENTS.md<br/>coding rules, approval, template pointers"] --> R L["CLAUDE.md / GEMINI.md<br/>symlinks"] --> A C["copilot-instructions.md<br/>independent coding guidance"] --> CP["Copilot runtime"] S["Conditional task skill<br/>more-specific guidance"] -.-> R R --> W["Generate title and body"] CP --> W P["PR template<br/>title syntax and headings"] -. "when consulted or injected" .-> W I["Issue form<br/>required fields"] -. "when selected" .-> W D["Discussion<br/>no local writing prompt"] -.-> W W --> O["Accurate, but often diff-first<br/>and procedural"] O --> M["Maintainer cleanup later"] ``` ### Current layers - **Shared repository guidance:** [`AGENTS.md`](https://github.com/apache/gravitino/blob/e51be54441cb72b7556d810f463b042fa0909775/AGENTS.md#L45-L48) requires a preview, routes issues to an issue form, and routes PR descriptions to the PR template. It asks for content to be concise and clear, but supplies no narrative model. - **Agent entry points:** `CLAUDE.md` and `GEMINI.md` are symlinks to `AGENTS.md`. [Copilot has a separate instruction file](https://github.com/apache/gravitino/blob/e51be54441cb72b7556d810f463b042fa0909775/.github/copilot-instructions.md) containing coding rules but no PR, Issue, or Discussion-writing guidance. Coverage therefore varies by agent surface. - **Conditional skills:** Specialized guidance applies only when a skill is selected. The [documentation-refinement style](https://github.com/apache/gravitino/blob/e51be54441cb72b7556d810f463b042fa0909775/.claude/skills/gravitino-docs-refine/STYLE.md#L190-L200) currently asks for a category list in PR descriptions and gives a title format that can conflict with the repository template. - **Artifact schemas:** The [PR template](https://github.com/apache/gravitino/blob/e51be54441cb72b7556d810f463b042fa0909775/.github/PULL_REQUEST_TEMPLATE#L1-L35) provides title syntax and four headings. Issue forms provide required fields. These shape submissions when they are used, but direct API or command-line creation can bypass their automatic insertion. - **Discussions:** [GitHub Discussions are enabled](https://github.com/apache/gravitino/blob/e51be54441cb72b7556d810f463b042fa0909775/.asf.yaml#L36-L41), but the repository has no Discussion template or agent-writing rule. - **After authoring:** [Maintainers are asked](https://github.com/apache/gravitino/blob/e51be54441cb72b7556d810f463b042fa0909775/MAINTAINERS.md#L50-L59) to correct PR titles and descriptions before merge. That is a manual, late-stage safeguard rather than guidance at generation time. ### What this encourages 1. **Structure before story.** Agents know the required fields, but not the intended information hierarchy: bottom line, why it matters, context and boundaries, evidence, then optional detail. 2. **A change inventory first.** The PR template asks “What changes” before “Why” and says to “outline the changes,” making a file/class/step inventory the easiest compliant response. 3. **Procedural titles.** The title rule specifies syntax, not that the subject should express a concrete outcome, problem, question, or decision. 4. **Fragmented behavior.** Shared guidance, Copilot guidance, conditional skills, and artifact templates can give different or incomplete instructions. 5. **No freshness loop.** Nothing generally tells an agent to recheck a title or body after the scope, behavior, decision, relationships, or verification evidence changes. ### Implication The shared narrative principles and freshness behavior should live in canonical repository agent guidance. Existing PR and Issue templates can remain structural contracts; agent-specific entry points and specialized skills should defer to the canonical rule. This issue intentionally leaves design-document guidance and validation workflows out of scope. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
