CLAUDE.md

1# CLAUDE.md
2 
3Claude Code instructions for MedLens+.
4 
5## First run
6 
71. `README.md`, `AGENTS.md`, `docs/01-product/03-GOLDEN_RULES.md`
82. `docs/02-architecture/01-SYSTEM_ARCHITECTURE.md`
93. Pick a **Ready** issue on [Project #2](https://github.com/users/itxSaaad/projects/2)
10 
11## Monorepo
12 
13| Path               | Role                                                   |
14| ------------------ | ------------------------------------------------------ |
15| `apps/web`         | Next.js 16 — see `apps/web/CLAUDE.md`                  |
16| `apps/api`         | FastAPI — see `apps/api/CLAUDE.md`                     |
17| `packages/types`   | Shared TS contracts                                    |
18| `packages/logger`  | Shared logging utilities                               |
19| `turbo.json`       | Turborepo task pipeline (lint, typecheck, test, build) |
20| `packages/schemas` | OpenAPI / JSON schema strategy                         |
21| `packages/parsers` | Extraction guidance                                    |
22| `packages/agents`  | Agent layer standards                                  |
23 
24## Execution
25 
26- Trunk-based: branch from `main`, PR back to `main` (squash merge). No `develop` branch.
27- Naming: [`docs/07-open-source/03-NAMING_CONVENTIONS.md`](docs/07-open-source/03-NAMING_CONVENTIONS.md) — `feat/TKT-NNN-slug`, conventional commits, semantic PR title
28- **Every commit message must pass `commitlint.config.cjs`** (`@commitlint/config-conventional`) or the required `Commit And PR Convention Checks` CI job fails the PR: `<type>(<scope>): <subject>` header, valid `type` (`feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `ci`, `release`, etc.), header ≤100 chars, blank line between header/body/footer. `body-max-line-length` is disabled (commit bodies routinely contain unwrappable URLs, e.g. Dependabot changelog links) — still wrap prose by hand for readability. Run `pnpm exec commitlint --from HEAD~1 --to HEAD` locally before pushing if unsure.
29- Adapter/factory boundaries; env + feature flags
30- PR-only merges; auto-merge disabled
31- Never bypass medical safety guardrails
32 
33## Validation
34 
35```bash
36pnpm lint && pnpm typecheck && pnpm test && pnpm build
37```
38 
39Turborepo orchestrates workspace tasks (`turbo.json`). CI caches `.turbo/` via GitHub Actions.
40 
41## Skills and rules
42 
43- Index: `.claude/skills/medlens/SKILL.md`
44- Discipline: `.claude/rules/agent-discipline.md`
45- Rules map: `docs/00-start/03-RULES_AND_SKILLS_MAP.md`
46 
47## graphify
48 
49This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
50 
51Rules:
52 
53- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
54- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
55- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
56- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).
57