|
Hi Thành Nguyễn,
When working with Qoder, your project rules file is essentially a README for the AI. A well-crafted rules file helps the coding agent quickly grasp your project structure, tech stack, and coding conventions, leading to more accurate code generation.
How do you write one systematically? We found inspiration in the classic 12-Factor App methodology.
Rules & AGENTS.md: Same Purpose, Different Paths
Qoder supports two ways to define project rules:
|
Approach
|
Path
|
Notes
|
|
Qoder Rules
|
.qoder/rules/*.md
|
Qoder-native, supports multiple files
|
|
AGENTS.md
|
AGENTS.md at the root directory
|
Industry standard, single file
|
Both work exactly the same way, auto loaded into agent context. Pick whichever you prefer and stay consistent.
The latest Qoder supports AGENTS.md across IDE, CLI, and JetBrains Plugin.
The 12-Factor Methodology for AI Coding Agents
I. Codebase: Declare the Basics
Tell the agent your language, build tools, and test framework:
## Codebase
- Java 25
- Apache Maven 3.9.11
- JUnit 6.0.0
- Spring Boot 4.0 with Spring MVC
Don't forget project architecture and structure. It's the foundation for how the agent organizes code.
II. Dependencies: List What Matters
Include only the essentials, with context on usage:
## Dependencies
- com.fasterxml.jackson.core:jackson-databind:2.20.1: JSON serialization
- com.github.ben-manes.caffeine:caffeine:3.2.3: In-memory caching
For newer frameworks the LLM might not know well, add code samples.
III. Config: Point to Your Config Files
Let the agent know where configuration lives: .env, application.properties, or YAML/TOML files. If .env is ignored, list key variable names so the agent uses them correctly in generated code.
IV. Backing Services: Declare External Services/Resources
Database, cache, message queue, and other infra-layer services:
### Database
- Main database: PostgreSQL 18.1
- Database migration: Flyway 11
- ORM: Spring Data JDBC with JPA annotations
V. Build & Run: Document Your Workflow
Especially custom tasks:
## Build and run
- Build: mvn -DskipTests package
- Run: mvn -DskipTests spring-boot:run
VI. Port Binding: Specify Listening Port
Help the agent understand how your app exposes services:
- 8080: web server
- 8081: actuator and health check
VII. Logs: Define Logging Practices
Specify your logging framework (e.g., slf4j + logback) and conventions. Pro tip: remind the agent to use proper logging instead of System.out.println().
One More Thing
Keep it concise. Agent context windows have limits.
Tip: In Qoder, we recommend staying under 500 lines.
Tailor to your project. The goal is simple: give the agent the context it needs to understand your codebase.
|
