Skip to content

Commit 55c5d5c

Browse files
bracesproulOpenSWE Bot
bracesproul
and
OpenSWE Bot
authored
Sync OpenSWE Documentation Files (#110)
This PR syncs documentation files from the OpenSWE repository. **Changes:** - Updated MDX files from `apps/docs/` - Target directory: `src/labs/swe/` - Updated images from `apps/docs/images/` - Target directory: `src/images/` - Source commit: 700bbf20f562c43c2f8c5b5e59ebae54cc0aa9b5 - Synced at 2025-08-04 20:33:02 UTC **Auto-generated by:** OpenSWE Documentation Sync Workflow --------- Co-authored-by: OpenSWE Bot <[email protected]>
1 parent d8fa0ae commit 55c5d5c

File tree

6 files changed

+256
-7
lines changed

6 files changed

+256
-7
lines changed

‎src/docs.json

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -289,18 +289,15 @@
289289
"labs/swe/index"
290290
]
291291
},
292-
{
293-
"group": "Examples",
294-
"pages": [
295-
"labs/swe/examples"
296-
]
297-
},
298292
{
299293
"group": "Usage",
300294
"pages": [
301295
"labs/swe/usage/intro",
302296
"labs/swe/usage/ui",
303-
"labs/swe/usage/github"
297+
"labs/swe/usage/github",
298+
"labs/swe/usage/best-practices",
299+
"labs/swe/usage/custom-rules",
300+
"labs/swe/usage/examples"
304301
]
305302
},
306303
{

‎src/images/quick_action_generate_agents_md.png

751 KB
Loading

‎src/labs/swe/usage/best-practices.mdx

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: Best Practices
3+
description: Guidelines for effective use of Open SWE
4+
---
5+
6+
# Best Practices
7+
8+
Follow these guidelines to get the best results from Open SWE.
9+
10+
## Prompting Tips
11+
12+
### Be Clear and Direct
13+
14+
- Include specific file paths and function names in your requests. Open SWE preforms best when its given a clear starting point.
15+
- 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.
16+
17+
### Create Custom Rules
18+
19+
Create an `AGENTS.md` file in your repository root to provide project-specific context. This helps Open SWE understand your codebase conventions and requirements.
20+
21+
<Tip>
22+
See the [Custom Rules](/labs/swe/usage/custom-rules) page for detailed guidance on
23+
setting up your `AGENTS.md` file.
24+
</Tip>
25+
26+
### Keep Tasks Well-Scoped
27+
28+
- Focus on one specific feature or fix per request
29+
- Break large changes into smaller, manageable tasks
30+
- Avoid combining multiple unrelated changes in a single request
31+
32+
### Avoid Multiple Tasks
33+
34+
Submit separate requests for different features or fixes. This allows Open SWE to:
35+
36+
- Generate more focused plans
37+
- Provide better error handling
38+
- Make changes easier to review
39+
40+
## Model Selection
41+
42+
- **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.
43+
- **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.
44+
45+
### Avoid Other Models
46+
47+
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.
48+
49+
## Mode Selection
50+
51+
### `open-swe` vs `open-swe-max`
52+
53+
**`open-swe`**: Uses Claude Sonnet 4
54+
55+
- Suitable for most development tasks
56+
- Faster execution
57+
- Cost-effective
58+
59+
**`open-swe-max`**: Uses Claude Opus 4 (only for the planning and code writing agents)
60+
61+
- For complex tasks requiring advanced reasoning
62+
- Higher quality output for challenging problems
63+
- More expensive but better for difficult tasks
64+
65+
### Auto vs Manual Labels
66+
67+
**Auto Mode (`-auto` labels)**
68+
69+
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.
70+
71+
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.
72+
73+
## Label Reference
74+
75+
- `open-swe`: Manual mode with Sonnet 4
76+
- `open-swe-auto`: Auto mode with Sonnet 4
77+
- `open-swe-max`: Manual mode with Opus 4
78+
- `open-swe-max-auto`: Auto mode with Opus 4
79+
80+
<Note>
81+
In development environments, append `-dev` to all labels (e.g.,
82+
`open-swe-dev`, `open-swe-auto-dev`).
83+
</Note>

‎src/labs/swe/usage/custom-rules.mdx

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
title: Custom Rules
3+
description: Configure Open SWE with project-specific rules using `AGENTS.md`
4+
---
5+
6+
# Custom Rules
7+
8+
Custom rules allow you to provide project-specific context and guidelines to Open SWE through a markdown file in your repository root.
9+
10+
## Getting Started
11+
12+
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.
13+
14+
![Quick Action Generate AGENTS.md](/images/quick_action_generate_agents_md.png)
15+
16+
## What is `AGENTS.md`?
17+
18+
`AGENTS.md` is a markdown file that tells Open SWE about your project's:
19+
20+
- Coding standards and conventions
21+
- Repository structure and architecture
22+
- Dependencies and installation procedures
23+
- Testing frameworks and practices
24+
- Pull request formatting requirements
25+
26+
## Why Use Custom Rules?
27+
28+
Custom rules help Open SWE:
29+
30+
- Follow your project's specific conventions
31+
- Understand your codebase architecture
32+
- Use the correct package managers and tools
33+
- Write tests that match your testing patterns
34+
- Generate properly formatted pull requests
35+
36+
Without custom rules, Open SWE uses generic best practices that may not align with your project.
37+
38+
## Supported Sections
39+
40+
### `<general_rules>`
41+
42+
Project-specific coding standards and conventions:
43+
44+
- Package manager preferences (e.g., "Always use Yarn")
45+
- Code style requirements
46+
- Import/export patterns
47+
- Architectural guidelines
48+
- Common scripts, and how to run them
49+
50+
Example: "Run `yarn test` to run tests", or "Run `yarn build` to build the project"
51+
52+
### `<repository_structure>`
53+
54+
Description of your codebase organization:
55+
56+
- Monorepo vs single package structure
57+
- Key directories and their purposes
58+
- Package relationships and dependencies
59+
- Build system configuration
60+
61+
Include context about where/how to create new files, apps, packages, etc. in this section.
62+
63+
Example: "When creating new packages, place them inside the `packages` directory."
64+
65+
### `<dependencies_and_installation>`
66+
67+
Package management and setup instructions:
68+
69+
- Package manager commands
70+
- Installation procedures
71+
- Key dependencies and their purposes
72+
- Workspace configuration details
73+
74+
This section should include information about the package manager(s) used in the project, and how/where to install dependencies.
75+
76+
Example: "Always install dependencies inside the specific app/package where they're used, never in the root `package.json` unless adding a resolution."
77+
78+
### `<testing_instructions>`
79+
80+
Testing framework and practices:
81+
82+
- Test runner configuration (Jest, Vitest, etc.)
83+
- Test file naming conventions
84+
- How to run different test types
85+
- Testing best practices for your project (e.g. what types of tests to write)
86+
87+
Example: "Always run `yarn test` after making changes."
88+
89+
### `<pull_request_formatting>`
90+
91+
PR creation and formatting guidelines:
92+
93+
- Title and description templates
94+
- Required sections or checklists
95+
- Review process requirements
96+
- Linking conventions
97+
98+
Example: "The pull request body should include a `Testing Steps` section which includes bullet points describing how to test the changes."
99+
100+
## File Names
101+
102+
Open SWE reads custom rules from these files (in order of precedence):
103+
104+
1. `AGENTS.md` (recommended)
105+
2. `AGENT.md`
106+
3. `CLAUDE.md`
107+
4. `CURSOR.md`
108+
109+
<Note>
110+
Use `AGENTS.md` as the standard filename for consistency across projects.
111+
</Note>
112+
113+
## Missing Sections
114+
115+
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.
116+
117+
## Formatting Example
118+
119+
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.
120+
121+
Known tags:
122+
- `<general_rules>`
123+
- `<repository_structure>`
124+
- `<dependencies_and_installation>`
125+
- `<testing_instructions>`
126+
- `<pull_request_formatting>`
127+
128+
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.
129+
130+
Here is an example showing what your `AGENTS.md` file should look like:
131+
132+
```markdown
133+
<general_rules>
134+
135+
- Always use Yarn as the package manager
136+
- Follow strict TypeScript practices
137+
- Use ESLint and Prettier for code quality
138+
</general_rules>
139+
140+
<repository_structure>
141+
This is a Yarn workspace monorepo with three main packages:
142+
143+
- apps/web: Next.js frontend
144+
- apps/api: Express backend
145+
- packages/shared: Common utilities
146+
</repository_structure>
147+
148+
<dependencies_and_installation>
149+
Run `yarn install` from the repository root to install all dependencies.
150+
Key dependencies include React 18, TypeScript, and Jest for testing.
151+
</dependencies_and_installation>
152+
153+
<testing_instructions>
154+
155+
- Run `yarn test` for unit tests
156+
- Run `yarn test:e2e` for end-to-end tests
157+
- Test files use `.test.ts` extension
158+
- Use Jest with React Testing Library
159+
</testing_instructions>
160+
161+
<pull_request_formatting>
162+
PR titles should follow: "feat: description" or "fix: description"
163+
Include a brief description and link any related issues.
164+
</pull_request_formatting>
165+
```

‎src/labs/swe/examples.mdx renamed to ‎src/labs/swe/usage/examples.mdx

File renamed without changes.

‎src/labs/swe/usage/github.mdx

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@ title: "From Github"
33
description: "How to use Open SWE from Github"
44
---
55

6+
<Warning>
7+
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).
8+
</Warning>
9+
610
# GitHub Webhook Integration
711

812
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.

0 commit comments

Comments
 (0)