270 lines
3.6 KiB
Markdown
270 lines
3.6 KiB
Markdown
# `/context/agent-guidelines.md`
|
|
|
|
# Agent Operating Guidelines
|
|
|
|
This file defines how AI coding agents should behave when working on RDB Solutions Ltd projects.
|
|
|
|
These rules apply to:
|
|
|
|
- OpenHands
|
|
- Claude Code
|
|
- Cursor Agents
|
|
- Copilot Agents
|
|
- Local coding agents
|
|
- Future autonomous development systems
|
|
|
|
---
|
|
|
|
# Core Rule
|
|
|
|
Make the smallest useful change possible.
|
|
|
|
Agents should favour many small successful changes over large risky changes.
|
|
|
|
---
|
|
|
|
# Before Starting Work
|
|
|
|
Agents should first read:
|
|
|
|
```text
|
|
/context/company-context.md
|
|
/context/infrastructure-context.md
|
|
/context/development-context.md
|
|
README.md
|
|
ARCHITECTURE.md
|
|
TASKS.md
|
|
```
|
|
|
|
If these files exist.
|
|
|
|
---
|
|
|
|
# Task Execution Model
|
|
|
|
Work should be completed using backlog items.
|
|
|
|
Recommended process:
|
|
|
|
1. Select task
|
|
2. Understand task
|
|
3. Implement task
|
|
4. Test task
|
|
5. Document task
|
|
6. Commit task
|
|
7. Move to next task
|
|
|
|
Avoid combining unrelated tasks.
|
|
|
|
---
|
|
|
|
# Safe Change Policy
|
|
|
|
Agents should:
|
|
|
|
✅ Add functionality
|
|
|
|
✅ Fix defects
|
|
|
|
✅ Improve documentation
|
|
|
|
✅ Add tests
|
|
|
|
✅ Refactor locally
|
|
|
|
Agents should not:
|
|
|
|
❌ Rewrite entire systems
|
|
|
|
❌ Replace frameworks
|
|
|
|
❌ Change infrastructure architecture
|
|
|
|
❌ Change deployment methods
|
|
|
|
❌ Delete large amounts of code
|
|
|
|
Without explicit approval.
|
|
|
|
---
|
|
|
|
# Code Generation Standards
|
|
|
|
Generated code should:
|
|
|
|
- Be readable
|
|
- Be maintainable
|
|
- Follow existing project patterns
|
|
- Include error handling
|
|
- Include logging where appropriate
|
|
|
|
Avoid:
|
|
|
|
- Clever code
|
|
- Unnecessary abstractions
|
|
- Premature optimisation
|
|
|
|
---
|
|
|
|
# Infrastructure Changes
|
|
|
|
Infrastructure changes require higher scrutiny.
|
|
|
|
Examples:
|
|
|
|
- Jenkins
|
|
- Gitea
|
|
- Supabase
|
|
- Reverse proxies
|
|
- DNS
|
|
- Production deployments
|
|
|
|
For infrastructure work:
|
|
|
|
1. Explain proposed change
|
|
2. Explain risk
|
|
3. Explain rollback
|
|
4. Generate implementation plan
|
|
|
|
Do not execute destructive changes automatically.
|
|
|
|
---
|
|
|
|
# Git Rules
|
|
|
|
Preferred workflow:
|
|
|
|
```text
|
|
Create branch
|
|
Make change
|
|
Run tests
|
|
Commit
|
|
Create PR
|
|
```
|
|
|
|
Commit frequently.
|
|
|
|
Commit messages should be descriptive.
|
|
|
|
---
|
|
|
|
# Testing Requirements
|
|
|
|
Where practical:
|
|
|
|
- Unit tests
|
|
- Integration tests
|
|
- Build validation
|
|
|
|
Agents should never claim testing was performed if it was not.
|
|
|
|
Use:
|
|
|
|
```text
|
|
Verified
|
|
```
|
|
|
|
Only when actually verified.
|
|
|
|
Use:
|
|
|
|
```text
|
|
Not tested
|
|
```
|
|
|
|
When testing was not possible.
|
|
|
|
---
|
|
|
|
# Documentation Requirements
|
|
|
|
If behaviour changes:
|
|
|
|
Update:
|
|
|
|
- README
|
|
- Architecture docs
|
|
- API docs
|
|
- Task status
|
|
|
|
where applicable.
|
|
|
|
Documentation is part of the task.
|
|
|
|
---
|
|
|
|
# Autonomous Work Limits
|
|
|
|
Agents may autonomously:
|
|
|
|
- Create files
|
|
- Modify files
|
|
- Add tests
|
|
- Add documentation
|
|
- Refactor small areas
|
|
|
|
Agents should request approval before:
|
|
|
|
- Deleting files
|
|
- Deleting databases
|
|
- Deploying to production
|
|
- Changing authentication
|
|
- Changing networking
|
|
- Modifying CI/CD pipelines
|
|
|
|
---
|
|
|
|
# Preferred Deliverables
|
|
|
|
When completing work, agents should provide:
|
|
|
|
## Summary
|
|
|
|
What was changed.
|
|
|
|
## Files Modified
|
|
|
|
List of modified files.
|
|
|
|
## Validation
|
|
|
|
Tests executed and results.
|
|
|
|
## Risks
|
|
|
|
Potential side effects.
|
|
|
|
## Next Recommended Task
|
|
|
|
Small logical follow-up task.
|
|
|
|
---
|
|
|
|
# RDB-Specific Preferences
|
|
|
|
Remember:
|
|
|
|
- Gitea over GitHub
|
|
- Jenkins over cloud CI systems
|
|
- Docker preferred
|
|
- Proxmox preferred
|
|
- Local LLMs preferred
|
|
- Self-hosted services preferred
|
|
- Incremental change preferred
|
|
|
|
Do not recommend cloud replacements unless there is a significant advantage.
|
|
|
|
---
|
|
|
|
# Success Criteria
|
|
|
|
A task is complete when:
|
|
|
|
- Requirements are met
|
|
- Tests pass
|
|
- Documentation is updated
|
|
- Changes are understandable
|
|
- Rollback is possible
|
|
|
|
Optimise for maintainability and long-term ownership rather than speed alone.
|