improve: add documentation guidline for agents (#3339)

Signed-off-by: Attila Mészáros <a_meszaros@apple.com>

Author: csviri

.gitignore

@@ -17,3 +17,4 @@ target/
 .aider*
 
 docs/content/en/docs/testindex/
+.claude/

AGENTS.md

@@ -188,6 +188,37 @@ public class ConfigMapDependent extends CRUDKubernetesDependentResource<ConfigMa
 - Reference issues in commit messages when applicable
 - Ensure CI checks pass (format, license, tests)
 
+### Documentation Update
+
+When implementing features or making code changes, always evaluate whether the change affects user-facing behavior that should be documented. If so, update the documentation as part of the same change.
+
+#### Documentation Location
+
+Documentation is a Hugo/Docsy site at `docs/content/en/docs/`:
+
+- `documentation/` — core feature docs (reconciler, eventing, error handling, caches, rate limiting, testing, features)
+- `documentation/dependent-resource-and-workflows/` — dependent resources and workflows
+- `documentation/operations/` — operational concerns (config, metrics, logging, health probes, leader election, helm)
+- `getting-started/` — introductory guides and best practices
+- `migration/` — version migration guides
+- `faq/` — frequently asked questions
+
+#### Behavior
+
+1. Skip if not relevant — internal refactors, test-only changes, and build tooling changes typically do not need doc updates.
+2. After implementing a code change, check if it introduces, modifies, or removes user-facing behavior.
+3. Search the docs for pages covering the affected functionality.
+4. Update existing pages or add new sections to reflect the change.
+
+
+#### Guidelines
+
+- Match the tone and style of the existing documentation
+- Prefer adding code snippets
+- Keep explanations concise with code examples where helpful
+- If a change introduces a new feature, consider whether it belongs in an existing page or warrants a new one
+- For breaking changes, also update the relevant migration guide under `migration/`
+
 ## Common Issues and Solutions
 
 ### Build Issues
@@ -209,7 +240,6 @@ public class ConfigMapDependent extends CRUDKubernetesDependentResource<ConfigMa
 - **Discord:** https://discord.gg/DacEhAy
 - **Fabric8 Client:** https://github.com/fabric8io/kubernetes-client
 
-
 ## Additional Notes for AI Agents
 
 - The codebase makes extensive use of Java generics for type safety

docs/content/en/docs/documentation/reconciler.md

@@ -98,10 +98,10 @@ typically instructs the framework to remove the finalizer after the dependent
 resource are cleaned up in `cleanup` implementation.
 
 ```java
-public DeleteControl cleanup(MyCustomResource customResource,Context context){
+public DeleteControl cleanup(MyCustomResource customResource,Context context) {
         // omitted code
 
-        return DeleteControl.defaultDelete();
+return DeleteControl.defaultDelete();
 }
 ```