3.6 KiB
/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:
/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:
- Select task
- Understand task
- Implement task
- Test task
- Document task
- Commit task
- 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:
- Explain proposed change
- Explain risk
- Explain rollback
- Generate implementation plan
Do not execute destructive changes automatically.
Git Rules
Preferred workflow:
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:
Verified
Only when actually verified.
Use:
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.