docs: improve CLAUDE.md with governance, local dev, observability, and ADR sections

[redhat-ship-help]

Summary

Improves CLAUDE.md by adding several sections that were missing but documented elsewhere in the repository. All original content is preserved.

What's Added

Governance & Agent Guidelines

• Layered docs table — quick-reference showing the purpose of CLAUDE.md, CONTRIBUTING.md, BOOKMARKS.md, .claude/context/, .claude/patterns/, .claude/skills/, .claude/commands/, and .claude/amber-config.yml
• Agent rules — consolidated from amber.md and constitution.md: user-scoped K8s clients, no secret logging, linter requirements, PR size limits, escalation thresholds
• Context files & patterns — explicit pointers so agents discover .claude/context/ and .claude/patterns/ files

Architecture Decisions

• References all 7 ADRs in docs/internal/adr/ with one-line descriptions

Local Development

• Prerequisites (Go 1.24+, Node.js 20+, Python 3.11+, Podman/Docker, Kind/kubectl)
• Quick-start commands (make kind-up, local-up, local-down, etc.)
• Basic troubleshooting commands

Observability

• Pointers to Langfuse integration, Grafana dashboards, and observability overview docs

Stats

1 file changed, 105 insertions(+), 10 deletions(-)

Motivation

CLAUDE.md is loaded into AI agent context windows. Having governance rules, local dev setup, and architectural context directly in this file means agents start with better guidance — reducing hallucination, improving code quality, and avoiding common mistakes (e.g., using service account clients instead of user-scoped clients).

---

Created via Ship Help Bot at the request of a team member.

Summary by CodeRabbit

• Documentation
  • Updated developer documentation with enhanced governance guidelines and agent rules.
  • Added local development setup guidance with quick-start commands and Kubernetes troubleshooting resources.
  • Expanded observability section with tracing and metrics documentation references.
  • Improved formatting and alignment in command examples.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f866e570-7a16-436c-9362-e95783a1d029

📥 Commits

Reviewing files that changed from the base of the PR and between 005806f and 44dc6ab.

📒 Files selected for processing (1)

• CLAUDE.md

---

📝 Walkthrough

Walkthrough

Documentation expansion to CLAUDE.md covering AI agent governance rules, local development setup guidance, observability references, and command example formatting adjustments. Adds prerequisites, Kubernetes troubleshooting, mandatory agent constraints, and links to supporting architecture/observability docs.

Changes

Cohort / File(s)

Summary

Documentation Updates CLAUDE.md

Added Governance & Agent Guidelines section with mandatory AI agent rules (K8s scoping, no secret logging, linter compliance, commit conventions, PR size limits, no force-push without review, CI enforcement). Added Local Development section with prerequisites, make local-* quick starts, and K8s troubleshooting. Added Observability section referencing Langfuse and Grafana docs. Minor whitespace adjustments to command examples.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Title follows Conventional Commits format (docs: ...) and accurately summarizes the main changes: governance, local dev, observability, and ADR sections added to CLAUDE.md.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Performance And Algorithmic Complexity	✅ Passed	Pull request modifies only CLAUDE.md documentation file; no code changes present that could introduce performance regressions.
Security And Secret Handling	✅ Passed	CLAUDE.md contains only architectural documentation with no security violations, proper references to security best practices, and no exposed secrets or credentials.
Kubernetes Resource Safety	✅ Passed	Pull request modifies only CLAUDE.md documentation file; no Kubernetes manifests, resource definitions, RBAC configurations, or container specifications present.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

✨ Simplify code

• Create PR with simplified code

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[redhat-ship-help]

Closing per request — this was a test PR.