diff --git a/apps/docs/docs.json b/apps/docs/docs.json index 8f1939d6..ae166820 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -17,13 +17,16 @@ "group": "Get Started", "pages": ["index"] }, - { - "group": "Examples", - "pages": ["examples"] - }, { "group": "Usage", - "pages": ["usage/intro", "usage/ui", "usage/github"] + "pages": [ + "usage/intro", + "usage/ui", + "usage/github", + "usage/examples", + "usage/best-practices", + "usage/custom-rules" + ] }, { "group": "Development Setup", diff --git a/apps/docs/images/quick_action_generate_agents_md.png b/apps/docs/images/quick_action_generate_agents_md.png new file mode 100644 index 00000000..c4f74ead Binary files /dev/null and b/apps/docs/images/quick_action_generate_agents_md.png differ diff --git a/apps/docs/usage/best-practices.mdx b/apps/docs/usage/best-practices.mdx new file mode 100644 index 00000000..dca487ca --- /dev/null +++ b/apps/docs/usage/best-practices.mdx @@ -0,0 +1,83 @@ +--- +title: Best Practices +description: Guidelines for effective use of Open SWE +--- + +# Best Practices + +Follow these guidelines to get the best results from Open SWE. + +## Prompting Tips + +### Be Clear and Direct + +- Include specific file paths and function names in your requests. Open SWE preforms best when its given a clear starting point. +- Provide concrete examples of what you want to achieve. Describe the end state you want to reach so Open SWE knows what it's working towards. + +### Create Custom Rules + +Create an `AGENTS.md` file in your repository root to provide project-specific context. This helps Open SWE understand your codebase conventions and requirements. + + + See the [Custom Rules](/labs/swe/usage/custom-rules) page for detailed guidance on + setting up your `AGENTS.md` file. + + +### Keep Tasks Well-Scoped + +- Focus on one specific feature or fix per request +- Break large changes into smaller, manageable tasks +- Avoid combining multiple unrelated changes in a single request + +### Avoid Multiple Tasks + +Submit separate requests for different features or fixes. This allows Open SWE to: + +- Generate more focused plans +- Provide better error handling +- Make changes easier to review + +## Model Selection + +- **Claude Sonnet 4 (Default)**: The default model for planning, writing code, and reviewing changes. This model offers the best balance of performance, speed and cost. +- **Claude Opus 4**: A larger, more powerful model for difficult, or open-ended tasks. Opus 4 is more expensive and slower, but will provide better results for complex tasks. + +### Avoid Other Models + +Although Open SWE allows you to select any model from Anthropic, OpenAI and Google, its prompts are tuned specifically for Anthropic models, and other providers will not preform as well. + +## Mode Selection + +### `open-swe` vs `open-swe-max` + +**`open-swe`**: Uses Claude Sonnet 4 + +- Suitable for most development tasks +- Faster execution +- Cost-effective + +**`open-swe-max`**: Uses Claude Opus 4 (only for the planning and code writing agents) + +- For complex tasks requiring advanced reasoning +- Higher quality output for challenging problems +- More expensive but better for difficult tasks + +### Auto vs Manual Labels + +**Auto Mode (`-auto` labels)** + +It's recommended to use the auto mode for most tasks. Open SWE is very good at planning, and in most cases it does not need a manual review before execution. + +If you're running Open SWE against an open-ended or very complex task, you may want to use manual mode to review the plan before execution. + +## Label Reference + +- `open-swe`: Manual mode with Sonnet 4 +- `open-swe-auto`: Auto mode with Sonnet 4 +- `open-swe-max`: Manual mode with Opus 4 +- `open-swe-max-auto`: Auto mode with Opus 4 + + + In development environments, append `-dev` to all labels (e.g., + `open-swe-dev`, `open-swe-auto-dev`). + diff --git a/apps/docs/usage/custom-rules.mdx b/apps/docs/usage/custom-rules.mdx new file mode 100644 index 00000000..b61eb25a --- /dev/null +++ b/apps/docs/usage/custom-rules.mdx @@ -0,0 +1,165 @@ +--- +title: Custom Rules +description: Configure Open SWE with project-specific rules using `AGENTS.md` +--- + +# Custom Rules + +Custom rules allow you to provide project-specific context and guidelines to Open SWE through a markdown file in your repository root. + +## Getting Started + +The easiest way to get started is to have Open SWE itself write this file for you! The Open SWE UI provides a "Generate `AGENTS.md`" quick action which will insert a predefined prompt into the input. This prompt has been designed to generate a well-formatted `AGENTS.md` file from the agent. + +![Quick Action Generate AGENTS.md](/images/quick_action_generate_agents_md.png) + +## What is `AGENTS.md`? + +`AGENTS.md` is a markdown file that tells Open SWE about your project's: + +- Coding standards and conventions +- Repository structure and architecture +- Dependencies and installation procedures +- Testing frameworks and practices +- Pull request formatting requirements + +## Why Use Custom Rules? + +Custom rules help Open SWE: + +- Follow your project's specific conventions +- Understand your codebase architecture +- Use the correct package managers and tools +- Write tests that match your testing patterns +- Generate properly formatted pull requests + +Without custom rules, Open SWE uses generic best practices that may not align with your project. + +## Supported Sections + +### `` + +Project-specific coding standards and conventions: + +- Package manager preferences (e.g., "Always use Yarn") +- Code style requirements +- Import/export patterns +- Architectural guidelines +- Common scripts, and how to run them + +Example: "Run `yarn test` to run tests", or "Run `yarn build` to build the project" + +### `` + +Description of your codebase organization: + +- Monorepo vs single package structure +- Key directories and their purposes +- Package relationships and dependencies +- Build system configuration + +Include context about where/how to create new files, apps, packages, etc. in this section. + +Example: "When creating new packages, place them inside the `packages` directory." + +### `` + +Package management and setup instructions: + +- Package manager commands +- Installation procedures +- Key dependencies and their purposes +- Workspace configuration details + +This section should include information about the package manager(s) used in the project, and how/where to install dependencies. + +Example: "Always install dependencies inside the specific app/package where they're used, never in the root `package.json` unless adding a resolution." + +### `` + +Testing framework and practices: + +- Test runner configuration (Jest, Vitest, etc.) +- Test file naming conventions +- How to run different test types +- Testing best practices for your project (e.g. what types of tests to write) + +Example: "Always run `yarn test` after making changes." + +### `` + +PR creation and formatting guidelines: + +- Title and description templates +- Required sections or checklists +- Review process requirements +- Linking conventions + +Example: "The pull request body should include a `Testing Steps` section which includes bullet points describing how to test the changes." + +## File Names + +Open SWE reads custom rules from these files (in order of precedence): + +1. `AGENTS.md` (recommended) +2. `AGENT.md` +3. `CLAUDE.md` +4. `CURSOR.md` + + + Use `AGENTS.md` as the standard filename for consistency across projects. + + +## Missing Sections + +If your custom rules file doesn't include XML section tags, the entire file content will be passed to the prompt inside a custom rules section. + +## Formatting Example + +If your custom rules file does include the proper XML section tags, only the content from inside the known tags will be passed to the system prompt. + +Known tags: +- `` +- `` +- `` +- `` +- `` + +Each tag _must_ contain a proper closing tag. If a tag is missing a closing tag, the entire file content will be passed to the prompt inside a custom rules section. + +Here is an example showing what your `AGENTS.md` file should look like: + +```markdown + + +- Always use Yarn as the package manager +- Follow strict TypeScript practices +- Use ESLint and Prettier for code quality + + + +This is a Yarn workspace monorepo with three main packages: + +- apps/web: Next.js frontend +- apps/api: Express backend +- packages/shared: Common utilities + + + +Run `yarn install` from the repository root to install all dependencies. +Key dependencies include React 18, TypeScript, and Jest for testing. + + + + +- Run `yarn test` for unit tests +- Run `yarn test:e2e` for end-to-end tests +- Test files use `.test.ts` extension +- Use Jest with React Testing Library + + + +PR titles should follow: "feat: description" or "fix: description" +Include a brief description and link any related issues. + +``` diff --git a/apps/docs/examples.mdx b/apps/docs/usage/examples.mdx similarity index 100% rename from apps/docs/examples.mdx rename to apps/docs/usage/examples.mdx diff --git a/apps/docs/usage/github.mdx b/apps/docs/usage/github.mdx index 9310fb84..85ae2283 100644 --- a/apps/docs/usage/github.mdx +++ b/apps/docs/usage/github.mdx @@ -3,6 +3,10 @@ title: "From Github" description: "How to use Open SWE from Github" --- + + GitHub webhooks are _not_ available via the demo application. To use GitHub webhooks, you must set up your own instance of Open SWE following the [development setup guide](/labs/swe/setup/development). + + # GitHub Webhook Integration Open SWE integrates seamlessly with GitHub through webhooks, allowing you to trigger automated code changes directly from GitHub issues. This provides a streamlined workflow where you can request code changes by simply adding labels to issues in repositories where Open SWE is installed.