This is an automated email from the ASF dual-hosted git repository.
jerryshao pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new ef303f2f0f [#10875] improvement(agent-skills): Add
gravitino-design-doc skill to enforce design document structure (#10876)
ef303f2f0f is described below
commit ef303f2f0ff00eb3b0604cf948a78cdfea0d89af
Author: Jerry Shao <[email protected]>
AuthorDate: Thu May 7 15:45:03 2026 +0800
[#10875] improvement(agent-skills): Add gravitino-design-doc skill to
enforce design document structure (#10876)
### What changes were proposed in this pull request?
Adds a new `gravitino-design-doc` Claude Code skill under
`agent-skills/` that enforces consistent structure and content quality
for Apache Gravitino design documents.
The skill requires the following sections in order:
1. Apache License Header
2. Title
3. Background — current state and problem, not the solution
4. Goals — concrete and verifiable
5. Non-Goals — explicit scope carve-outs with rationale
6. Solution Investigations — alternatives with pros/cons and rejection
reasons
7. Proposal — API design, data model, implementation approach
8. Task Breakdown — one actionable task per GitHub issue/PR, ordered by
dependency
### Why are the changes needed?
Closes #10875. With spec-driven development, design doc PRs are now
required before major features. Without an enforced structure, doc
quality is inconsistent and reviewers repeatedly request the same fixes.
### How was this patch tested?
N/A — documentation/tooling only change.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Sonnet 4.6 <[email protected]>
---
.claude/skills/gravitino-design-doc/README.md | 67 ++++++++
.claude/skills/gravitino-design-doc/SKILL.md | 222 ++++++++++++++++++++++++++
.gitignore | 2 +-
3 files changed, 290 insertions(+), 1 deletion(-)
diff --git a/.claude/skills/gravitino-design-doc/README.md
b/.claude/skills/gravitino-design-doc/README.md
new file mode 100644
index 0000000000..5bc784fd96
--- /dev/null
+++ b/.claude/skills/gravitino-design-doc/README.md
@@ -0,0 +1,67 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# gravitino-design-doc skill
+
+An agent skill that enforces consistent structure and content quality for
Apache Gravitino design documents.
+
+## What it does
+
+When writing or reviewing a design doc, the skill ensures the document covers
all required sections in the correct order:
+
+| # | Section | Required |
+|---|---------|----------|
+| 1 | **Apache License Header** | Yes |
+| 2 | **Title** | Yes |
+| 3 | **Background** | Yes |
+| 4 | **Goals** | Yes |
+| 5 | **Non-Goals** | Strongly recommended |
+| 6 | **Solution Investigations** | Yes |
+| 7 | **Proposal** | Yes |
+| 8 | **Task Breakdown** | Yes |
+
+For each section, the skill checks content quality — not just presence. For
example, Goals must be concrete and verifiable, and Solution Investigations
must document rejected alternatives with specific reasons.
+
+## Installation
+
+Copy `SKILL.md` into your agent's skill/instruction directory according to the
agent's documentation. For example, with Claude Code:
+
+```bash
+cp -r agent-skills/gravitino-design-doc ~/.claude/skills/
+```
+
+## Usage
+
+### Writing a new design doc
+
+Ask the agent to use this skill before you start writing:
+
+> "Write a design doc for \<feature\> using the gravitino-design-doc skill"
+
+The agent will guide you through each section, prompting for the right content
and flagging weak or missing parts before you open a PR.
+
+### Reviewing a design doc PR
+
+Ask the agent to review an existing doc against the skill's checklist:
+
+> "Review this design doc using the gravitino-design-doc skill"
+
+The agent will check each section against the quality checklist and report
what needs to be fixed before the PR is ready to merge.
+
+### Auto-trigger
+
+The skill also activates automatically when you mention writing or reviewing a
Gravitino design document, without needing an explicit invocation.
diff --git a/.claude/skills/gravitino-design-doc/SKILL.md
b/.claude/skills/gravitino-design-doc/SKILL.md
new file mode 100644
index 0000000000..d43a616eb1
--- /dev/null
+++ b/.claude/skills/gravitino-design-doc/SKILL.md
@@ -0,0 +1,222 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+---
+name: gravitino-design-doc
+description: Use when writing or reviewing a design document PR for the Apache
Gravitino project
+---
+
+# Gravitino Design Document
+
+## Overview
+
+All Gravitino design documents must cover the problem, scope, and solution in
a consistent structure so reviewers can evaluate them efficiently.
+
+## Required Sections (in order)
+
+### 1. Apache License Header
+HTML comment block — always the very first block in the file.
+
+```html
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ ...
+-->
+```
+
+### 2. Title (H1)
+- `# Design of <Feature> in Gravitino`, or
+- `# Design: <Feature> for Apache Gravitino`
+
+### 3. Background
+Describe **current state** and **what's wrong with it** — not the solution.
+- What does Gravitino currently do (or not do)?
+- Why is this a problem now?
+- Use tables, code blocks, or ASCII diagrams for architecture/current-state
illustration.
+
+### 4. Goals
+Numbered list. Each goal must be **concrete and verifiable**. Bold the goal
name.
+
+```markdown
+1. **Multi-Engine Compatibility**: Views managed by Gravitino are visible and
manageable across engines.
+```
+
+Avoid vague goals like "improve performance" or "better support X."
+
+### 5. Non-Goals (strongly recommended)
+Numbered list. Each non-goal must state **what is out of scope and briefly
why**.
+
+```markdown
+1. **SQL Transpilation**: Gravitino will not convert SQL between dialects.
Users must provide correct SQL per dialect.
+```
+
+Non-Goals prevent scope creep during review and implementation.
+
+### 6. Solution Investigations
+Document the alternative approaches considered and why they were accepted or
rejected. This section helps reviewers understand the design space and
validates that the proposal is the best fit.
+
+Each alternative should cover:
+- **What it is**: a brief description of the approach
+- **Pros**: why it is attractive
+- **Cons / why rejected**: the concrete reason it was not chosen
+
+**Table format (for 2–4 short alternatives):**
+
+| Approach | Pros | Cons | Decision |
+|----------|------|------|----------|
+| Option A | Fast, simple | Breaks backward compat | Rejected |
+| Option B (chosen) | Backward compatible, extensible | Slightly more complex
| **Chosen** |
+
+**Sub-section format (for deep alternatives):**
+
+```markdown
+### Option A: <Name>
+<Description>
+**Pros:** ...
+**Cons:** ...
+**Decision:** Rejected because ...
+
+### Option B: <Name> (Chosen)
+...
+```
+
+If only one approach was seriously considered, explain briefly why
alternatives were dismissed early.
+
+### 7. Proposal
+The actual design for the chosen approach. Use sub-sections. Should cover at
minimum:
+- API changes (new interfaces, REST endpoints, or CLI commands)
+- Data/metadata model (new entities, fields, schemas)
+- User process
+- Implementation process
+- Backward compatibility impact
+
+**API changes format:**
+
+For **new REST APIs**, define all three:
+```markdown
+#### POST /api/metalakes/{metalake}/...
+**Request:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | yes | ... |
+
+**Response:** `200 OK`
+```json
+{ "id": "...", "name": "..." }
+```
+**Behavior:** Describe what the endpoint does, preconditions, and error cases.
+```
+
+For **changed APIs** (modified request/response/semantics), document old vs.
new explicitly:
+```markdown
+#### PATCH /api/metalakes/{metalake}/...
+**Old behavior:** ...
+**New behavior:** ...
+**Migration impact:** What callers must change and whether a deprecation
window applies.
+```
+
+For **Java/Python client API or interface changes**, show the old and new
signatures side by side and note any incompatibility.
+
+**User process:**
+Describe how a user interacts with the feature end-to-end. Use numbered steps
or a sequence diagram so that a newcomer can follow the intended usage flow
without reading the implementation.
+
+```markdown
+1. User creates a catalog via `POST /api/metalakes/{metalake}/catalogs`.
+2. User lists views with `GET
/api/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/views`.
+3. ...
+```
+
+**Implementation process:**
+Describe how the system internally handles the feature. Cover component
interactions, data flow, and any non-obvious sequencing. Use ASCII sequence
diagrams or component diagrams where the flow would be hard to follow in prose.
+
+```
+Client → REST Server → Core Service → Metadata Store
+ ↑
+ Authorization
+```
+
+### 8. Task Breakdown
+A flat checklist of the concrete implementation tasks required to deliver this
feature. Each task should map to one GitHub issue or PR.
+
+Rules:
+- Each task must be **actionable** — a developer should be able to pick it up
and start without further clarification
+- Order tasks so that dependencies come first
+- Mark tasks that can be parallelized with `(parallel)` if helpful
+- Do not bundle unrelated changes into one task
+
+**Format:**
+
+```markdown
+- [ ] Define `<Interface>` API in `api/` module
+- [ ] Implement `<Class>` in `core/` module
+- [ ] Add REST endpoint `POST /api/metalakes/{metalake}/...` in `server/`
+- [ ] Add Java client support in `clients/client-java/`
+- [ ] Add Python client support in `clients/client-python/`
+- [ ] Write unit tests for `<Class>`
+- [ ] Write integration tests (Docker) for end-to-end flow
+- [ ] Update OpenAPI spec (`docs/open-api/*.yaml`) and validate with
`./gradlew :docs:build`
+- [ ] Update user-facing documentation in `docs/`
+```
+
+Group tasks by phase if the feature spans multiple releases:
+
+```markdown
+### Phase 1: Core API and Storage
+- [ ] ...
+
+### Phase 2: Engine Connector Support
+- [ ] ...
+```
+
+## Quality Checklist
+
+Before submitting a design doc PR, verify:
+
+- [ ] Apache License HTML comment is the first block in the file
+- [ ] Background describes the current state **and** the problem with it (not
just the desired future)
+- [ ] Goals are concrete — each one is verifiable when the feature ships
+- [ ] Non-Goals explicitly carve out scope with a one-line rationale each
+- [ ] Solution Investigations documents at least two approaches (or explains
why only one was viable)
+- [ ] Each rejected alternative has a concrete reason for rejection, not just
"Option B is better"
+- [ ] Proposal has at least one concrete sub-section (API, data model, or
algorithm)
+- [ ] New REST APIs define request, response, and behavior; changed APIs
document old vs. new behavior and migration impact
+- [ ] User process is described step-by-step so a newcomer can follow the
intended usage flow
+- [ ] Implementation process describes component interactions and data flow
(diagram preferred)
+- [ ] Task Breakdown has one task per GitHub issue/PR, ordered by dependency
+- [ ] Complex structures use tables, code blocks, or diagrams — no
wall-of-text paragraphs
+- [ ] Section separators (`---`) between major sections for readability
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Missing license header | Add the Apache License HTML comment block at top |
+| Background describes the solution instead of the problem | Rewrite to
describe current state and its shortcomings |
+| Vague goals ("improve X", "support Y better") | Rewrite as concrete,
verifiable statements |
+| Missing Non-Goals | Add explicit Non-Goals with brief rationale for each |
+| Solution Investigations only lists the chosen approach | Document rejected
alternatives with specific reasons |
+| Rejected alternatives say "too complex" with no detail | Explain the
specific complexity or constraint that disqualifies it |
+| Proposal skips API/data model and jumps to implementation | Add API design
and data model before implementation details |
+| New API defined without request/response/behavior | Add request fields
table, response schema, and behavior description |
+| Changed API doesn't show old vs. new behavior | Add explicit before/after
comparison and migration impact |
+| Proposal missing user process | Add numbered steps describing end-to-end
user interaction |
+| Proposal missing implementation process | Add component interaction diagram
or sequence description |
+| Goals have no bold label | Use `**Label**: Description` format |
+| Task Breakdown bundles multiple concerns into one task | Split into one task
per issue/PR |
+| Task Breakdown is unordered with no dependency awareness | Order so
dependencies come first |
+
diff --git a/.gitignore b/.gitignore
index aa17be1fd4..e085208f9f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -63,4 +63,4 @@ web/.next
.venv/
.worktrees/
-.claude
+.claude/settings.local.json
