chore: Add Claude Code commands (#14438)
* chore: Add Claude Code commands * chore: Improvements based on feedback
This commit is contained in:
Oli Juhl
GitHub
190
thoughts/shared/research/2026-01-05-claude-md-research.md
Normal file
190
thoughts/shared/research/2026-01-05-claude-md-research.md
Normal file
@@ -0,0 +1,190 @@
|
||||
---
|
||||
date: 2026-01-05T07:06:33Z
|
||||
researcher: Claude
|
||||
git_commit: 43305a562cfba914654da056b0a7e03c40849678
|
||||
branch: develop
|
||||
repository: medusa-core
|
||||
topic: "CLAUDE.md File Creation Research"
|
||||
tags: [research, codebase, claude-md, documentation, conventions]
|
||||
status: complete
|
||||
last_updated: 2026-01-05
|
||||
last_updated_by: Claude
|
||||
---
|
||||
|
||||
# Research: CLAUDE.md File Creation for Medusa Core
|
||||
|
||||
**Date**: 2026-01-05T07:06:33Z
|
||||
**Researcher**: Claude
|
||||
**Git Commit**: 43305a562cfba914654da056b0a7e03c40849678
|
||||
**Branch**: develop
|
||||
**Repository**: medusa-core
|
||||
|
||||
## Research Question
|
||||
|
||||
Research the Medusa Core codebase to gather information needed to create a CLAUDE.md file following Claude Code best practices. The file should be concise and focused.
|
||||
|
||||
## Summary
|
||||
|
||||
This research documents the Medusa Core monorepo structure, build system, testing conventions, and code style to enable creation of an effective CLAUDE.md file. Key findings:
|
||||
|
||||
- **Monorepo**: Yarn 3 workspaces with Turbo orchestration
|
||||
- **Stack**: Node.js 20+, TypeScript 5.6.2, Express, MikroORM/PostgreSQL
|
||||
- **30+ modules**: Product, Order, Cart, Payment, Fulfillment, etc.
|
||||
- **Admin**: React 18 dashboard with Vite
|
||||
- **Testing**: Jest for backend, Vitest for frontend
|
||||
|
||||
## Detailed Findings
|
||||
|
||||
### 1. Codebase Structure
|
||||
|
||||
**Monorepo Organization:**
|
||||
```
|
||||
/packages/
|
||||
├── medusa/ # Main Medusa package
|
||||
├── core/ # Core framework packages
|
||||
│ ├── framework/ # Core runtime
|
||||
│ ├── types/ # TypeScript definitions
|
||||
│ ├── utils/ # Utilities
|
||||
│ ├── workflows-sdk/ # Workflow composition
|
||||
│ ├── core-flows/ # Predefined workflows
|
||||
│ └── modules-sdk/ # Module development
|
||||
├── modules/ # 30+ commerce modules
|
||||
│ ├── product/, order/, cart/, payment/...
|
||||
│ └── providers/ # 15+ provider implementations
|
||||
├── admin/ # Dashboard packages
|
||||
│ └── dashboard/ # React admin UI
|
||||
├── cli/ # CLI tools
|
||||
└── design-system/ # UI components
|
||||
/integration-tests/ # Full-stack tests
|
||||
/www/ # Documentation site
|
||||
```
|
||||
|
||||
**Key Directories:**
|
||||
- `packages/core/framework/` - Core runtime, HTTP, database
|
||||
- `packages/medusa/src/api/` - API routes
|
||||
- `packages/modules/` - Commerce feature modules
|
||||
- `packages/admin/dashboard/` - Admin React app
|
||||
|
||||
### 2. Build System & Commands
|
||||
|
||||
**Package Manager**: Yarn 3.2.1 with node-modules linker
|
||||
|
||||
**Essential Commands:**
|
||||
```bash
|
||||
# Install dependencies
|
||||
yarn install
|
||||
|
||||
# Build all packages
|
||||
yarn build
|
||||
|
||||
# Build specific package
|
||||
yarn workspace @medusajs/medusa build
|
||||
|
||||
# Watch mode (in package directory)
|
||||
yarn watch
|
||||
|
||||
# Lint
|
||||
yarn lint
|
||||
|
||||
# Format
|
||||
yarn prettier --write <files>
|
||||
```
|
||||
|
||||
**Testing Commands:**
|
||||
```bash
|
||||
# All unit tests
|
||||
yarn test
|
||||
|
||||
# Package integration tests
|
||||
yarn test:integration:packages
|
||||
|
||||
# HTTP integration tests
|
||||
yarn test:integration:http
|
||||
|
||||
# API integration tests
|
||||
yarn test:integration:api
|
||||
|
||||
# Module integration tests
|
||||
yarn test:integration:modules
|
||||
```
|
||||
|
||||
### 3. Testing Conventions
|
||||
|
||||
**Frameworks:**
|
||||
- Jest 29.7.0 (backend/core)
|
||||
- Vitest 3.0.5 (admin/frontend)
|
||||
|
||||
**Test Locations:**
|
||||
- Unit tests: `__tests__/` directories alongside source
|
||||
- Module integration tests: `packages/*/integration-tests/__tests__/`
|
||||
- HTTP integration tests: `integration-tests/http/__tests__/`
|
||||
|
||||
**Test Runners:**
|
||||
- `medusaIntegrationTestRunner` - HTTP integration tests
|
||||
- `moduleIntegrationTestRunner` - Module integration tests
|
||||
- Both from `@medusajs/test-utils`
|
||||
|
||||
**Patterns:**
|
||||
- File extension: `.spec.ts` or `.test.ts`
|
||||
- Unit test structure: `describe/it` blocks
|
||||
- Integration tests: Use custom test runners with DB setup
|
||||
|
||||
### 4. Code Style Conventions
|
||||
|
||||
**Formatting (Prettier):**
|
||||
- No semicolons
|
||||
- Double quotes
|
||||
- 2 space indentation
|
||||
- ES5 trailing commas
|
||||
- Always use parens in arrow functions
|
||||
|
||||
**TypeScript:**
|
||||
- Target: ES2021
|
||||
- Module: Node16
|
||||
- Strict null checks enabled
|
||||
- Decorators enabled (experimental)
|
||||
|
||||
**Naming Conventions:**
|
||||
- Files: kebab-case (`define-config.ts`)
|
||||
- Types/Interfaces/Classes: PascalCase
|
||||
- Functions/Variables: camelCase
|
||||
- Constants: SCREAMING_SNAKE_CASE
|
||||
- DB fields: snake_case
|
||||
|
||||
**Import Organization:**
|
||||
1. @medusajs/framework imports (grouped by subpath)
|
||||
2. External npm packages
|
||||
3. Node.js built-ins
|
||||
4. Relative local imports
|
||||
|
||||
**Export Patterns:**
|
||||
- Barrel exports via `export * from`
|
||||
- Named re-exports for specific items
|
||||
|
||||
## Code References
|
||||
|
||||
- Root package.json: `package.json`
|
||||
- ESLint config: `.eslintrc.js`
|
||||
- Prettier config: `.prettierrc`
|
||||
- TypeScript base: `_tsconfig.base.json`
|
||||
- Turbo config: `turbo.json`
|
||||
- Contributing guide: `CONTRIBUTING.md`
|
||||
- Jest config: `jest.config.js`
|
||||
- Yarn config: `.yarnrc.yml`
|
||||
|
||||
## Recommended CLAUDE.md Structure
|
||||
|
||||
Based on research, the CLAUDE.md should include:
|
||||
|
||||
1. **Project Overview** - Brief description of Medusa as commerce platform
|
||||
2. **Quick Commands** - Build, test, lint commands
|
||||
3. **Code Style** - Key formatting/naming conventions
|
||||
4. **Architecture Notes** - Module system, workflows, admin
|
||||
5. **Testing** - How to run tests, test patterns
|
||||
6. **Key Directories** - Where to find important code
|
||||
|
||||
Keep each section to 3-5 bullet points maximum for conciseness.
|
||||
|
||||
## Open Questions
|
||||
|
||||
None - sufficient information gathered for CLAUDE.md creation.
|
||||
Reference in New Issue
Block a user