docs: add CLAUDE.md for Claude Code guidance#125
Conversation
🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
There was a problem hiding this comment.
Hello @koki-develop, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
Summary of Changes
Hello! Gemini here, providing a summary of this pull request. This PR introduces a new documentation file, CLAUDE.md, specifically designed to provide guidance for AI code assistants, such as Claude Code, when working within this repository. The file aims to give AI models a quick overview of the project's development commands, architecture, key technologies, structure, data handling, testing approach, deployment process, and commit conventions. This should help AI tools understand the project context better and potentially generate more accurate and relevant code suggestions or changes.
Highlights
- New Documentation File for AI: Adds a new file,
CLAUDE.md, intended to serve as a guide for AI code assistants like Claude Code, detailing project specifics. - Development Workflow Documentation: The new file includes a comprehensive list of
bun runcommands for common development tasks like starting the dev server, building, formatting, linting, testing, and deploying. - Architecture Overview: Provides a summary of the project's architecture, including the tech stack (Bun, React 19, TypeScript, TanStack Query, Mantine, TailwindCSS 4, Firebase Firestore) and project structure.
- Conventions and Specifics: Documents specific project conventions such as using Bun's native test runner with
.spec.tsfiles, environment variable prefixes (BUN_PUBLIC_), and conventional commit message format.
Changelog
- CLAUDE.md
- Added a new file
CLAUDE.md. - Included sections detailing development commands using
bun run. - Provided an overview of the project's architecture, tech stack, and structure.
- Documented specifics about the data layer (Firestore, TanStack Query).
- Explained the testing setup using Bun's native runner.
- Described the Firebase hosting deployment process.
- Outlined the required commit message conventions.
- Added a new file
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
🚀 Deployed to Preview Environment 🚀ℹ️ This preview will expire in 2025-06-14T06:15:37.049999301Z. |
There was a problem hiding this comment.
Code Review
This pull request introduces a CLAUDE.md file, which is an excellent initiative to guide AI-assisted development with Claude Code. The document is comprehensive, covering development commands, a detailed architecture overview, and coding conventions. The information provided appears largely accurate and well-structured based on the repository context. My review focuses on enhancing clarity for the AI to ensure it can follow project conventions as precisely as possible.
Summary of Findings
- Clarity of 'Core business logic' for AI: The description for
src/lib/uses the term 'Core business logic', which could be more specific to better guide AI code generation and placement. (Commented as medium severity) - Clarity of 'co-located presentation components' for AI: The description for
src/pages/mentions 'co-located presentation components'. Specifying the exact co-location pattern (e.g., same file, sub-directory) would provide clearer guidance for the AI. (Commented as medium severity) - Missing newline at end of file: The file
CLAUDE.mdis missing a newline character at the end of the file (after line 52). While minor, it's a common convention for text files. (Not commented due to severity settings, rated as low)
Merge Readiness
This pull request is a valuable addition to the repository. The CLAUDE.md file is well-crafted and will be beneficial for AI-assisted development.
I have identified a couple of areas where the descriptions could be more specific to provide even clearer guidance to an AI like Claude. These are marked as medium severity. Addressing these suggestions would enhance the document's effectiveness in ensuring the AI adheres closely to project structures and conventions.
Therefore, I recommend addressing these points before merging. I am not authorized to approve pull requests, so please ensure further review and approval as per your team's process once the changes are made.
| - **Build:** Custom Bun build script in `tasks/build.ts`, not typical bundlers | ||
|
|
||
| **Project Structure:** | ||
| - `src/lib/` - Core business logic and Firebase integration |
There was a problem hiding this comment.
The term "Core business logic" is a bit general. For an AI like Claude, providing more specific examples of what's expected in src/lib/ could lead to more accurate code placement and generation. Could you elaborate on the types of logic intended for this directory to make it more explicit for the AI?
For example, does it include shared utility functions, data transformation logic, specific domain models, API service wrappers, etc.? Clarifying this will help the AI make better decisions when generating or refactoring code related to business logic.
| - `src/lib/` - Core business logic and Firebase integration | |
| - `src/lib/` - Shared utilities, Firebase integration, data access/transformation functions, and core application-specific logic (e.g., models, services). |
|
|
||
| **Project Structure:** | ||
| - `src/lib/` - Core business logic and Firebase integration | ||
| - `src/pages/` - Route components with co-located presentation components |
There was a problem hiding this comment.
The phrase "co-located presentation components" is a good start, but "co-located" can be interpreted in a few ways (e.g., components defined in the same file as the route component, or in a components subdirectory within that page's folder, etc.).
To ensure Claude consistently follows the intended structure when generating or modifying page components, could you specify the preferred pattern for co-location? This will help maintain a consistent structure across pages.
| - `src/pages/` - Route components with co-located presentation components | |
| - `src/pages/` - Route components (e.g., `MyPage/MyPage.tsx`), with their specific, non-reusable presentational components co-located (e.g., within the same `.tsx` file or in a dedicated `components/` subdirectory like `MyPage/components/`). |
Summary
• Add comprehensive CLAUDE.md file to guide future Claude Code instances
• Include development commands, architecture overview, and coding conventions
• Document Bun-specific tooling and Firebase deployment process
Test plan
🤖 Generated with Claude Code