docs: add CLAUDE.md with architecture and workflow guidance - #54
Conversation
Documents the engine/UI layering, Zustand slice composition, auth/DB setup (Postgres via Neon, not SQLite as older docs claim), Astryx design-system conventions, testing layout, and the repo's agent-loop guardrails so future Claude Code sessions can orient quickly. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012Jpq3N94psa27k8xASDy8B
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Warning Review limit reached
Next review available in: 52 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. 📝 WalkthroughWalkthroughAdded ChangesRepository Guidance
Estimated code review effort: 1 (Trivial) | ~2 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CLAUDE.md`:
- Around line 44-50: Update both Markdown code fences in the architecture
diagram within CLAUDE.md to include an appropriate language identifier, such as
text, immediately after each opening fence. Leave the diagram contents
unchanged.
- Line 109: Update the protected-file list in CLAUDE.md to explicitly include
src/lib/auth.ts alongside the existing approval-required paths, preserving the
rule that this file cannot be edited without explicit human approval.
- Around line 81-85: Update the Auth documentation near the “Every /api/* route”
statement to limit mandatory auth() and userId checks to protected API routes.
Explicitly identify registration and login endpoints as public exceptions that
must work without an existing session, while preserving the requirement for
session validation on all other protected routes.
- Around line 52-58: Update the architecture documentation to distinguish
framework-free modules from Zustand-dependent core/slices: limit the
zero-dependency and copy-without-changes portability claims to core/engine,
core/types.ts, and core/simulation.ts, while explicitly identifying core/slices
as Zustand-dependent. Keep the existing slice descriptions and module
organization unless needed to make these boundary statements consistent.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
- Add language identifiers to fenced diagrams (markdownlint MD040) - Scope the zero-dependency/portability claims to core/engine, core/types.ts, and core/simulation.ts; core/slices and store.ts depend on Zustand by design - Note /api/auth/register and /api/auth/[...nextauth] as the public exceptions to the "every /api/* route checks session" rule - Add src/lib/auth.ts explicitly to the protected-file list, since there's no auth/ directory for the existing wording to match Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012Jpq3N94psa27k8xASDy8B
There was a problem hiding this comment.
🟡 Not ready to approve
The new doc contains a few concrete inaccuracies/ambiguities (nonexistent test path, coverage-scope wording, and core “no Zustand” claim) that should be corrected to avoid misleading contributors.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Pull request overview
Adds a new CLAUDE.md document to capture repository-specific guidance for future Claude Code sessions, focusing on the project’s architecture boundaries (engine vs UI), local/CI workflows, and operational guardrails (auth/DB, testing, Astryx conventions, and agent-loop constraints).
Changes:
- Introduces
CLAUDE.mdwith commands, CI/test pointers, and architecture layering guidance. - Documents the Postgres + Neon Prisma setup and notes the SQLite vs Postgres discrepancy in older docs.
- Summarizes repo layout and “agent loop” constraints intended to prevent risky automated edits.
File summaries
| File | Description |
|---|---|
| CLAUDE.md | New repo guidance doc covering workflows, architecture invariants, DB/auth notes, and guardrails for automated sessions. |
Review details
Suppressed comments (1)
CLAUDE.md:52
- This paragraph claims everything under
src/engine/ad-console/core/has zero Zustand dependencies and says to never import store code undercore/, butcore/slices/is store integration code and currently imports Zustand types. Clarifying the invariant to apply tocore/engine+core/simulation.tswould match the actual structure.
**`core/engine/`, `core/types.ts`, and `core/simulation.ts` have zero React/Next/Zustand dependencies.** They are pure TypeScript: given state in, return new state out, no mutation, no side effects. This is the most important invariant in the codebase — it's what makes those modules portable and unit-testable in isolation. Never import React, Next.js, or store code into them. Note that `core/slices/` (below) is the one exception within `core/` — it depends on Zustand's `StateCreator` type by design, since its job is to wrap the pure engine in store slices.
- Files reviewed: 1/1 changed files
- Comments generated: 4
- Review effort level: Lite
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
|
|
||
| CI (`.github/workflows/ci.yml`) runs, in order: `type-check` → `test` → `build`. Match that locally before pushing. | ||
|
|
||
| Coverage thresholds (vitest.config.ts, engine/core code only): 80% statements/functions/lines, 70% branches. |
| npx vitest run src/engine/ad-console/core/__tests__/target.test.ts | ||
| npx vitest run -t "harvests converting search terms" |
| React components (src/components/AdConsole) — presentation only | ||
| Zustand store (src/engine/ad-console/store.ts) — composed of 8 core slices + 7 feature slices | ||
| Feature engines (src/engine/ad-console/features/<name>/{types,engine,store}.ts) | ||
| Core engine (src/engine/ad-console/core/) — zero framework dependencies, pure functions |
| These come from `AGENTS.md`, `LOOP.md`, and `loop-constraints.md` — they apply to automated/agentic changes here and are good defaults for any change: | ||
|
|
||
| - **Never edit without explicit human approval**: `.env`/`.env.*`, `prisma/schema.prisma` or `prisma/migrations/`, `next.config.ts`, anything under `auth/` or files matching `*_key*`/`*_secret*`. | ||
| - Always run `npm test` before proposing a change as done. |
- Point the single-test example at a file/test name that actually exists (core/__tests__/engine.test.ts, not a nonexistent target.test.ts) - Correct the coverage-threshold description to match vitest.config.ts's actual include/exclude scope, not "engine/core only" - Attribute the *_key*/*_secret* guardrail to gate.yaml (where it's actually enforced) and align wording with loop-constraints.md Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012Jpq3N94psa27k8xASDy8B
Summary
CLAUDE.md(none existed) documenting the engine/UI layering, Zustand slice composition, auth/DB setup, Astryx design-system conventions, testing layout, and this repo's agent-loop guardrails for future Claude Code sessions.prisma/schema.prismaandsrc/lib/prisma.tsuse Postgres via the Neon adapter, while README/AGENTS.md still describe SQLite — CLAUDE.md points at the schema as source of truth.legacy/andcodegraphs/Amazon-ad-console.mddescribe an older single-file HTML prototype and are stale relative to the current Next.js/engine architecture.Test plan
git diffreviewed for accuracy against currentprisma/schema.prisma,tsconfig.json,vitest.config.ts, andpackage.jsonscripts.Generated by Claude Code
Summary by CodeRabbit