docs: add AGENTS.md and CLAUDE.md

[matteoredz]

Summary

Introduces two documentation files aimed at improving the developer and LLM experience when working with this codebase.

AGENTS.md — LLM Codebase Reference

A structured reference document for LLMs (and humans) covering:

• Tax code structure and segment encoding rules
• Full architecture overview with class responsibilities and key file index
• Complete public API with signatures and return shapes
• Error hierarchy
• Key implementation details and edge cases (omocodia, female day encoding, city validity dates, CIN algorithm, etc.)
• Development commands and testing conventions

CLAUDE.md — Claude Code Notes

Project-specific instructions for Claude Code, including:

• How to run tests and linting
• Coverage requirements (100% line + branch)
• Code style rules
• Data file loading constraints

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added comprehensive documentation describing Italian Tax Code structure, Omocodia handling, public API behavior (encode/decode/validation), error hierarchy, and edge-case rules.
  • Expanded development guidance: testing, style, tooling, and contribution conventions.
  • Replaced a prior guidance file with a concise pointer to the main documentation to centralize and simplify maintenance.

[coderabbitai]

Warning

Review limit reached

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

More reviews will be available in 54 minutes and 24 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: c72b3019-b598-4bbc-b21a-2cc5878b26d2

📥 Commits

Reviewing files that changed from the base of the PR and between bf7cf23 and d3216f4.

📒 Files selected for processing (1)

• AGENTS.md

📝 Walkthrough

Walkthrough

Adds AGENTS.md and CLAUDE.md documenting the itax-code Ruby gem: Tax Code format, public API (encode, decode, valid?), error hierarchy, implementation edge cases, development/test commands, and project style/coverage notes.

Changes

Gem Documentation

Layer / File(s)

Summary

API and implementation documentation AGENTS.md, CLAUDE.md

AGENTS.md documents the gem’s Tax Code structure, Omocodia positions and substitution mapping, public API signatures and return/error behavior (including valid? rescue semantics), full error class hierarchy, and implementation edge cases (female day encoding, ambiguous century/year handling, city validity dates, foreign birthplace rules, Omocodia decoding, transliteration, CIN algorithm, name consonant rule), plus development/testing commands, code style, and a maintenance instruction block. CLAUDE.md contains a single pointer to @AGENTS.md.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 I hopped through docs with nimble feet,
Lined up rules and edge cases neat,
Codes, names, and CIN all in a row,
Tests and style so reviewers know,
A tiny guide for the itax-code show.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main change: adding two documentation files (AGENTS.md and CLAUDE.md) to the repository.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/agents-md-corrections

---

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.}

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@AGENTS.md`:
- Around line 11-15: The markdown fenced code blocks containing ASCII
diagrams/trees (for example the blocks starting with the lines "R  S  S  M  R  A
8  0..." and the blocks showing "ItaxCode (public API module)" and
"ItaxCode::Error (< StandardError)") are missing language identifiers and
trigger MD040; update each of those fenced blocks to use ```text instead of
plain ``` so the diagrams are treated as plain text (apply the same change to
the other similar blocks referenced in the comment).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 447fb514-706c-4c99-a845-058e08dfbbc5

📥 Commits

Reviewing files that changed from the base of the PR and between c06a187 and f44bd34.

📒 Files selected for processing (1)

• AGENTS.md