docs(claude): consolidate and align project documentation (#590)

[nanotaboada]

Summary

• Verified all documentation claims against the code; corrected cache layer description (services/ does not manage the cache — routes/ does via aiocache)
• Consolidated .github/copilot-instructions.md into CLAUDE.md as the single source of truth; deleted the now-redundant Copilot file
• Added Invariants and Architecture Decision Records sections to CLAUDE.md; extended pre-commit checklist with ADR update requirement (step 7)
• Fixed docs/adr/README.md: corrected ADR-0002 status to Superseded; added missing ADR-0010 row
• Updated .coderabbit.yaml: precise 422/400/404/409 guidance in enforce http error handling; references updated from copilot-instructions.md → CLAUDE.md; new alembic/versions/**/*.py path instruction enforcing append-only migration policy

Test plan

• uv run flake8 . — passed
• uv run black --check . — passed (22 files unchanged)
• uv run pytest --cov=./ --cov-report=term --cov-fail-under=80 — 25 passed, 97.56% coverage
• Docker — not running, skipped
• CodeRabbit CLI (--prompt-only) — no findings

Closes #590

🤖 Generated with Claude Code

---

This change is 

Summary by CodeRabbit

• Documentation

  • Consolidated development guidelines into unified documentation file.
  • Enhanced API documentation with explicit 422 Unprocessable Entity responses for validation errors.
  • Updated architecture decision record (ADR) index with status changes and new migration management entry.

• Chores

  • Refined code review configuration with updated HTTP error handling guidance and migration workflow rules.

[coderabbitai]

Warning

Ignoring CodeRabbit configuration file changes. For security, only the configuration from the base branch is applied for open source repositories.

Walkthrough

This PR consolidates project guidance and documentation standards. It expands CLAUDE.md from a stub into comprehensive guidance covering architecture, coding standards, and workflows; updates ADR index status and adds ADR-0010; refines CodeRabbit reviewer configuration for migrations and HTTP error handling; and removes the deprecated .github/copilot-instructions.md after consolidating its content into CLAUDE.md.

Changes

Documentation Consolidation and Guidance Standardization

Layer / File(s)	Summary
CLAUDE.md Consolidation and Expansion CLAUDE.md	Expands from a 2-line stub into ~241 lines of comprehensive project guidance: REST/FastAPI architecture rules, tech stack enumeration, coding guidelines (async/SQLAlchemy/Pydantic conventions, API contracts, error handling, caching, logging, limits), command workflows (quick start, pre-commit, commit message conventions, migration commands), Agent Mode instructions (what can proceed freely vs require confirmation, what must never change), repo invariants (port, API contract stability, commit format, CHANGELOG requirements), and ADR references.
ADR Index Status Update docs/adr/README.md	ADR-0002 status changed from Accepted to Superseded; new ADR-0010 entry (Alembic Migration-Based Schema Management, 2026-04-09) added to index table.
CodeRabbit Configuration Refinement .coderabbit.yaml	Added path instructions for alembic/versions/**/*.py enforcing append-only migrations, forbidding standalone seed scripts, and requiring render_as_batch=True for SQLite support; updated "enforce http error handling" rule to specify 422 for Pydantic validation, 400 for semantic request errors, 409 for duplicate conflicts, and 404 for missing resources; changed knowledge base code_guidelines file pattern from .github/copilot-instructions.md to CLAUDE.md.
Changelog Documentation CHANGELOG.md	Updated [Unreleased] section: Changed entries document CLAUDE.md expansion with invariants/ADRs and pre-commit steps, .coderabbit.yaml HTTP error handling and migration enforcement, and explicit 422 documentation in routes; Fixed entries record ADR-0002 status and ADR-0010 addition in docs/adr/README.md; Removed entry documents .github/copilot-instructions.md deletion after consolidation.

---

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

---

Assessment against linked issues

Objective	Addressed	Explanation
Consolidate copilot-instructions.md into CLAUDE.md as single source of truth [#590]	✅
Add Alembic migration path instructions to .coderabbit.yaml enforcing append-only and seed-in-migrations [#590]	✅
Update HTTP error handling guidance in .coderabbit.yaml to distinguish 422 (validation) from 400 (semantic) [#590]	✅
Mark ADR-0002 as Superseded and add ADR-0010 to index [#590]	✅
Remove .github/copilot-instructions.md after consolidation [#590]	✅

---

Possibly related issues

• nanotaboada/rust-samples-rocket-restful#112: Similar documentation consolidation effort across another language/framework repository with identical objectives (consolidate copilot-instructions into CLAUDE.md, update CodeRabbit config, mark/add ADRs).
• nanotaboada/java.samples.spring.boot#335: Parallel documentation standardization effort consolidating .github/copilot-instructions.md into CLAUDE.md and refining .coderabbit.yaml guidance across another project variant.

---

Possibly related PRs

• nanotaboada/python-samples-fastapi-restful#540: Adds "Claude Code" section to CLAUDE.md including pre-commit guidance directly related to this PR's expansion of the same file.
• nanotaboada/python-samples-fastapi-restful#509: Modifies .coderabbit.yaml HTTP error handling instructions and knowledge-base file pattern configuration—the exact same configuration elements refined in this PR.
• nanotaboada/python-samples-fastapi-restful#462: Updates .coderabbit.yaml with path instructions and knowledge-base configuration changes related to this PR's CodeRabbit refinements.

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title follows Conventional Commits format (docs:), is under 80 characters (64 chars), and accurately summarizes the main objective of consolidating and aligning project documentation by making CLAUDE.md the single source of truth.
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: #590

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/verify-consolidate-align-documentation-590

• 🛠️ 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

• X
• Mastodon
• Reddit
• LinkedIn

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (5d71447) to head (8ac9b67).

Additional details and impacted files

@@            Coverage Diff            @@
##            master      #593   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            7         7           
  Lines          172       172           
=========================================
  Hits           172       172           

☔ 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.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

🧹 Nitpick comments (1)

CLAUDE.md (1)

145-149: 💤 Low value

Specify language identifier for fenced code block.

The fenced code block listing coach names should have a language identifier (e.g., text or leave it as plain text with explicit identifier).

📝 Proposed fix

-```
+```text
 ancelotti bielsa capello delbosque eriksson ferguson guardiola heynckes
 inzaghi klopp kovac low mourinho nagelsmann ottmar pochettino queiroz
 ranieri simeone tuchel unai vangaal wenger xavi yozhef zeman

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

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

In @CLAUDE.md around lines 145 - 149, Update the fenced code block that lists
coach names so it includes a language identifier: change the opening fence from
totext for the block that contains "ancelotti bielsa capello ..." and
keep the closing fence as ``` so the block is explicitly marked as plain text.

</details>

<!-- cr-comment:v1:d688878e20ea79a3ffec632a -->

_Source: Linters/SAST tools_

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

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

Nitpick comments:
In @CLAUDE.md:

• Around line 145-149: Update the fenced code block that lists coach names so it
  includes a language identifier: change the opening fence from totext for
  the block that contains "ancelotti bielsa capello ..." and keep the closing
  fence as ``` so the block is explicitly marked as plain text.

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: Path: .coderabbit.yaml

**Review profile**: CHILL

**Plan**: Pro

**Run ID**: `bb89d198-f793-44bb-9f6c-6b930ddc83e4`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between 9e254a4a1fb83635676ab462ee8fa943d6cba289 and 8a275502e044d4e02461e1991e6f33a9438e5bbd.

</details>

<details>
<summary>📒 Files selected for processing (5)</summary>

* `.coderabbit.yaml`
* `.github/copilot-instructions.md`
* `CHANGELOG.md`
* `CLAUDE.md`
* `docs/adr/README.md`

</details>

<details>
<summary>💤 Files with no reviewable changes (1)</summary>

* .github/copilot-instructions.md

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud