From 399dcb1ead8d04ae901e26a63cf70485a77667fe Mon Sep 17 00:00:00 2001 From: johnlanni Date: Mon, 17 Nov 2025 20:40:58 +0800 Subject: [PATCH] docs: add Cursor project rules for AI coding with plugin development standards Change-Id: I3f578b11e29e018a746a9530d2995fec99eabb4b Co-developed-by: Cursor --- .cursor/rules/plugin-development.mdc | 135 +++++++++++++++++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 44 ++++++++- CONTRIBUTING_CN.md | 25 +++++ CONTRIBUTING_EN.md | 25 +++++ CONTRIBUTING_JP.md | 25 +++++ 5 files changed, 249 insertions(+), 5 deletions(-) create mode 100644 .cursor/rules/plugin-development.mdc diff --git a/.cursor/rules/plugin-development.mdc b/.cursor/rules/plugin-development.mdc new file mode 100644 index 000000000..2d3fed6c7 --- /dev/null +++ b/.cursor/rules/plugin-development.mdc @@ -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 diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index d773ccbc8..74044bd2b 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,17 +1,51 @@ -### Ⅰ. Describe what this PR did +## Ⅰ. Describe what this PR did -### Ⅱ. Does this pull request fix one issue? +## Ⅱ. Does this pull request fix one issue? -### Ⅲ. 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) + + +**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) + + + +### AI Coding Summary + -### Ⅴ. Special notes for reviews diff --git a/CONTRIBUTING_CN.md b/CONTRIBUTING_CN.md index 3fbcb0fe9..47700d78b 100644 --- a/CONTRIBUTING_CN.md +++ b/CONTRIBUTING_CN.md @@ -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 diff --git a/CONTRIBUTING_EN.md b/CONTRIBUTING_EN.md index 30b341083..5df39db4c 100644 --- a/CONTRIBUTING_EN.md +++ b/CONTRIBUTING_EN.md @@ -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 diff --git a/CONTRIBUTING_JP.md b/CONTRIBUTING_JP.md index 7916c56dd..5541a5220 100644 --- a/CONTRIBUTING_JP.md +++ b/CONTRIBUTING_JP.md @@ -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