Skip to content

docs(claude): consolidate project documentation into CLAUDE.md (#335)#339

Merged
nanotaboada merged 2 commits into
masterfrom
docs/335-consolidate-project-documentation
Jun 8, 2026
Merged

docs(claude): consolidate project documentation into CLAUDE.md (#335)#339
nanotaboada merged 2 commits into
masterfrom
docs/335-consolidate-project-documentation

Conversation

@nanotaboada

@nanotaboada nanotaboada commented Jun 8, 2026

Copy link
Copy Markdown
Owner

Summary

  • Replace the CLAUDE.md stub (which delegated to .github/copilot-instructions.md via an @ include) with the full, self-contained content
  • Add Invariants section documenting non-negotiable project constraints (port, API contract, commit format, CHANGELOG requirement)
  • Add Architecture Decision Records section referencing docs/adr/ (implemented in Implement Architecture Decision Records (ADRs) #299)
  • Extend Pre-commit Checks with item 6: update CLAUDE.md and create/amend the relevant ADR when a commit introduces an architectural decision
  • Delete .github/copilot-instructions.md (content fully merged into CLAUDE.md)
  • Update .coderabbit.yaml: document intentional no-expiry cache behaviour in services path instruction; point knowledge_base.code_guidelines and the "sync documentation" finishing touch to CLAUDE.md

Test plan

Closes #335

🤖 Generated with Claude Code


This change is Reviewable

Summary by CodeRabbit

  • Documentation
    • Consolidated project guidelines and architecture decision records into centralized documentation.
    • Enhanced code review tooling with clarified cache configuration standards.
    • Integrated architecture decision tracking into pre-commit validation process.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Jun 8, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@nanotaboada, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 41 minutes and 18 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 3caf0fac-0941-42e4-a157-bdf2da738071

📥 Commits

Reviewing files that changed from the base of the PR and between f94c213 and 9fb61cd.

📒 Files selected for processing (1)
  • .coderabbit.yaml

Walkthrough

Consolidates AI agent project guidance from .github/copilot-instructions.md into CLAUDE.md as the single source of truth. Updates .coderabbit.yaml to reference CLAUDE.md and clarify Spring Cache no-expiry behavior. Records the consolidation and deletion in CHANGELOG.md.

Changes

Documentation Consolidation and Alignment

Layer / File(s) Summary
CLAUDE.md as consolidated source of truth
CLAUDE.md
CLAUDE.md is expanded from a two-line stub into comprehensive project guidance covering tech stack, structure/layering rules, coding guidelines, commands and commit conventions, Agent Mode instructions, invariants (port 9000, API contract, commit format), ADR directory reference, and workflow templates. Old reference to @.github/copilot-instructions.md is removed.
CodeRabbit configuration alignment
.coderabbit.yaml
"Sync documentation" custom step #3 is retargeted to CLAUDE.md (from .github/copilot-instructions.md) and updated to flag architecturally significant changes for ADR creation/amendment. knowledge_base.code_guidelines.filePatterns is updated to reference CLAUDE.md. Service path instructions are enhanced with explicit Spring Cache guidance: no-expiry caching is intentional, TTL suggestions are discouraged, and invalidation occurs only via @CacheEvict(allEntries = true) on write operations.
Changelog documentation
CHANGELOG.md
[Unreleased] → Changed section records documentation consolidation into CLAUDE.md (including Invariants and ADR sections), removal of .github/copilot-instructions.md, and corresponding .coderabbit.yaml instruction updates for cache behavior and documentation sync targets.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Assessment against linked issues

Objective Addressed Explanation
Consolidate documentation into CLAUDE.md and remove .github/copilot-instructions.md [#335]
CLAUDE.md contains Invariants section and ADR reference [#335]
CLAUDE.md pre-commit checklist includes ADR/CLAUDE.md update requirement [#335]
.coderabbit.yaml documents intentional no-expiry cache behavior [#335]
Update CHANGELOG.md [#335]

Possibly related issues

  • This PR directly addresses issue #335 (docs: verify, consolidate and align project documentation) by consolidating documentation into CLAUDE.md and updating tooling configuration.

Possibly related PRs

🚥 Pre-merge checks | ✅ 2
✅ Passed checks (2 passed)
Check name Status Explanation
Title check ✅ Passed The title uses Conventional Commits format (docs:), is descriptive and specific about consolidating documentation into CLAUDE.md, and is 69 characters—well under the 80-character limit.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

📋 Issue Planner

Built with CodeRabbit's Coding Plans for faster development and fewer bugs.

View plan used: #335

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/335-consolidate-project-documentation
  • 🛠️ sync documentation
  • 🛠️ enforce http error handling
  • 🛠️ idiomatic review
  • 🛠️ verify api contract

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

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

@codecov

codecov Bot commented Jun 8, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (6a6c841) to head (9fb61cd).

Additional details and impacted files
@@             Coverage Diff             @@
##              master      #339   +/-   ##
===========================================
  Coverage     100.00%   100.00%           
  Complexity        32        32           
===========================================
  Files              3         3           
  Lines             90        90           
  Branches           8         8           
===========================================
  Hits              90        90           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)
.coderabbit.yaml (2)

240-241: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Align allowed Conventional Commit types with documented invariants.

pre_merge_checks.title.requirements currently omits ci and perf, which conflicts with CLAUDE.md and may incorrectly warn on valid PR titles.

Suggested patch
-        - Use Conventional Commits format (feat:, fix:, chore:, docs:, test:, refactor:)
+        - Use Conventional Commits format (feat:, fix:, chore:, docs:, test:, refactor:, ci:, perf:)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.coderabbit.yaml around lines 240 - 241, pre_merge_checks.title.requirements
currently lists allowed Conventional Commit types but omits "ci" and "perf",
causing false warnings; update the pre_merge_checks.title.requirements
configuration to include "ci" and "perf" alongside existing types (e.g., feat,
fix, chore, docs, test, refactor) so it matches the invariants in CLAUDE.md and
accepts valid PR titles. Ensure the change updates the allowed types
array/string used by the title check logic referenced by
pre_merge_checks.title.requirements.

110-114: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Fix test DB guidance drift (H2 vs SQLite in-memory).

This path instruction contradicts the project’s documented test database strategy and will push reviewers toward wrong recommendations.

Suggested patch
     - path: "src/test/resources/application.properties"
       instructions: |
-        - Verify H2 in-memory database for tests
+        - Verify SQLite in-memory database for tests
         - Check test-specific configurations
         - Ensure proper test isolation settings

Based on learnings, this repository standard is in-memory SQLite for tests.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.coderabbit.yaml around lines 110 - 114, The guidance text under the YAML
entry whose path is "src/test/resources/application.properties" currently
references H2; update the "instructions" value to align with the repository
standard (in-memory SQLite) by replacing any "H2" mentions with "SQLite" and
changing checklist items to: verify in-memory SQLite for tests, check
test-specific SQLite configurations (e.g., JDBC URL like jdbc:sqlite::memory: or
equivalent), ensure proper test isolation and teardown for SQLite, and confirm
any ORM/connection-pool settings are compatible with SQLite in-memory mode; keep
the same YAML key "instructions" and the same path entry but update the bullet
content to these SQLite-focused checks.

Source: Learnings

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In @.coderabbit.yaml:
- Around line 240-241: pre_merge_checks.title.requirements currently lists
allowed Conventional Commit types but omits "ci" and "perf", causing false
warnings; update the pre_merge_checks.title.requirements configuration to
include "ci" and "perf" alongside existing types (e.g., feat, fix, chore, docs,
test, refactor) so it matches the invariants in CLAUDE.md and accepts valid PR
titles. Ensure the change updates the allowed types array/string used by the
title check logic referenced by pre_merge_checks.title.requirements.
- Around line 110-114: The guidance text under the YAML entry whose path is
"src/test/resources/application.properties" currently references H2; update the
"instructions" value to align with the repository standard (in-memory SQLite) by
replacing any "H2" mentions with "SQLite" and changing checklist items to:
verify in-memory SQLite for tests, check test-specific SQLite configurations
(e.g., JDBC URL like jdbc:sqlite::memory: or equivalent), ensure proper test
isolation and teardown for SQLite, and confirm any ORM/connection-pool settings
are compatible with SQLite in-memory mode; keep the same YAML key "instructions"
and the same path entry but update the bullet content to these SQLite-focused
checks.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f3b28558-bf50-4277-8ec1-5b432d390ca3

📥 Commits

Reviewing files that changed from the base of the PR and between 6a6c841 and f94c213.

📒 Files selected for processing (4)
  • .coderabbit.yaml
  • .github/copilot-instructions.md
  • CHANGELOG.md
  • CLAUDE.md
💤 Files with no reviewable changes (1)
  • .github/copilot-instructions.md

…#335)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
@sonarqubecloud

sonarqubecloud Bot commented Jun 8, 2026

Copy link
Copy Markdown

@nanotaboada nanotaboada merged commit a866013 into master Jun 8, 2026
12 checks passed
@nanotaboada nanotaboada deleted the docs/335-consolidate-project-documentation branch June 8, 2026 16:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: verify, consolidate and align project documentation

1 participant