mirror of
https://github.com/alibaba/higress.git
synced 2026-06-09 04:37:31 +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:
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 -->
|
<!-- 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. -->
|
<!-- 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) 来完成拉取请求。
|
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
|
```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.
|
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
|
### Pre-development preparation
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
|
|||||||
@@ -164,6 +164,31 @@ git config --get user.email
|
|||||||
|
|
||||||
PR は Higress プロジェクトファイルを変更する唯一の方法です。レビュアーが目的をよりよく理解できるようにするために、PR 説明は詳細すぎることはありません。貢献者には、[PR テンプレート](./.github/PULL_REQUEST_TEMPLATE.md) に従ってプルリクエストを完了することを奨励します。
|
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
|
```shell
|
||||||
|
|||||||
Reference in New Issue
Block a user