From cf27bf1e5c6fad8c116bb7947e91ed24598a84d8 Mon Sep 17 00:00:00 2001 From: Mercy Ma Date: Tue, 26 May 2026 10:33:14 +0800 Subject: [PATCH] Add prompt templates and update onboarding Add three new agent prompt templates for developer workflows: document-api.prompt.md (generate OpenAPI specs), explain-code.prompt.md (clear code explanations), and generate-unit-tests.prompt.md (focused unit test generation). Update onboarding-plan.prompt.md to set the team to Microsphere Projects and change the background default to "the experienced developer new to this stack" to provide a more specific onboarding context. --- .github/prompts/document-api.prompt.md | 52 +++++++++++++++++++ .github/prompts/explain-code.prompt.md | 19 +++++++ .github/prompts/generate-unit-tests.prompt.md | 52 +++++++++++++++++++ .github/prompts/onboarding-plan.prompt.md | 4 +- 4 files changed, 125 insertions(+), 2 deletions(-) create mode 100644 .github/prompts/document-api.prompt.md create mode 100644 .github/prompts/explain-code.prompt.md create mode 100644 .github/prompts/generate-unit-tests.prompt.md diff --git a/.github/prompts/document-api.prompt.md b/.github/prompts/document-api.prompt.md new file mode 100644 index 000000000..cd44011b6 --- /dev/null +++ b/.github/prompts/document-api.prompt.md @@ -0,0 +1,52 @@ +--- +agent: 'agent' +description: 'Generate OpenAPI 3.0 specification for API endpoints' +--- + +## Task + +Analyze the API endpoint code and generate a valid OpenAPI 3.0 specification in YAML format. + +## OpenAPI Structure + +Generate a complete OpenAPI spec including: + +1. **OpenAPI Header** + - OpenAPI version (3.0.3) + - API info (title, description, version) + - Server configuration + +2. **Path Definitions** + - HTTP method and path + - Operation summary and description + - Tags for organization + +3. **Parameters Schema** + - Path parameters with type validation + - Query parameters with constraints and defaults + - Request body schema using proper JSON Schema + - Required vs optional parameters + +4. **Response Schemas** + - Success responses (200, 201, etc.) with schema definitions + - Error responses (400, 401, 404, 500) with error schema + - Content-Type specifications + - Realistic example values + +5. **Components Section** + - Reusable schemas for request/response models + - Security schemes (Bearer token, API key, etc.) + - Common parameter definitions + +## Requirements + +- Generate valid OpenAPI 3.0.3 YAML that passes validation +- Use proper JSON Schema for all data models +- Include realistic example values, not placeholders +- Define reusable components to avoid duplication +- Add appropriate data validation (required fields, formats, constraints) +- Include security requirements where applicable + +Focus on: ${input:endpoint_focus:Which specific endpoint or endpoints should be documented?} + +Generate production-ready OpenAPI specification that can be used with Swagger UI, Postman, and code generators. diff --git a/.github/prompts/explain-code.prompt.md b/.github/prompts/explain-code.prompt.md new file mode 100644 index 000000000..bff916b90 --- /dev/null +++ b/.github/prompts/explain-code.prompt.md @@ -0,0 +1,19 @@ +--- +agent: 'agent' +description: 'Generate a clear code explanation with examples' +--- + +Explain the following code in a clear, beginner-friendly way: + +Code to explain: ${input:code:Paste your code here} +Target audience: ${input:audience:Who is this explanation for? (e.g., beginners, intermediate developers, etc.)} + +Please provide: + +* A brief overview of what the code does +* A step-by-step breakdown of the main parts +* Explanation of any key concepts or terminology +* A simple example showing how it works +* Common use cases or when you might use this approach + +Use clear, simple language and avoid unnecessary jargon. diff --git a/.github/prompts/generate-unit-tests.prompt.md b/.github/prompts/generate-unit-tests.prompt.md new file mode 100644 index 000000000..84e4d5733 --- /dev/null +++ b/.github/prompts/generate-unit-tests.prompt.md @@ -0,0 +1,52 @@ +--- +agent: 'agent' +description: 'Generate unit tests for selected functions or methods' +--- + +## Task + +Analyze the selected function/method and generate focused unit tests that thoroughly validate its behavior. + +## Test Generation Strategy + +1. **Core Functionality Tests** + - Test the main purpose/expected behavior + - Verify return values with typical inputs + - Test with realistic data scenarios + +2. **Input Validation Tests** + - Test with invalid input types + - Test with null/undefined values + - Test with empty strings/arrays/objects + - Test boundary values (min/max, zero, negative numbers) + +3. **Error Handling Tests** + - Test expected exceptions are thrown + - Verify error messages are meaningful + - Test graceful handling of edge cases + +4. **Side Effects Tests** (if applicable) + - Verify external calls are made correctly + - Test state changes + - Validate interactions with dependencies + +## Test Structure Requirements + +- Use existing project testing framework and patterns +- Follow AAA pattern: Arrange, Act, Assert +- Write descriptive test names that explain the scenario +- Group related tests in describe/context blocks +- Mock external dependencies cleanly + +Target function: ${input:function_name:Which function or method should be tested?} +Testing framework: ${input:framework:Which framework? (jest/vitest/mocha/pytest/rspec/etc)} + +## Guidelines + +- Generate 5-8 focused test cases covering the most important scenarios +- Include realistic test data, not just simple examples +- Add comments for complex test setup or assertions +- Ensure tests are independent and can run in any order +- Focus on testing behavior, not implementation details + +Create tests that give confidence the function works correctly and help catch regressions. diff --git a/.github/prompts/onboarding-plan.prompt.md b/.github/prompts/onboarding-plan.prompt.md index 263227e63..96ee61b59 100644 --- a/.github/prompts/onboarding-plan.prompt.md +++ b/.github/prompts/onboarding-plan.prompt.md @@ -5,9 +5,9 @@ description: 'Help new team members onboard with a phased plan and suggestions f # Create My Onboarding Plan -I'm a new team member joining ${input:team:Team or project name} and I need help creating a structured onboarding plan. +I'm a new team member joining [Microsphere Projects](https://github.com/microsphere-projects) and I need help creating a structured onboarding plan. -My background: ${input:background:Briefly describe your experience level - new to tech, experienced developer new to this stack, etc.} +My background: the experienced developer new to this stack Please create a personalized phased onboarding plan that includes the following phases.