docs: add Claude framework enhancements

[david-waltermire]

Summary

Adds enhancements to the Claude Code framework:

• Build verification summary format - Standardized format for reporting build results with specific counts for tests, SpotBugs, PMD, and Checkstyle
• Unit testing rule - Standards for what to test (edge cases, business logic) and what not to test (getters/setters, trivial code)
• Unit test writing skill - Detailed workflow with edge case checklist, coverage expansion process, and test structure patterns

Changes

.claude/rules/development-workflow.md

• Added Build Verification Summary Format section
• Added unit-test-writing to project skills list

.claude/rules/unit-testing.md (new)

• Core principles: what to test, what not to test
• Prioritize edge cases over happy paths
• Mandatory coverage evaluation when touching existing code

.claude/skills/unit-test-writing.md (new)

• Edge case checklist (Empty/Null, Boundaries, Invalid, Missing, etc.)
• Coverage expansion workflow (4 steps)
• Test naming conventions
• Test fixture patterns (focused fixtures, helper methods, nested classes)

Test plan

• Documentation-only changes, no code impact
• Reviewed for consistency with existing framework

Summary by CodeRabbit

• Documentation
  • Added unit testing standards and a mandatory coverage-evaluation workflow to assess and expand test coverage when modifying code.
  • Introduced a new "unit-test-writing" skill with guidance, an edge-case checklist, naming and fixture patterns, and examples.
  • Inserted a Build Verification Summary format (sample, guidelines, failure example) into the development workflow.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

Added three documentation artifacts under .claude: a new unit-test-writing skill, a new unit-testing rules document, and updates to the development workflow that insert the skill reference and a Build Verification Summary Format section.

Changes

Cohort / File(s)	Summary
Unit Testing Rules ​.claude/rules/unit-testing.md	New file describing unit testing standards: what to test/avoid, prioritize edge cases, and a mandatory coverage-evaluation workflow for code changes.
Development Workflow ​.claude/rules/development-workflow.md	Workflow updated to add unit-test-writing to Project Skills and to insert a Build Verification Summary Format section (sample summary, guidelines, and a failure example) in the lifecycle narrative.
Unit Test Writing Skill ​.claude/skills/unit-test-writing.md	New skill doc covering when to apply the skill, an edge-case checklist, coverage expansion workflow, naming conventions, fixture patterns, TDD guidance, and sample test snippets.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Check consistency of unit-test-writing references across the three files.
• Verify the Build Verification Summary Format appears correctly and consistently in both workflow locations.
• Review the coverage-evaluation workflow and sample test snippets for clarity and applicability.

Possibly related PRs

• docs: add Claude framework enhancements #565 — Modifies the same .claude documentation files and adds the unit-test-writing skill and Build Verification Summary Format, indicating direct relation.

Suggested reviewers

• aj-stein

Poem

🐰 I hopped through docs with careful care,
Left checklists, fixtures, and tests to prepare,
Boundaries checked and edge cases bright,
Coverage growing by soft moonlight,
A rabbit cheers for every passing test ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'docs: add Claude framework enhancements' is vague and generic, using broad language that doesn't clearly convey the specific nature of the changes.	Consider a more descriptive title such as 'docs: add unit testing guidelines and build verification format' to clearly reflect the main additions.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8d75d6c and 39fb1da.

📒 Files selected for processing (3)

• .claude/rules/development-workflow.md (2 hunks)
• .claude/rules/unit-testing.md (1 hunks)
• .claude/skills/unit-test-writing.md (1 hunks)

---

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

[david-waltermire]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

.claude/rules/development-workflow.md (1)

127-127: Clarify the placement and scope of the Build Verification Summary Format section.

The section is inserted mid-Phase 5, which creates ambiguity about whether it's a required sub-section of Phase 5 verification or a general format applicable to all build verification contexts. Consider either:

1. Explicitly marking it as a subsection of Phase 5 with a header like "Phase 5.1: Build Verification Summary Format"
2. Moving it to a separate "Build Output Standards" section at workflow level

This will clarify when developers should apply this format.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b5a1dd4 and 580434e.

📒 Files selected for processing (3)

• .claude/rules/development-workflow.md (2 hunks)
• .claude/rules/unit-testing.md (1 hunks)
• .claude/skills/unit-test-writing.md (1 hunks)

🧰 Additional context used

🧠 Learnings (6)

📚 Learning: 2025-12-17T13:27:43.679Z

Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Code changes should use TDD principles: write tests first before implementing code, watch tests fail, write minimal code to pass tests, then refactor. For existing code without tests, add tests when modifying files to ensure behavioral equivalence.

Applied to files:

• .claude/skills/unit-test-writing.md
• .claude/rules/unit-testing.md

📚 Learning: 2025-12-17T13:27:43.679Z

Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/*.java : Follow Test-Driven Development (TDD) principles: write tests first before implementing functionality, verify tests fail with current implementation, implement minimal code to pass tests, then refactor while keeping tests green

Applied to files:

• .claude/skills/unit-test-writing.md
• .claude/rules/unit-testing.md

📚 Learning: 2025-12-17T13:27:43.679Z

Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: All PRs require passing CI checks before merge

Applied to files:

• .claude/rules/development-workflow.md

📚 Learning: 2025-12-17T13:27:43.679Z

Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Use SpotBugs, PMD, Checkstyle, and Jacoco for static analysis. Project enforces Checkstyle code style, PMD source analysis (fails on priority 2+ violations), SpotBugs bug detection (with spotbugs-exclude.xml exclusions), and Jacoco code coverage (target: 60% coverage)

Applied to files:

• .claude/rules/development-workflow.md
• .claude/rules/unit-testing.md

📚 Learning: 2025-12-17T13:27:43.679Z

Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/*.java : All code changes must follow the Javadoc style guide (docs/javadoc-style-guide.md). New code requires 100% Javadoc coverage on public/protected members. Modified code must add/update Javadoc on any members touched. All Javadoc must include param, return, throws tags in the correct order (BLOCKING)

Applied to files:

• .claude/rules/unit-testing.md

📚 Learning: 2025-12-17T13:27:43.679Z

Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: 100% of unit tests must pass before pushing code (BLOCKING)

Applied to files:

• .claude/rules/unit-testing.md

🔇 Additional comments (7)

.claude/rules/development-workflow.md (1)

32-32: Skill entry is well-integrated.

The new unit-test-writing skill entry fits naturally into the Project Skills list and provides a clear, accurate description. The skill is properly referenced from the unit-testing rule and the Phase 3 development workflow.

.claude/rules/unit-testing.md (1)

1-40: Comprehensive and well-aligned unit testing standards.

The document establishes clear, actionable principles that align well with the project's TDD requirements. The "What NOT to test" section effectively eliminates common anti-patterns, while prioritizing edge cases acknowledges the reality that boundary conditions are where bugs hide. The mandatory coverage evaluation workflow integrates cleanly with the development lifecycle.

.claude/skills/unit-test-writing.md (5)

1-12: Skill metadata and usage section are clear and complete.

The YAML frontmatter is properly formatted, and the "When to Use" section accurately captures the three primary scenarios for applying this skill. The description provides sufficient context for developers to understand when to invoke the skill.

---

14-28: Edge Case Checklist is comprehensive and well-organized.

The table effectively categorizes edge case types with concrete examples. The integration with TodoWrite (line 16) creates accountability by converting checklist items into tracked tasks. The nine categories provide thorough coverage of edge case domains, from simple boundary conditions to complex scenarios like concurrency and state.

---

30-60: Practical coverage expansion workflow with good integration of tools.

The four-step process moves logically from assessment to implementation, with each step building on the previous. The shell commands and code examples are concrete and actionable. Integration with TodoWrite at Step 3 ensures tests don't get overlooked. The Jacoco reference in Step 1 (line 41) properly aligns with the project's code coverage requirements.

---

62-94: Test naming conventions are clear with excellent examples.

The naming pattern ([action]When[condition] format) creates self-documenting tests that immediately convey the scenario and expected behavior. The good/bad examples make it easy for developers to understand the distinction. The use of @DisplayName (line 68) provides a secondary layer of clarity beyond method names.

---

96-158: Test fixture patterns, TDD integration, and quick reference are well-structured.

The fixture patterns (focused fixtures, helper methods, nested classes) provide practical strategies for organizing tests at scale. The TDD integration guidance—prioritizing edge cases over happy paths—ensures tests catch bugs early. The quick reference table provides a scannable guide that developers can apply immediately. All Java examples use modern JUnit 5 conventions appropriate for the metaschema-java project.

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 580434e and db7d2e4.

📒 Files selected for processing (1)

• .claude/rules/development-workflow.md (2 hunks)

🧰 Additional context used

🧠 Learnings (3)

📚 Learning: 2025-12-17T13:27:43.679Z

Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Use SpotBugs, PMD, Checkstyle, and Jacoco for static analysis. Project enforces Checkstyle code style, PMD source analysis (fails on priority 2+ violations), SpotBugs bug detection (with spotbugs-exclude.xml exclusions), and Jacoco code coverage (target: 60% coverage)

Applied to files:

• .claude/rules/development-workflow.md

📚 Learning: 2025-12-17T13:27:43.679Z

Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/*.java : All code changes must follow the Javadoc style guide (docs/javadoc-style-guide.md). New code requires 100% Javadoc coverage on public/protected members. Modified code must add/update Javadoc on any members touched. All Javadoc must include param, return, throws tags in the correct order (BLOCKING)

Applied to files:

• .claude/rules/development-workflow.md

📚 Learning: 2025-12-17T13:27:43.679Z

Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: All PRs require passing CI checks before merge

Applied to files:

• .claude/rules/development-workflow.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Code
• GitHub Check: Website

🔇 Additional comments (2)

.claude/rules/development-workflow.md (2)

32-32: Skill reference is clear and well-placed.

The unit-test-writing skill addition integrates naturally into the Available Skills section with a concise, descriptive summary that matches the PR objective.

---

127-155: Build Verification Summary Format correctly incorporates Jacoco coverage (addressing prior feedback).

The format now includes Jacoco coverage metrics with appropriate ✅/⚠️ indicators for passing and below-target scenarios, fulfilling the previous review request.