AGENTS.md

1# CODEX Agent Configuration
2 
3This file demonstrates how `vibe-rules` formats and manages rules for the CODEX editor. Rules are stored as XML-like tagged blocks within a `<vibe-rules Integration>` section.
4 
5## Codex File Hierarchy
6 
7Codex looks for AGENTS.md files in the following places and merges them top-down:
8 
91. `~/.codex/AGENTS.md` - personal global guidance (use `--global` flag)
102. `AGENTS.md` at repo root - shared project notes (default behavior)
113. `AGENTS.md` in current working directory - sub-folder/feature specifics (use `--target` flag)
12 
13## Custom Project Rules
14 
15Add your custom CODEX rules here...
16 
17## Rule Examples
18 
19<!-- vibe-rules Integration -->
20<react-component-patterns>
21React Component Development Guidelines
22 
23Always Apply: true
24Globs: src/components/**/\*.tsx, src/components/**/\*.jsx
25 
26When creating React components:
27 
281. Use functional components with hooks instead of class components
292. Implement proper TypeScript interfaces for props
303. Use descriptive component and prop names
314. Extract complex logic into custom hooks
325. Add proper JSDoc comments for complex components
336. Use React.memo() for performance optimization when appropriate
347. Implement proper error boundaries for critical components
35   </react-component-patterns>
36 
37<api-design-patterns>
38API Development Best Practices
39 
40Always Apply: false
41Globs: src/api/**/\*.ts, src/routes/**/\*.ts
42 
43For API development:
44 
451. Use consistent REST conventions (GET, POST, PUT, DELETE)
462. Implement proper error handling with meaningful HTTP status codes
473. Use middleware for authentication and validation
484. Document APIs with OpenAPI/Swagger specifications
495. Implement rate limiting and request validation
506. Use proper TypeScript types for request/response objects
517. Add comprehensive logging for debugging
52   </api-design-patterns>
53 
54<testing-guidelines>
55Testing and Quality Assurance
56 
57Always Apply: true
58 
59Testing best practices:
60 
611. Write unit tests for all business logic functions
622. Use integration tests for API endpoints
633. Implement end-to-end tests for critical user flows
644. Maintain at least 80% code coverage
655. Use descriptive test names that explain the scenario
666. Mock external dependencies appropriately
677. Test both success and error cases
688. Use factories or fixtures for test data setup
69   </testing-guidelines>
70 
71<architecture-patterns>
72Software Architecture Guidelines
73 
74Globs: src/models/**/\*.ts, src/services/**/_.ts, src/utils/\*\*/_.ts
75 
76Architecture principles:
77 
781. Follow SOLID principles in class design
792. Use dependency injection for better testability
803. Implement proper separation of concerns
814. Use design patterns appropriately (Factory, Strategy, Observer)
825. Keep functions small and focused on single responsibility
836. Implement proper error handling and logging
847. Use TypeScript interfaces to define contracts
858. Follow consistent naming conventions
86</architecture-patterns>
87<!-- /vibe-rules Integration -->
88 
89## Additional Notes
90 
91The CODEX editor reads agent instructions from `AGENTS.md` files. The hierarchy allows for flexible configuration:
92 
93- Global rules apply to all projects
94- Project-root rules apply to the entire project
95- Directory-specific rules apply to current working directory contexts
96 
97Rules managed by `vibe-rules` are contained within the `<!-- vibe-rules Integration -->` comment block to distinguish them from manually added rules.
98 
99Rules can include metadata such as:
100 
101- **Always Apply**: Whether the rule should be automatically applied to all relevant contexts
102- **Globs**: File patterns that determine when the rule should be active
103 
104Use `vibe-rules` commands to manage these rules:
105 
106- `vibe-rules save my-rule -f ./my-rule.md` - Save a rule to local storage
107- `vibe-rules load my-rule codex` - Apply a saved rule to this file
108- `vibe-rules load my-rule codex --global` - Apply to global `~/.codex/AGENTS.md`
109- `vibe-rules load my-rule codex --target ./subdir/AGENTS.md` - Apply to specific directory
110- `vibe-rules install codex` - Install rules from NPM packages with `llms` exports
111