refactor: Rewrite CLAUDE.md as concise notes instead of documentation - #83
Conversation
gabrypavanello
commented
Jan 10, 2026
gabrypavanello
commented
- Reduced from ~200 lines to ~70 lines
- Put mandatory pre-task commands at the top
- Added "why" context for rules (e.g., strict TS because of production bugs)
- Added Learnings section for ongoing discoveries
- Point to files instead of copying code examples
- Focus on what makes this codebase different (Zod 4, Express 5)
- Removed generic patterns Claude already knows
- Reduced from ~200 lines to ~70 lines - Put mandatory pre-task commands at the top - Added "why" context for rules (e.g., strict TS because of production bugs) - Added Learnings section for ongoing discoveries - Point to files instead of copying code examples - Focus on what makes this codebase different (Zod 4, Express 5) - Removed generic patterns Claude already knows
📝 WalkthroughSummary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings. WalkthroughCLAUDE.md was rewritten from a comprehensive development guide into a concise, task-focused document: long architectural sections and many examples were removed and replaced with Quick Commands, a "Before Finishing Any Task" checklist, brief patterns, minimal packaging notes, and high-level external references. (45 words) Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
PR Review: CLAUDE.md RefactorOverall Assessment✅ Approved with Minor Suggestions This is an excellent refactor that significantly improves the developer experience. The transformation from comprehensive documentation to concise, actionable notes is well-executed and aligns with the stated goal of reducing cognitive load. Strengths
Code Quality & Best PracticesScore: 9/10
Potential Issues & Suggestions1. Missing Pattern Examples Reference (Minor)The old version had specific code examples for $ find packages/core/src -name "tools" -type d
# No resultsRecommendation:
2. External Docs Section Could Be More Specific (Minor)Lines 55-58 provide links but no context on when to use them. Suggestion: ## External Docs
- MCP Spec: https://modelcontextprotocol.io/specification/2025-11-25 (protocol details, tool schemas)
- OpenAI Apps SDK: https://developers.openai.com/apps-sdk (ChatGPT integration patterns)3. Consider Adding More "Common Mistakes" (Optional)The current three are good, but based on the diff, these were valuable from the old version:
Suggestion: Consider adding 2-3 more common pitfalls discovered during development. Performance ConsiderationsN/A - This is a documentation file with no runtime impact. Security ConcernsNone - No code changes, no security implications. Test CoverageN/A - Documentation doesn't require tests, but the PR correctly maintains the requirement in the file itself (line 26: "80% test coverage - CI fails below this"). Markdown Formatting CheckMinor consistency suggestion: Line 42-51: The project map uses a code block without language specifier. Consider adding ## Project Map
- `packages/core` → Server framework (createApp, adapters, middleware)
- `packages/ui` → Client SDK (vanilla JS, protocol detection)
- `packages/ui-react` → React hooks (useAppsClient, useToolResult, useHostContext...)
- `packages/testing` → Test utilities (mocks, matchers for vitest/jest)
- `packages/create-app` → CLI scaffolder
- `examples/` → Working examples to test againstThis renders better in most markdown viewers and is more scannable. Verification Checklist
Final RecommendationMerge after addressing the file path reference (line 30). This is a significant improvement that will make the codebase more approachable while maintaining necessary technical rigor. The philosophy shift from "comprehensive documentation" to "concise, context-rich notes" is exactly right for an AI-assisted development guide. Commit QualityCommits are well-structured:
Both follow conventional commits and have clear, descriptive messages. Great work! 🎉 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In @CLAUDE.md:
- Around line 57-58: The two bare URLs currently listed ("MCP Spec:
https://modelcontextprotocol.io/specification/2025-11-25" and "OpenAI Apps SDK:
https://developers.openai.com/apps-sdk") should be converted to Markdown link
syntax; replace them with "MCP Spec:
[https://modelcontextprotocol.io/specification/2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25)"
and "OpenAI Apps SDK:
[https://developers.openai.com/apps-sdk](https://developers.openai.com/apps-sdk)"
so they render and parse consistently.
- Around line 44-51: Add the language identifier "text" to the Project Map
fenced code block so Markdown renderers and linters get proper syntax
highlighting; locate the fenced block containing the package list (the
triple-backtick block shown around "packages/core … examples/") and change the
opening fence from ``` to ```text while leaving the content and closing fence
unchanged.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
CLAUDE.md
🧰 Additional context used
🧠 Learnings (3)
📚 Learning: 2026-01-09T14:18:43.516Z
Learnt from: CR
Repo: AndurilCode/mcp-apps-kit PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-09T14:18:43.516Z
Learning: Applies to packages/**/*.ts : Use `AppError` and `ErrorCode` from `mcp-apps-kit/core` for error handling
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-09T14:18:43.516Z
Learnt from: CR
Repo: AndurilCode/mcp-apps-kit PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-09T14:18:43.516Z
Learning: Applies to packages/core/**/*.ts : Always use `defineTool` and `defineUI` for type inference when creating tools and UI widgets
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-09T14:18:43.516Z
Learnt from: CR
Repo: AndurilCode/mcp-apps-kit PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-09T14:18:43.516Z
Learning: Keep packages independent and avoid circular dependencies within the monorepo
Applied to files:
CLAUDE.md
🪛 markdownlint-cli2 (0.18.1)
CLAUDE.md
44-44: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
57-57: Bare URL used
(MD034, no-bare-urls)
58-58: Bare URL used
(MD034, no-bare-urls)
⏰ 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: test-and-lint
- GitHub Check: claude-review
🔇 Additional comments (1)
CLAUDE.md (1)
1-69: Excellent refactoring alignment with PR objectives.The rewrite effectively transforms CLAUDE.md from verbose documentation to concise, actionable notes. The structure is task-oriented with clear command placement, rationale for rules (Zod 4, Express 5, strict TS), and file-reference approach rather than code duplication. The retrieved learnings on
defineTool,defineUI, and circular dependencies align well with the Patterns and Common Mistakes sections. The Learnings section template appropriately supports incremental discovery capture.
- Fix path reference: packages/core/src/tools/ → examples/minimal/src/index.ts - Add language identifier to project map code block (```text) - Convert bare URLs to markdown links with context
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @CLAUDE.md:
- Around line 28-34: Add a new pattern to the Patterns to Follow section
recommending the use of AppError and ErrorCode from mcp-apps-kit/core for
consistent error handling; update the CLAUDE.md section that lists patterns
(where defineTool, defineUI, middleware, and exports are described) to include a
short sentence stating "Use AppError and ErrorCode from mcp-apps-kit/core" and a
brief justification about consistent error handling and easier debugging so
contributors follow the established error-handling conventions.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
CLAUDE.md
🧰 Additional context used
🧠 Learnings (3)
📚 Learning: 2026-01-09T14:18:43.516Z
Learnt from: CR
Repo: AndurilCode/mcp-apps-kit PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-09T14:18:43.516Z
Learning: Applies to packages/**/*.ts : Use `AppError` and `ErrorCode` from `mcp-apps-kit/core` for error handling
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-09T14:18:43.516Z
Learnt from: CR
Repo: AndurilCode/mcp-apps-kit PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-09T14:18:43.516Z
Learning: Applies to packages/core/**/*.ts : Always use `defineTool` and `defineUI` for type inference when creating tools and UI widgets
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-09T14:18:43.516Z
Learnt from: CR
Repo: AndurilCode/mcp-apps-kit PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-09T14:18:43.516Z
Learning: Keep packages independent and avoid circular dependencies within the monorepo
Applied to files:
CLAUDE.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: test-and-lint
- GitHub Check: claude-review
🔇 Additional comments (4)
CLAUDE.md (4)
5-11: Strong enforcement of quality gates.The "Before Finishing Any Task" section with non-negotiable checks is excellent. The tone ("No exceptions. Broken builds block the whole team.") sets clear team expectations and prevents CI failures from slipping through.
21-26: Excellent "why" context for codebase-specific constraints.The explanations for Zod 4, Express 5, strict TS, and test coverage requirements provide crucial context about why these rules exist. The production-bug reference for implicit
anyis particularly effective for justifying the stricter TypeScript enforcement.
42-53: Well-balanced project map.The ASCII diagram is scannable and the per-package descriptions are concise. Directing developers to package READMEs for detailed APIs is the right call to avoid duplication and keep this file focused and maintainable.
62-68: Learnings section template is helpful.The empty section with examples shows how to format ongoing discoveries. However, confirm with your team that this section will be regularly maintained—otherwise it becomes stale noise. Consider adding a guideline about review frequency or archival.
| ## Patterns to Follow | ||
|
|
||
| // Custom Express middleware | ||
| expressApp.use("/mcp", app.handler()); | ||
| Use `defineTool` and `defineUI` - they provide type inference. See `examples/minimal/src/index.ts` for usage. | ||
|
|
||
| // Stdio for CLI tools | ||
| await app.getServer().connect(new StdioTransport()); | ||
| Middleware is Koa-style: always `await next()` or the chain breaks. | ||
|
|
||
| // Serverless | ||
| export default { | ||
| async fetch(request) { | ||
| return app.handleRequest(request); | ||
| }, | ||
| }; | ||
| ``` | ||
| Exports only through `index.ts` - keeps the public API clean and refactoring safe. |
There was a problem hiding this comment.
Missing critical error handling pattern.
The Patterns section references defineTool, defineUI, middleware, and exports, but omits guidance on error handling. Per your established learnings, developers should use AppError and ErrorCode from mcp-apps-kit/core for consistent error handling across packages. This is especially important since the codebase maintains strict patterns for reliability.
Consider adding:
Use `AppError` and `ErrorCode` from `mcp-apps-kit/core` - ensures consistent error handling and makes debugging easier across packages.🤖 Prompt for AI Agents
In @CLAUDE.md around lines 28 - 34, Add a new pattern to the Patterns to Follow
section recommending the use of AppError and ErrorCode from mcp-apps-kit/core
for consistent error handling; update the CLAUDE.md section that lists patterns
(where defineTool, defineUI, middleware, and exports are described) to include a
short sentence stating "Use AppError and ErrorCode from mcp-apps-kit/core" and a
brief justification about consistent error handling and easier debugging so
contributors follow the established error-handling conventions.
PR Review: Refactor CLAUDE.md as Concise NotesOverall AssessmentExcellent refactoring - This is a significant improvement that transforms CLAUDE.md from verbose documentation into actionable guidance. The reduction from ~200 to ~70 lines while retaining essential information is impressive. Strengths
Issues Found1. Minor Inaccuracy in Example ReferenceLocation: Line 30 Issue: The minimal example actually uses Recommendation: Either update to: 2. Missing Package in Project MapLocation: Lines 44-50 Issue: The codebase has a Recommendation: Add What This PR Gets Right
RecommendationApprove with minor fixes - Address the The philosophy shift from "comprehensive guide" to "essential context" is exactly right for AI-assisted development. Files Changed: 1 | Net Change: -128 lines |
- Clarify defineUI vs defineReactUI in patterns section - Add missing ui-react-builder package to project map
Pull Request Review: Refactor CLAUDE.mdSummaryThis PR successfully refactors CLAUDE.md from a comprehensive 200-line documentation file to a concise 70-line reference guide. The changes align well with the goal of making it more useful as a quick reference for Claude Code users. ✅ Strengths
🔍 Minor Issues & Suggestions1. Node.js Version DiscrepancyThe CLAUDE.md doesn't mention Node.js requirements, but:
Suggestion: Add a note about Node.js requirements, or clarify which is correct: ## Requirements
- Node.js >= 20.0.0
- pnpm 10.19.02. Pattern Reference Could Be More SpecificCurrent text:
The example file ( Use `defineTool` with `defineUI` for vanilla JS UIs or `defineReactUI` for React components - they provide type inference. See `examples/minimal/src/index.ts` for React usage.3. Missing Example ReferenceThe new CLAUDE.md removes the reference to the full-featured kanban example that was in the original. Consider adding it back to "Examples" section or External Docs if it's valuable for learning. 4. Common Mistakes SectionThe third item mentions:
This is somewhat redundant with the prominent "Before Finishing Any Task" section at the top. Consider consolidating or removing. 🎯 Code Quality AssessmentSince this PR only modifies documentation:
📊 Overall AssessmentRecommendation: ✅ APPROVE with minor suggestions This is a well-executed refactor that makes CLAUDE.md significantly more useful as a quick reference. The reduction in length improves scannability without sacrificing essential information. The additions ("why" context, Learnings section) add real value. The minor issues noted above are truly minor and don't block merging. They can be addressed in a follow-up if desired. 📝 Checklist for MaintainerBefore merging:
Great work on making this more maintainable and useful! 🎉 |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
CLAUDE.md (1)
28-34: Consider adding error handling pattern (AppError/ErrorCode) to Patterns section.The Patterns section covers tool/UI definition and middleware, but the learnings indicate a critical pattern exists: using
AppErrorandErrorCodefrommcp-apps-kit/corefor error handling. Given that error handling is a foundational concern, this pattern may warrant inclusion, even if briefly.For example:
Error handling uses `AppError` and `ErrorCode` from core - see `packages/core/README` for details.This is optional given the document's intentional conciseness, but consider whether the omission creates a gap for new contributors.
Based on learnings,
AppErrorandErrorCodeare documented patterns for the codebase.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
CLAUDE.md
🧰 Additional context used
🧠 Learnings (3)
📚 Learning: 2026-01-09T14:18:43.516Z
Learnt from: CR
Repo: AndurilCode/mcp-apps-kit PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-09T14:18:43.516Z
Learning: Applies to packages/**/*.ts : Use `AppError` and `ErrorCode` from `mcp-apps-kit/core` for error handling
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-09T14:18:43.516Z
Learnt from: CR
Repo: AndurilCode/mcp-apps-kit PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-09T14:18:43.516Z
Learning: Applies to packages/core/**/*.ts : Always use `defineTool` and `defineUI` for type inference when creating tools and UI widgets
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-09T14:18:43.516Z
Learnt from: CR
Repo: AndurilCode/mcp-apps-kit PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-09T14:18:43.516Z
Learning: Keep packages independent and avoid circular dependencies within the monorepo
Applied to files:
CLAUDE.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: test-and-lint
- GitHub Check: claude-review
🔇 Additional comments (8)
CLAUDE.md (8)
42-54: ✓ Project Map is accurate and complete.The Project Map correctly lists all packages and includes
ui-react-builderas noted in the PR. The decision to defer detailed API docs to individual package READMEs is sound and reduces duplication. No changes needed here.
36-40: ✓ Common Mistakes section is well-targeted and actionable.The three mistakes listed are practical, common in monorepo/TypeScript projects, and tie back to guidance earlier in the document. No changes needed.
63-70: ✓ Learnings section structure is clear and well-exemplified.The commented examples are practical (rebuild order, typed mocks) and the format is clear enough for future contributors. This addition addresses the PR goal of creating space for ongoing discoveries. Approved.
1-70: ✓ Overall structure successfully achieves PR objectives.The refactor successfully condenses a comprehensive guide into an action-oriented, task-focused document. It prioritizes critical checks, emphasizes "why" for key decisions, and creates space for ongoing learnings. The tone is appropriately professional for experienced developers without unnecessary verbosity.
The document structure (Before Finishing → Quick Commands → What Makes This Different → Patterns → Mistakes → Map → External → Learnings) flows logically and supports rapid onboarding.
Recommendation: Resolve the outstanding verification items (command existence, version confirmations, coverage config, external link validity) before merging. Once those are confirmed, this is ready.
8-8: No action required—documented commands are validated.The "Before Finishing Any Task" command chain and referenced pnpm scripts (build, test, lint, typecheck) are confirmed to exist and accurately reflect the project's verification workflow.
23-25: Versions confirmed: Zod 4.2.1 and Express 5.2.1 are pinned in pnpm-lock.yaml as stated. The documentation is accurate and sufficient for developers working on this codebase.
26-26: No changes needed — 80% test coverage is correctly enforced in CI.The vitest.config.ts file defines coverage thresholds at 80% for lines, functions, branches, and statements. The
pr-check.ymlworkflow runspnpm teston every PR, which triggers vitest's coverage validation and fails if thresholds are not met.
58-59: No action needed. Both links are valid and current.The MCP Spec URL with the date suffix (2025-11-25) is the correct, official protocol revision reference and is appropriately formatted. The OpenAI Apps SDK link is also current and accessible. Both are suitable for inclusion in the documentation.
3 participants
