James Wampler
4313c8f206
Renames the domain concept from Project to Novel throughout the backend (entities, DTOs, services, endpoints, ProjectAccessService/Permission, ProjectId foreign keys), MCP server (tool names and routes), and the React/Vite frontend (types, hooks, routes, components). Adds a new EF Core migration (RenameProjectToNovel) using RenameTable/RenameColumn to preserve existing data instead of dropping/recreating tables. Updates CLAUDE.md's structure section to reference Novels/ instead of Projects/.
108 lines
6.4 KiB
Markdown
108 lines
6.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
Guidance for Claude Code (claude.ai/code) in repo.
|
|
|
|
## Project
|
|
|
|
Novelly: software plan + write novel. ASP.NET Core 10, C#, TypeScript, React, .NET Aspire. Chapter outlines, character dossiers, prose drafting, embedded Claude agent, MCP server over same API.
|
|
|
|
## Structure
|
|
|
|
- `src/Novelly.Api/` — whole back end, organised by feature. One folder per feature holds
|
|
entity, DTOs, service, endpoints together: `Novels/`, `Characters/`, `Chapters/`, `Beats/`,
|
|
`Scenes/`, `Tags/`, `Agent/`. `Common/` holds what crosses features; `Data/` holds
|
|
`DbContext` + EF migrations.
|
|
- `src/Novelly.AppHost/` — .NET Aspire orchestration; run this to bring up API + web client
|
|
- `src/Novelly.ServiceDefaults/` — shared Aspire wiring: OpenTelemetry, health checks, service discovery
|
|
- `src/Novelly.Mcp/` — MCP stdio server
|
|
- `src/Novelly.Web/` — React + Vite client
|
|
- `tests/` — test suite
|
|
- `docs/` — documentation
|
|
- `scripts/ci/` — bash CI steps; `prepush.sh` = what Husky pre-push hook runs
|
|
|
|
## Best Practices
|
|
|
|
- Use latest .NET + latest supported nuget packages for that version
|
|
- Set `langVersion` latest in all csproj files; enable nullable
|
|
- Organize code by feature/area, not layer or type. New capability adds files to one feature folder
|
|
rather than row to each of entity/DTO/service/endpoint folder
|
|
- New features need unit tests covering logic much as possible
|
|
- Modified file: check missing test coverage, all tests pass
|
|
|
|
## Architecture
|
|
|
|
- React client, embedded agent, MCP server all go through same REST API. One source of truth — never let client reach past API to database.
|
|
- Agent tools + MCP tools call same application services endpoints do. New capability = new service method, then surface in all three.
|
|
|
|
## Logging
|
|
|
|
Serilog console via `AddSerilog` (not `UseSerilog` — keeps OTel provider for Aspire dashboard). `app.UseSerilogRequestLogging()` registered before `UseExceptionHandler` (outermost), else it logs raw exception status instead of handled one.
|
|
- Endpoints: Information via `RequestLoggingEndpointFilter` on each `MapGroup`. No per-lambda logging.
|
|
- Service public methods: Information at entry, ids/enums/counts as args.
|
|
- Deeper/private methods: Debug at start + end.
|
|
- Caught exceptions: `LogError(ex, ...)` with identifying values.
|
|
- Expected/recoverable (NotFound, validation, agent tool errors): Warning before throw/return.
|
|
- Structured templates only — `{ChapterId}`, never interpolation.
|
|
- Never log prose (summary/notes/content) or `ANTHROPIC_API_KEY`. Prose = length only.
|
|
|
|
# Coding
|
|
|
|
- No comments — no `///` XML doc, no `//` line comments, no `/* */` blocks, in C#, TS, or CSS. Unclear code → rename for
|
|
clarity or extract a well-named method instead of explaining it.
|
|
- Descriptive names all classes/methods. No generic: Provider, Manager, Helper
|
|
- Match formatting/style from `.editorconfig`
|
|
- Wrap lines at 220 chars, single line if fewer
|
|
- Interface implemented by single class → bottom of class file. Interface w/ multiple implementations → separate file.
|
|
- No tuples for return types. Prefer records or classes for multiple values
|
|
- Use `record` for data objects, `class` for objects with behavior. Avoid mutable state where possible.
|
|
- DTOs are records; entities are classes. DO NOT use Dto in names.
|
|
- `PATCH` requests partial: null field = leave alone, empty string = clear. Keep new update endpoints consistent with `Patch.Apply`.
|
|
- Enums cross wire as names, never ordinals
|
|
- All frontend components should have an id attribute that identifies them uniquely.
|
|
|
|
## Testing
|
|
|
|
- Min 70% code coverage, target 90%. Unit tests focus end-user scenarios first.
|
|
- Don't write tests just for coverage. Call out missing coverage rather than cover stuff not valuable to end user.
|
|
- Code not cleanly unit-testable → mark `[ExcludeFromCodeCoverage]` or exclude namespace from coverage in .runsettings file
|
|
- BDD-style unit tests, end-to-end as possible. e.g. `Deleting_a_scene_leaves_its_beats_alone`
|
|
- NUnit. No FluentAssertions — assert with `Assert.That` + NUnit's constraint model:
|
|
`Assert.That(beat.SceneId, Is.Null)`, `Assert.That(listed, Has.Count.EqualTo(3))`,
|
|
`Assert.That(titles, Is.EqualTo(new[] { "First", "Second" }))`
|
|
- Grouping related asserts in `Assert.Multiple` beats chain that stops at first failure
|
|
- Expected exceptions: `Assert.That(() => service.Foo(), Throws.TypeOf<NotFoundException>())`
|
|
- Tests run against real in-memory SQLite via `TestDatabase`, not EF InMemory provider — cascade deletes + query translation must be exercised, InMemory provider fakes both
|
|
- Model calls faked at `IAgentModelClient` seam (see `ScriptedModelClient`). Never hit Anthropic API from test.
|
|
- No "Mock" in mocked object names
|
|
- No Arrange/Act/Assert comments
|
|
- All tests pass before commit
|
|
|
|
## Verifying
|
|
|
|
Build + tests passing ≠ working. Anything touching endpoint, agent loop, or MCP server — run it:
|
|
|
|
- Everything at once: `dotnet run --project src/Novelly.AppHost` — Aspire starts API on :5080 +
|
|
Vite dev server on :5173, dashboard for logs + traces
|
|
- API alone: `ASPNETCORE_URLS=http://localhost:5080 dotnet run --project src/Novelly.Api`, then exercise route with curl
|
|
- Web alone: `cd src/Novelly.Web && npm run dev` — proxies `/api` to :5080
|
|
- MCP: build it, then drive over stdio JSON-RPC (`initialize` → `notifications/initialized` → `tools/list` → `tools/call`)
|
|
|
|
Several real bugs here — SQLite refusing ORDER BY DateTimeOffset, agent's model client throwing at construction + taking read-only endpoints down with it — passed build + test suite, only showed up when app actually ran.
|
|
|
|
## Claude
|
|
|
|
- Plans = `.md` files in `docs/plans/`. Web → `docs/plans/web/`, API → `docs/plans/api/`
|
|
- Split large plans into discrete chunks — each buildable + committable independently
|
|
- Plan generated from `docs/plans/<name>.md` → save as `docs/plans/<name>_plan.md`
|
|
- Plan implemented from `docs/plans/<name>.md` → save summary as `docs/plans/<name>_output.md`
|
|
|
|
## Stack
|
|
|
|
`.gitignore` set for .NET/Visual Studio (C#, NuGet, MSBuild) plus Node. Update if stack change.
|
|
|
|
- Anthropic model id lives in `appsettings.json` under `Agent:Model`. Don't hardcode.
|
|
- API key comes from `ANTHROPIC_API_KEY` or `Agent:ApiKey` — never commit one. App must stay fully usable without key; only agent endpoints require it.
|
|
- EF migrations: `dotnet ef migrations add <Name> -p src/Novelly.Api -o Data/Migrations`. API migrates on boot.
|
|
- `git push` runs `scripts/ci/prepush.sh` through Husky: build, test, then web build. Run `npm install`
|
|
once at repo root to install hook.
|