[PM-26809] Improve Claude and add Review changes Skill

[fedemkr]

🎟️ Tracking

PM-26809

📔 Objective

Improved CLAUDE.md file and added reviewing-changes Claude SKILL based on Android repo config https://github.com/bitwarden/android/tree/main/.claude.

Also updated Architecture.md and added Testing.md docs to the repo to add further details to them.

⏰ Reminders before review

• Contributor guidelines followed
• All formatters and local linters executed and passed
• Written new unit and / or integration tests where applicable
• Protected functional changes with optionality (feature flags)
• Used internationalization (i18n) for all UI strings
• CI builds passed
• Communicated to DevOps any deployment requirements
• Updated any necessary documentation (Confluence, contributing docs) or informed the documentation team

🦮 Reviewer guidelines

• 👍 (:+1:) or similar for great changes
• 📝 (:memo:) or ℹ️ (:information_source:) for notes or general info
• ❓ (:question:) for questions
• 🤔 (:thinking:) or 💭 (:thought_balloon:) for more open inquiry that's not quite a confirmed issue and could potentially benefit from discussion
• 🎨 (:art:) for suggestions / improvements
• ❌ (:x:) or ⚠️ (:warning:) for more significant problems or concerns needing attention
• 🌱 (:seedling:) or ♻️ (:recycle:) for future improvements or indications of technical debt
• ⛏ (:pick:) for minor or nitpick changes

[KatherineInCode]

🤔 Part of me wonders if this will be sufficient for BWA, or if we need to call BWA out separately, or if we should work at getting some of these files actually migrated to BitwardenKit

[fedemkr]

I will rewrite this to take into account both apps. Even though we could move some things into BitwardenKit there are some objects/services that are particular of each app so we will still need the specific app ServiceContainers; so we should still be documenting them.

[KatherineInCode]

🤔 Should this explicitly call out that we can have multiple test files per class?

[SaintPatrck]

I think we should. Something like...

Suggested change

	- **Testing**: Test file goes in same folder as implementation (e.g., `FooProcessor.swift` + `FooProcessorTests.swift`)
	- **Testing**: Test files go in the same folder as the implementation (e.g., `FooProcessor.swift` + `FooProcessorTests.swift`). Multiple test files can be used for a single class to improve readability.

[fedemkr]

I can add a direct link to the testing docs explanation on contributing docs as in there, it's explained how test files are organized. Also will make it plural.

[github-actions]

Checkmarx One – Scan Summary & Details – e62b83bd-db33-4f44-af8f-fb8e60c858e4

Great job! No new security vulnerabilities introduced in this pull request

[SaintPatrck]

Blank bullet can be removed.

[fedemkr]

Work in progress need to add some things in there; missed to add them before committing. Thanks for catching this!

[SaintPatrck]

Extra newline can be removed.

[SaintPatrck]

🧠 ⛈️ I've found terminology like "should not" to be less effective than using more direct phrases like, "You MUST NOT do x." When possible, providing reasoning is also helpful to express criticality in following instructions.

- You **MUST NOT** install third-party libraries unless explicitly told to.
- New encryption logic **MUST NOT** be added to this repository.
- Before providing any code or making changes, you **MUST** have read and understood the "iOS Client Architecture" and "Code Style" documents listed in the References section.

[SaintPatrck]

Can we elaborate on this?

Suggested change

	- Test files named `<TypeToTest>Tests.swift` in same folder
	Test files must be named `<TypeToTest>Tests.swift` and be located in the same folder as the file being tested.

[SaintPatrck]

This is repeated from the Common patterns section. I'm wondering if there's actually value in it being in both places. 🤔

[SaintPatrck]

⛏️ Can we elaborate more here, too?

Suggested change

	- Test in light mode, dark mode, and large dynamic type
	- Tests must pass in light mode, dark mode, and large dynamic type.

[SaintPatrck]

🤔 It may be helpful to provide instructions on how to run tests.

Suggested change

	### How to Run Tests
	- After making changes, run the tests for the relevant scheme in Xcode to ensure your changes have not broken anything.
	- You can also run tests from the command line using `xcodebuild`.

[SaintPatrck]

I think it would be helpful to add a clear purpose statement so Claude has immediate context and directive. Something like

This document provides the necessary context and rules for you, an expert iOS developer, to contribute to the Bitwarden iOS project.

## Project Context Files

**Read these files first to fully understand the project and contributing guidelines.**

Files prefixed with `@` are references to other files in this `.ai` directory. You MUST read them for context before proceeding.

The bottom "Files prefixed with @...", part is to clarify file notation since it varies throughout the doc. Some places, like L7-L9, are prefixed @ while others use hyperlinks pointing to the file.

[fedemkr]

Agree, I'll add that. I think I can just switch to use @ in all places as it's the preferred way on Claude docs to avoid stating it here.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.31%. Comparing base (d6cd64f) to head (ff96d0b).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2039   +/-   ##
=======================================
  Coverage   85.31%   85.31%           
=======================================
  Files        1691     1691           
  Lines      144372   144372           
=======================================
+ Hits       123168   123169    +1     
+ Misses      21204    21203    -1     

☔ View full report in Codecov by Sentry.
📢 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.

[KatherineInCode]

🤔 Forgive my ignorance, but what's a 6502 kernel do in the context of iOS development?

[fedemkr]

Nothing, that was in the template and I wasn't sure whether to remove it as leaving it makes merging from the template easier when updates are made there that we want to bring here.
However, we could totally remove that part and some others as well on our repo.

[KatherineInCode]

Is merging from that repo something we're going to want to do long-term? 🤔 Or are we going to want to take our configuration off in our own configured direction?

[claude]

Claude finished @fedemkr's task —— View job

---

Comprehensive Code Review

Summary

This PR prepares Claude AI configuration for the Bitwarden iOS repository by:

• Adding structured Claude configuration files (.claude/CLAUDE.md, skill, prompts)
• Significantly expanding Architecture.md with better organized content and test architecture details
• Adding comprehensive Testing.md documentation (1089 lines) covering testing philosophy, strategies, and patterns
• Updating .gitignore to exclude local Claude settings

The changes are primarily documentation and tooling configuration with no direct code impact.

Critical Issues

None found. This is a documentation and tooling PR with no compilation or runtime impact.

Suggested Improvements

1. CLAUDE.md Structure and Clarity

Issue: The file could benefit from improved organization based on reviewer feedback

Recommendations

Per reviewer comments:

• .claude/CLAUDE.md:1 - Consider adding a clear purpose statement at the top explaining this document's role for Claude AI
• The distinction between Password Manager (BitwardenShared) and Authenticator (AuthenticatorShared) apps could be more explicit, especially regarding their separate ServiceContainer instances
• Multiple test files per class pattern should be explicitly called out (reviewer question at line discussing testing)

Suggested addition at top:

# Bitwarden iOS Password Manager & Authenticator Apps Claude Guidelines

This document provides the necessary context and rules for Claude AI to contribute effectively to the Bitwarden iOS project.

2. Review Comments Integration

Issue: Several inline review comments from SaintPatrck and KatherineInCode have not been addressed

Outstanding reviewer suggestions

From review comments:

1. .claude/CLAUDE.md - Blank bullet point needs removal (mentioned by SaintPatrck)
2. .claude/CLAUDE.md - Extra newlines can be cleaned up
3. .claude/CLAUDE.md - Terminology improvements suggested (use "MUST NOT" instead of "should not" for stronger directives)
4. .claude/CLAUDE.md - Test file location/organization could be more detailed
5. .claude/CLAUDE.md - Consider elaborating on running tests (how to run from CLI/Xcode)
6. .claude/QUEUE_SYSTEM_GUIDE.md - Contains 6502 kernel references from template that may not be relevant (questioned by KatherineInCode)

Note: Some of these files may have been removed in the latest commit (9f10bd4) which "Removed template based Claude config".

3. Architecture.md Enhancements

Issue: The expanded test architecture section is excellent but could cross-reference Testing.md more explicitly

Recommendation

Docs/Architecture.md:340-404 - The new "Test Architecture" section is comprehensive. Consider adding a note at the beginning:

## Test Architecture

> **Note**: For detailed testing guidelines, examples, and step-by-step instructions, see [Testing.md](Testing.md). This section provides architectural context for how testing aligns with the layered architecture.

This prevents duplication while making the relationship between docs clear.

4. Testing.md Completeness Check

Issue: The 1089-line Testing.md is very comprehensive. Verify all examples compile and reference real paths

Validation needed

The file contains extensive code examples. Recommend:

1. Verify all import statements match actual module names
2. Confirm all file path references in examples exist
3. Check that mock class names align with actual generated mocks (e.g., MockExampleRepository)
4. Ensure test patterns match current XCTest/Swift Testing framework usage in the codebase

This validation ensures Claude AI receives accurate guidance.

5. Skills Configuration Completeness

Issue: .claude/skills/reviewing-changes/SKILL.md references CLAUDE.md but relationship could be clearer

Enhancement

.claude/skills/reviewing-changes/SKILL.md:18 - The skill correctly references checking against CLAUDE.md standards. Consider adding a note about the relationship:

### Step 2: Verify Compliance

Systematically check each area against Bitwarden standards documented in `CLAUDE.md` and its referenced files:

This makes it explicit that CLAUDE.md is the source of truth.

6. Reviewer Questions Not Resolved

Issue: KatherineInCode asked important questions that need resolution

Questions needing answers

1. BWA vs Password Manager: "Part of me wonders if this will be sufficient for BWA, or if we need to call BWA out separately" - The docs now mention both apps but could be more explicit about differences
2. Template merging: "Is merging from that repo something we're going to want to do long-term?" - This relates to whether template-specific content should be removed

These architectural decisions should be resolved before merge.

Good Practices Observed

• Co-located test documentation with architecture docs
• Clear separation of concerns (CLAUDE.md for directives, Architecture.md for patterns, Testing.md for details)
• Proper .gitignore addition for local settings
• Strong emphasis on security requirements
• Comprehensive testing strategies with visual examples
• File references using standard file:line format
• Updated to reference correct repo URLs (sdk-internal)

Action Items for Author

1. Address outstanding review comments from SaintPatrck and KatherineInCode (see section 2 above)
2. Clarify BWA/Password Manager distinction in CLAUDE.md if needed
3. Validate Testing.md examples - ensure all code snippets compile and paths exist
4. Add purpose statement to top of CLAUDE.md as suggested
5. Cross-reference Testing.md explicitly in Architecture.md test section
6. Resolve template questions - confirm QUEUE_SYSTEM_GUIDE.md and other template files were intentionally removed or should be cleaned up
7. Verify consistency between Architecture.md test section and Testing.md content

Review Notes

• No compilation impact: All changes are documentation/configuration
• No security concerns: Changes are tooling-only
• Architecture compliance: N/A (this defines the architecture for Claude)
• Test coverage: N/A (documentation only)

This PR significantly improves Claude AI's ability to contribute to the codebase by providing comprehensive context and guidelines. The documentation quality is high, with minor improvements needed based on reviewer feedback.

---

[github-actions]

Warning

@fedemkr Uploading code coverage report failed. Please check the "Upload to codecov.io" step of Process Test Reports job for more details.

[github-actions]

Warning

@fedemkr Uploading code coverage report failed. Please check the "Upload to codecov.io" step of Process Test Reports job for more details.