mirror of
https://github.com/alibaba/higress.git
synced 2026-03-04 08:30:48 +08:00
docs: add Cursor project rules for AI coding with plugin development standards
Change-Id: I3f578b11e29e018a746a9530d2995fec99eabb4b Co-developed-by: Cursor <noreply@cursor.com>
This commit is contained in:
johnlanni
135
.cursor/rules/plugin-development.mdc
Normal file
135
.cursor/rules/plugin-development.mdc
Normal file
@@ -0,0 +1,135 @@
|
||||
---
|
||||
description: Plugin Development Standards - Applies to all new wasm and golang-filter plugins
|
||||
globs:
|
||||
- "plugins/wasm-go/extensions/*/**"
|
||||
- "plugins/wasm-cpp/extensions/*/**"
|
||||
- "plugins/wasm-rust/extensions/*/**"
|
||||
- "plugins/wasm-assemblyscript/extensions/*/**"
|
||||
- "plugins/golang-filter/*/**"
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Plugin Development Standards
|
||||
|
||||
## Strict Requirements for New Independent Plugins
|
||||
|
||||
When creating **new independent plugins** (e.g., newly implemented wasm plugins or golang-filter plugins), you **MUST** follow these standards:
|
||||
|
||||
### 1. Design Documentation Directory Requirements
|
||||
|
||||
- You **MUST** create a `design/` directory within the plugin directory
|
||||
- Directory structure example:
|
||||
```
|
||||
plugins/wasm-go/extensions/my-new-plugin/
|
||||
├── design/
|
||||
│ ├── design-doc.md # Design document
|
||||
│ ├── architecture.md # Architecture (optional)
|
||||
│ └── requirements.md # Requirements (optional)
|
||||
├── main.go
|
||||
├── go.mod
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### 2. Design Documentation Content Requirements
|
||||
|
||||
The design documentation in the `design/` directory should include:
|
||||
|
||||
- **Plugin Purpose and Use Cases**: Clearly explain what problem the plugin solves
|
||||
- **Core Functionality Design**: Detailed description of main features and implementation approach
|
||||
- **Configuration Parameters**: List all configuration items and their meanings
|
||||
- **Technology Selection and Dependencies**: Explain the technology stack and third-party libraries used
|
||||
- **Boundary Conditions and Limitations**: Define the applicable scope and limitations of the plugin
|
||||
- **Testing Strategy**: How to verify plugin functionality
|
||||
|
||||
### 3. Documentation Provided to AI Coding Tools
|
||||
|
||||
If you are using AI Coding tools (such as Cursor, GitHub Copilot, etc.) to generate code:
|
||||
|
||||
- You **MUST** save the complete design documents, requirement descriptions, and prompts you provided to the AI in the `design/` directory
|
||||
- Recommended file naming:
|
||||
- `ai-prompts.md` - AI prompts record
|
||||
- `design-doc.md` - Complete design document
|
||||
- `requirements.md` - Feature requirements list
|
||||
|
||||
### 4. Files NOT to Commit to Git
|
||||
|
||||
Note: The following files should **NOT** be committed to Git:
|
||||
- AI Coding tool work summary documents (should be placed in PR description)
|
||||
- Temporary feature change summary documents
|
||||
|
||||
Design documents in the `design/` directory **SHOULD** be committed to Git, as they serve as the design basis and technical documentation for the plugin.
|
||||
|
||||
## Examples
|
||||
|
||||
### Good Plugin Directory Structure Example
|
||||
|
||||
```
|
||||
plugins/wasm-go/extensions/ai-security-guard/
|
||||
├── design/
|
||||
│ ├── design-doc.md # ✅ Detailed design document
|
||||
│ ├── ai-prompts.md # ✅ Prompts provided to AI
|
||||
│ └── architecture.png # ✅ Architecture diagram
|
||||
├── main.go
|
||||
├── config.go
|
||||
├── README.md
|
||||
└── go.mod
|
||||
```
|
||||
|
||||
### Design Document Template
|
||||
|
||||
When creating `design/design-doc.md`, you can refer to the following template:
|
||||
|
||||
```markdown
|
||||
# [Plugin Name] Design Document
|
||||
|
||||
## Overview
|
||||
- Plugin purpose
|
||||
- Problem it solves
|
||||
- Target users
|
||||
|
||||
## Functional Design
|
||||
### Core Feature 1
|
||||
- Feature description
|
||||
- Implementation approach
|
||||
- Key code logic
|
||||
|
||||
### Core Feature 2
|
||||
...
|
||||
|
||||
## Configuration Parameters
|
||||
| Parameter | Type | Required | Description | Default |
|
||||
|-----------|------|----------|-------------|---------|
|
||||
| ... | ... | ... | ... | ... |
|
||||
|
||||
## Technical Implementation
|
||||
- Technology selection
|
||||
- Dependencies
|
||||
- Performance considerations
|
||||
|
||||
## Test Plan
|
||||
- Unit tests
|
||||
- Integration tests
|
||||
- Boundary tests
|
||||
|
||||
## Limitations and Notes
|
||||
- Known limitations
|
||||
- Usage recommendations
|
||||
```
|
||||
|
||||
## Execution Checklist
|
||||
|
||||
When creating a new plugin, please confirm:
|
||||
|
||||
- [ ] Created `design/` directory within the plugin directory
|
||||
- [ ] Placed design documentation in the `design/` directory
|
||||
- [ ] If using AI Coding tools, saved prompts/requirement documents in the `design/` directory
|
||||
- [ ] Prepared AI Coding tool work summary (for PR description)
|
||||
- [ ] Design documentation is complete with necessary technical details
|
||||
|
||||
## Tips
|
||||
|
||||
- Design documentation is important technical documentation for the plugin, helpful for:
|
||||
- Understanding design intent during code review
|
||||
- Quickly understanding implementation approach during future maintenance
|
||||
- Learning and reference for other developers
|
||||
- Tracing the reasoning behind design decisions
|
||||
44
.github/PULL_REQUEST_TEMPLATE.md
vendored
44
.github/PULL_REQUEST_TEMPLATE.md
vendored
@@ -1,17 +1,51 @@
|
||||
<!-- Please make sure you have read and understood the contributing guidelines -->
|
||||
|
||||
### Ⅰ. Describe what this PR did
|
||||
## Ⅰ. Describe what this PR did
|
||||
|
||||
|
||||
### Ⅱ. Does this pull request fix one issue?
|
||||
## Ⅱ. Does this pull request fix one issue?
|
||||
<!-- If that, add "fixes #xxx" below in the next line, for example, fixes #97. -->
|
||||
|
||||
|
||||
### Ⅲ. Why don't you add test cases (unit test/integration test)?
|
||||
## Ⅲ. Why don't you add test cases (unit test/integration test)?
|
||||
|
||||
|
||||
### Ⅳ. Describe how to verify it
|
||||
## Ⅳ. Describe how to verify it
|
||||
|
||||
|
||||
## Ⅴ. Special notes for reviews
|
||||
|
||||
|
||||
## Ⅵ. AI Coding Tool Usage Checklist (if applicable)
|
||||
<!--
|
||||
**IMPORTANT**: If you used AI Coding tools (e.g., Cursor, GitHub Copilot, etc.) to generate this PR, please check the following items.
|
||||
PRs that don't meet these requirements will have **LOWER REVIEW PRIORITY** and we **CANNOT GUARANTEE** timely reviews.
|
||||
|
||||
If you did NOT use AI Coding tools, you can skip this section entirely.
|
||||
-->
|
||||
|
||||
**Please check all applicable items:**
|
||||
|
||||
- [ ] **For new standalone features** (e.g., new wasm plugin or golang-filter plugin):
|
||||
- [ ] I have created a `design/` directory in the plugin folder
|
||||
- [ ] I have added the design document to the `design/` directory
|
||||
- [ ] I have included the AI Coding summary below
|
||||
|
||||
- [ ] **For regular updates/changes** (not new plugins):
|
||||
- [ ] I have provided the prompts/instructions I gave to the AI Coding tool below
|
||||
- [ ] I have included the AI Coding summary below
|
||||
|
||||
### AI Coding Prompts (for regular updates)
|
||||
<!-- Paste the prompts/instructions you provided to the AI Coding tool -->
|
||||
|
||||
|
||||
### AI Coding Summary
|
||||
<!--
|
||||
AI Coding tool should provide a summary after completing the work, including:
|
||||
- Key decisions made
|
||||
- Major changes implemented
|
||||
- Important considerations or limitations
|
||||
-->
|
||||
|
||||
|
||||
### Ⅴ. Special notes for reviews
|
||||
|
||||
|
||||
@@ -169,6 +169,31 @@ git config --get user.email
|
||||
|
||||
PR 是更改 Higress 项目文件的唯一方法。为了帮助审查人更好地理解你的目的，PR 描述不能太详细。我们鼓励贡献者遵循 [PR 模板](./.github/PULL_REQUEST_TEMPLATE.md) 来完成拉取请求。
|
||||
|
||||
#### 使用 AI Coding 工具的特殊要求
|
||||
|
||||
如果你使用 AI Coding 工具（如 Cursor、GitHub Copilot 等）来生成 PR，我们有以下**严格要求**：
|
||||
|
||||
**针对新增独立插件的场景**（例如新实现的 wasm 插件或 golang-filter 插件）：
|
||||
- 你**必须**在插件目录下创建 `design/` 目录
|
||||
- 将你提供给 AI Coding 工具的设计文档放在 `design/` 目录中
|
||||
- 在 PR 描述中提供 AI Coding 工具生成的工作总结
|
||||
|
||||
**针对日常更新/修改的场景**：
|
||||
- 在 PR 描述中提供你给 AI Coding 工具的提示词/指令
|
||||
- 在 PR 描述中提供 AI Coding 工具生成的工作总结
|
||||
|
||||
**AI Coding 工作总结应包括**：
|
||||
- 做出的关键决策
|
||||
- 实现的主要更改
|
||||
- 重要的注意事项或限制
|
||||
|
||||
**Review 优先级说明**：
|
||||
- 如果你使用了 AI Coding 工具但没有按照上述要求操作，你的 PR review 优先级将会**降低**
|
||||
- 我们**无法保证**对不符合要求的 AI Coding PR 进行及时 review
|
||||
- 如果不是使用 AI Coding 工具完成的 PR，则不需要遵循这些额外要求
|
||||
|
||||
这些要求的目的是确保使用 AI 生成的代码具有充分的文档记录和可追溯性，便于代码审查和后续维护。通过要求提供提示词/设计文档，我们可以更好地理解开发意图和上下文。
|
||||
|
||||
### 开发前准备
|
||||
|
||||
```shell
|
||||
|
||||
@@ -169,6 +169,31 @@ No matter commit message, or commit content, we do take more emphasis on code re
|
||||
|
||||
PR is the only way to make change to Higress project files. To help reviewers better get your purpose, PR description could not be too detailed. We encourage contributors to follow the [PR template](./.github/PULL_REQUEST_TEMPLATE.md) to finish the pull request.
|
||||
|
||||
#### Special Requirements for AI Coding Tool Usage
|
||||
|
||||
If you use AI Coding tools (such as Cursor, GitHub Copilot, etc.) to generate PRs, we have the following **strict requirements**:
|
||||
|
||||
**For new standalone plugin scenarios** (e.g., newly implemented wasm plugins or golang-filter plugins):
|
||||
- You **MUST** create a `design/` directory under the plugin directory
|
||||
- Place the design document you provided to the AI Coding tool in the `design/` directory
|
||||
- Provide an AI Coding summary in the PR description
|
||||
|
||||
**For regular updates/changes scenarios**:
|
||||
- Provide the prompts/instructions you gave to the AI Coding tool in the PR description
|
||||
- Provide an AI Coding summary in the PR description
|
||||
|
||||
**AI Coding Summary should include**:
|
||||
- Key decisions made
|
||||
- Major changes implemented
|
||||
- Important considerations or limitations
|
||||
|
||||
**Review Priority Notice**:
|
||||
- If you use AI Coding tools but do not follow the above requirements, your PR review priority will be **lowered**
|
||||
- We **cannot guarantee** timely reviews for AI Coding PRs that do not meet these requirements
|
||||
- If the PR is not completed using AI Coding tools, these additional requirements do not apply
|
||||
|
||||
The purpose of these requirements is to ensure that AI-generated code is adequately documented and traceable, facilitating code review and subsequent maintenance. By requiring prompts/design documents, we can better understand the development intent and context.
|
||||
|
||||
### Pre-development preparation
|
||||
|
||||
```shell
|
||||
|
||||
@@ -164,6 +164,31 @@ git config --get user.email
|
||||
|
||||
PR は Higress プロジェクトファイルを変更する唯一の方法です。レビュアーが目的をよりよく理解できるようにするために、PR 説明は詳細すぎることはありません。貢献者には、[PR テンプレート](./.github/PULL_REQUEST_TEMPLATE.md) に従ってプルリクエストを完了することを奨励します。
|
||||
|
||||
#### AI Coding ツール使用時の特別な要件
|
||||
|
||||
AI Coding ツール（Cursor、GitHub Copilot など）を使用して PR を生成する場合、以下の**厳格な要件**があります：
|
||||
|
||||
**新規独立プラグインのシナリオ**（新しく実装された wasm プラグインや golang-filter プラグインなど）の場合：
|
||||
- プラグインディレクトリの下に `design/` ディレクトリを作成する**必要があります**
|
||||
- AI Coding ツールに提供した設計ドキュメントを `design/` ディレクトリに配置してください
|
||||
- PR の説明に AI Coding サマリーを提供してください
|
||||
|
||||
**通常の更新/変更のシナリオ**の場合：
|
||||
- PR の説明に AI Coding ツールに与えたプロンプト/指示を提供してください
|
||||
- PR の説明に AI Coding サマリーを提供してください
|
||||
|
||||
**AI Coding サマリーには以下を含める必要があります**：
|
||||
- 行われた重要な決定
|
||||
- 実装された主要な変更
|
||||
- 重要な考慮事項または制限事項
|
||||
|
||||
**レビュー優先度に関する通知**：
|
||||
- AI Coding ツールを使用したが上記の要件に従わなかった場合、PR のレビュー優先度が**低下**します
|
||||
- 要件を満たしていない AI Coding PR に対して、タイムリーなレビューを**保証できません**
|
||||
- AI Coding ツールを使用せずに完了した PR の場合、これらの追加要件は適用されません
|
||||
|
||||
これらの要件の目的は、AI で生成されたコードが十分に文書化され、追跡可能であることを保証し、コードレビューと後続のメンテナンスを容易にすることです。プロンプト/設計ドキュメントを要求することで、開発意図とコンテキストをより良く理解できます。
|
||||
|
||||
### 開発前の準備
|
||||
|
||||
```shell
|
||||
|
||||
Reference in New Issue
Block a user