docs: verify, consolidate and align project documentation

[nanotaboada]

Context

This repo contains a REST API built with Java 25 and Spring Boot 4. Project guidance currently lives in two files: CLAUDE.md (a two-line stub with an @ include) and .github/copilot-instructions.md (the actual content). GitHub Copilot is no longer in use, making the split pointless. The goal is to establish CLAUDE.md as the single source of truth, verify its content against the code, and close gaps in .coderabbit.yaml.

Note: issue #299 (Implement Architecture Decision Records) has been implemented — docs/adr/ is live with all 12 ADRs. This issue should reference the existing directory directly rather than adding a forward reference.

Conflict resolution rule

The code is the source of truth. When copilot-instructions.md contradicts what the code actually does, fix the documentation — do not change the code.

Implementation steps

1. Verify copilot-instructions.md against the code

Before copying any content, read the actual code and confirm these claims are still accurate:

• No cache TTL: check src/main/java/**/services/PlayersService.java — @Cacheable should have no time-based expiry; cache invalidation should use @CacheEvict(allEntries = true) on writes only
• Constructor injection only: spot-check service and repository classes — no @Autowired field injection should be present
• @Transactional(readOnly = true) on reads: check service read methods
• In-memory SQLite for tests: check src/test/resources/application.properties — should configure an in-memory SQLite datasource
• BDD test naming (givenX_whenY_thenZ): spot-check test class names and method names
• Port 9000: check src/main/resources/application.properties

Document any discrepancies found. Correct copilot-instructions.md content before moving to step 2.

2. Consolidate into CLAUDE.md

Replace the entire content of CLAUDE.md with the (now-verified and corrected) content from .github/copilot-instructions.md. Then add:

## Invariants (never change without explicit discussion)

- Port: 9000
- API contract: endpoints, HTTP status codes, and response shapes are fixed;
  do not change them without explicit discussion
- Commit format: `type(scope): description (#issue)` — max 80 chars
- Conventional Commits types: feat fix chore docs test refactor ci perf
- CHANGELOG.md `[Unreleased]` section must be updated before every commit

## Architecture Decision Records

Architectural decisions are documented in [`docs/adr/`](../docs/adr/README.md).
When proposing structural changes, check both this file and the relevant ADR.
When a decision changes, update this file and create or amend the relevant ADR.

Then update the Pre-commit Checks section to add:

6. If this commit introduces or changes an architectural decision, update
   CLAUDE.md and create or amend the relevant ADR in `docs/adr/`.

Delete .github/copilot-instructions.md.

3. Update .coderabbit.yaml

Add to the src/**/services/**/*.java path instruction:

- Spring Cache is configured with NO expiry — this is intentional. Do not
  suggest adding a TTL or time-based eviction. Cache is invalidated only on
  write operations via @CacheEvict(allEntries = true).

Acceptance criteria

• Every claim in CLAUDE.md has been verified against the current code
• Any discrepancies found during verification are corrected in CLAUDE.md
• CLAUDE.md contains all content previously in copilot-instructions.md
• CLAUDE.md has an Invariants section and a reference to docs/adr/
• CLAUDE.md pre-commit checklist includes the ADR/CLAUDE.md update requirement
• .github/copilot-instructions.md is deleted
• .coderabbit.yaml service path instruction documents the intentional no-expiry cache behaviour
• CHANGELOG.md [Unreleased] updated
• No regressions in existing tests

References

• Implement Architecture Decision Records (ADRs) #299 — Implement Architecture Decision Records (implemented — docs/adr/ is live with all 12 ADRs)

[coderabbitai]

🔗 Related PRs

#266 - test: adopt BDD Given-When-Then pattern across all tests [merged]
#267 - docs: restructure AI instruction files [merged]
#284 - chore(claude): improve Claude Code integration [merged]
#297 - docs: normalize README structure and add RELEASES.md [merged]
#338 - docs(adr): implement Architecture Decision Records (#299) [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• All claims in copilot-instructions.md were verified accurate during codebase exploration—no corrections needed
• Consolidation is a straightforward content merge plus addition of two new sections (Invariants, ADR reference) and one Pre-commit Checks item
• The .coderabbit.yaml update adds a single instruction to an existing path_instructions block
• Changes are documentation-only with no impact on application behavior or tests

Implementation Steps

Phase 1: Consolidate Documentation into CLAUDE.md

This phase establishes CLAUDE.md as the single source of truth by incorporating all verified content and adding new required sections.

Task 1: Replace CLAUDE.md with Verified Content

Replace the current stub content in CLAUDE.md with the full content from .github/copilot-instructions.md.

• Remove the @.github/copilot-instructions.md include directive and the Claude Code section from CLAUDE.md
• Copy the entire verified content from .github/copilot-instructions.md (all sections: Overview, Tech Stack, Structure, Coding Guidelines, Commands, Pre-commit Checks, Agent Mode, Issue Templates, Key Workflows, Additional Resources)
• Preserve the existing Claude-specific /pre-commit command note by integrating it into the Commands section or keeping it as a separate Claude Code section at the end
• No content corrections needed—exploration verified all claims are accurate

Task 2: Add Invariants Section

Add a new section documenting project invariants that should not change without explicit discussion.

• Insert new "Invariants" section after the existing content (before any Claude-specific notes)
• Document the fixed port (9000), API contract stability, commit format requirements (type(scope): description (#issue) max 80 chars), Conventional Commits types (feat, fix, chore, docs, test, refactor, ci, perf), and CHANGELOG.md update requirement
• Position this section prominently since it defines non-negotiable project constraints

Task 3: Add ADR Reference Section

Add a section that references the existing ADR directory and explains the relationship between CLAUDE.md and ADRs.

• Insert "Architecture Decision Records" section after Invariants
• Include a relative link to docs/adr/README.md
• Explain that structural changes should check both CLAUDE.md and relevant ADRs
• Note that when decisions change, both this file and the relevant ADR should be updated

Task 4: Update Pre-commit Checks Section

Extend the existing Pre-commit Checks section with an ADR/documentation update requirement.

• Locate the existing Pre-commit Checks section (currently has 5 items)
• Add item 6: requirement to update CLAUDE.md and create/amend relevant ADR in docs/adr/ when a commit introduces or changes an architectural decision
• Maintain consistent numbering and formatting with existing items

🤖 Prompt for AI agents

Update `CLAUDE.md` to become the single source of truth for project
documentation, incorporating all content from `.github/copilot-instructions.md`
and adding new sections.

**Task 1: Replace stub content in `CLAUDE.md`**
- Remove the `@.github/copilot-instructions.md` include directive and the
existing Claude Code section
- Copy the full verified content from `.github/copilot-instructions.md`,
preserving all sections: Overview, Tech Stack, Structure, Coding Guidelines,
Commands, Pre-commit Checks, Agent Mode, Issue Templates, Key Workflows, and
Additional Resources
- Retain the Claude-specific `/pre-commit` command note, either integrated into
the Commands section or as a separate Claude Code section at the end
- No content corrections are needed — all claims have been verified as accurate

**Task 2: Add Invariants section**
- Insert a new "Invariants" section after the merged content (before any
Claude-specific notes)
- Document the following invariants:
  - Fixed port (9000)
  - API contract stability
  - Commit format: `type(scope): description (`#issue`)`, max 80 characters
  - Conventional Commits types: feat, fix, chore, docs, test, refactor, ci, perf
  - CHANGELOG.md update requirement

**Task 3: Add Architecture Decision Records section**
- Insert an "Architecture Decision Records" section after the Invariants section
- Include a relative link to `docs/adr/README.md`
- Explain that structural changes should consult both `CLAUDE.md` and relevant
ADRs
- Note that when decisions change, both this file and the relevant ADR must be
updated

**Task 4: Extend Pre-commit Checks section**
- Locate the Pre-commit Checks section (currently 5 items)
- Append item 6: when a commit introduces or changes an architectural decision,
update `CLAUDE.md` and create/amend the relevant ADR in `docs/adr/`
- Keep consistent numbering and formatting with existing items

Phase 2: Configuration Updates and Cleanup

This phase updates supporting configuration, removes the deprecated file, and documents changes.

Task 1: Update .coderabbit.yaml Services Path Instruction

Add cache behavior guidance to the services path instruction to prevent incorrect review suggestions.

• Locate the path_instructions entry for **/services/**/*.java in .coderabbit.yaml
• Append the cache instruction explaining that Spring Cache is intentionally configured with no expiry, not to suggest adding TTL or time-based eviction, and that cache invalidation occurs only on writes via @CacheEvict(allEntries = true)
• Maintain YAML formatting consistency with existing path instructions

Task 2: Delete Deprecated Copilot Instructions File

Remove the now-redundant GitHub Copilot instructions file.

• Delete .github/copilot-instructions.md entirely
• This file's content has been consolidated into CLAUDE.md
• Verify no other files reference this path (exploration shows only CLAUDE.md referenced it via @ include, which will be removed)

Task 3: Update CHANGELOG.md

Document the documentation consolidation in the unreleased section.

• Add entry to [Unreleased] section in CHANGELOG.md
• Document the consolidation of project documentation into CLAUDE.md
• Note the deletion of .github/copilot-instructions.md
• Note the addition of Invariants section and ADR reference
• Note the .coderabbit.yaml cache instruction update
• Use appropriate changelog category (likely "Changed" or "Documentation")

Task 4: Verify No Test Regressions

Confirm that documentation-only changes do not affect test execution.

• Run ./mvnw clean test to verify all tests still pass
• This is a documentation-only change so no regressions are expected, but verification is required per acceptance criteria
• No code changes are involved; this is a sanity check

🤖 Prompt for AI agents

Update `.coderabbit.yaml`, remove the deprecated Copilot instructions file,
update `CHANGELOG.md`, and verify tests.

**Task 1: Update `.coderabbit.yaml`**
- Locate the `path_instructions` entry for `**/services/**/*.java`
- Append a cache behavior instruction to that entry with the following guidance:
  - Spring Cache is intentionally configured with no expiry
  - Do not suggest adding TTL or time-based eviction
- Cache invalidation occurs only on writes via `@CacheEvict(allEntries = true)`
- Maintain YAML formatting consistency with existing path instructions

**Task 2: Delete `.github/copilot-instructions.md`**
- Delete the file `.github/copilot-instructions.md` entirely
- Its content has been consolidated into `CLAUDE.md`
- No other files reference this path (the only reference was the `@` include in
`CLAUDE.md`, which has already been removed)

**Task 3: Update `CHANGELOG.md`**
- Add a new entry under the `[Unreleased]` section using the appropriate
category ("Changed" or "Documentation")
- Include the following notes:
  - Consolidation of project documentation into `CLAUDE.md`
  - Deletion of `.github/copilot-instructions.md`
  - Addition of Invariants section and ADR reference in `CLAUDE.md`
  - Cache behavior instruction added to `.coderabbit.yaml`

**Task 4: Verify tests**
- Run `./mvnw clean test` to confirm all tests still pass
- This is a documentation-only change; no regressions are expected, but
verification is required

Research

This is a Spring Boot 4 REST API for managing football players, using Java 25, SQLite, and a layered architecture (controllers → services → repositories → models). Documentation currently lives in two places: a stub CLAUDE.md that includes .github/copilot-instructions.md via an @ reference, and the actual 148-line instruction file in .github/. The codebase exploration has verified all claims in the instructions are accurate: no cache TTL (using ConcurrentMapCache), @CacheEvict(allEntries=true) on writes only, constructor injection via @RequiredArgsConstructor, @Transactional(readOnly=true) on reads, in-memory SQLite for tests, BDD test naming, and port 9000. The docs/adr/ directory contains 12 accepted ADRs with a README index.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Update `CLAUDE.md` to become the single source of truth for project
documentation, incorporating all content from `.github/copilot-instructions.md`
and adding new sections.

**Task 1: Replace stub content in `CLAUDE.md`**
- Remove the `@.github/copilot-instructions.md` include directive and the
existing Claude Code section
- Copy the full verified content from `.github/copilot-instructions.md`,
preserving all sections: Overview, Tech Stack, Structure, Coding Guidelines,
Commands, Pre-commit Checks, Agent Mode, Issue Templates, Key Workflows, and
Additional Resources
- Retain the Claude-specific `/pre-commit` command note, either integrated into
the Commands section or as a separate Claude Code section at the end
- No content corrections are needed — all claims have been verified as accurate

**Task 2: Add Invariants section**
- Insert a new "Invariants" section after the merged content (before any
Claude-specific notes)
- Document the following invariants:
  - Fixed port (9000)
  - API contract stability
  - Commit format: `type(scope): description (`#issue`)`, max 80 characters
  - Conventional Commits types: feat, fix, chore, docs, test, refactor, ci, perf
  - CHANGELOG.md update requirement

**Task 3: Add Architecture Decision Records section**
- Insert an "Architecture Decision Records" section after the Invariants section
- Include a relative link to `docs/adr/README.md`
- Explain that structural changes should consult both `CLAUDE.md` and relevant
ADRs
- Note that when decisions change, both this file and the relevant ADR must be
updated

**Task 4: Extend Pre-commit Checks section**
- Locate the Pre-commit Checks section (currently 5 items)
- Append item 6: when a commit introduces or changes an architectural decision,
update `CLAUDE.md` and create/amend the relevant ADR in `docs/adr/`
- Keep consistent numbering and formatting with existing items
===============================================================================

Task: 2

Update `.coderabbit.yaml`, remove the deprecated Copilot instructions file,
update `CHANGELOG.md`, and verify tests.

**Task 1: Update `.coderabbit.yaml`**
- Locate the `path_instructions` entry for `**/services/**/*.java`
- Append a cache behavior instruction to that entry with the following guidance:
  - Spring Cache is intentionally configured with no expiry
  - Do not suggest adding TTL or time-based eviction
- Cache invalidation occurs only on writes via `@CacheEvict(allEntries = true)`
- Maintain YAML formatting consistency with existing path instructions

**Task 2: Delete `.github/copilot-instructions.md`**
- Delete the file `.github/copilot-instructions.md` entirely
- Its content has been consolidated into `CLAUDE.md`
- No other files reference this path (the only reference was the `@` include in
`CLAUDE.md`, which has already been removed)

**Task 3: Update `CHANGELOG.md`**
- Add a new entry under the `[Unreleased]` section using the appropriate
category ("Changed" or "Documentation")
- Include the following notes:
  - Consolidation of project documentation into `CLAUDE.md`
  - Deletion of `.github/copilot-instructions.md`
  - Addition of Invariants section and ADR reference in `CLAUDE.md`
  - Cache behavior instruction added to `.coderabbit.yaml`

**Task 4: Verify tests**
- Run `./mvnw clean test` to confirm all tests still pass
- This is a documentation-only change; no regressions are expected, but
verification is required

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!