# `/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.

---

# Objectivity

- Do not praise, flatter, or agree unnecessarily.
- Do not repeat information the user already knows.
- State problems directly without hedging or softening.
- Provide factual assessments; separate observation from opinion.

---

# Context Discipline

- Read each file at most once unless its content changed between reads.
- Do not re-read context files that were read earlier in the same session unless explicitly asked.
- Track which files you have already read in your working notes rather than reloading them.

---

# Communication Efficiency

- Do not restate the task or requirements before acting.
- Skip summarising instructions the user has already given.
- Provide results, not process descriptions, unless asked for a rationale.
- Use concise technical language; avoid filler phrases ("sure", "great", "I can help with that").

---

# Execution Efficiency

- Act on the task immediately after understanding it.
- Avoid unnecessary planning or confirmation steps when the next action is clear.
- Report only what changed, not everything you considered.

---

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