novelly/CLAUDE.md

CLAUDE.md

Guidance for Claude Code (claude.ai/code) in this repo.

Project

Novelly: software for planning and writing a novel. ASP.NET Core 10, C#, TypeScript, React, .NET Aspire. Chapter outlines, character dossiers, prose drafting, an embedded Claude agent, and an MCP server over the same API.

Structure

• src/Novelly.Api/ — the whole back end, organised by feature. One folder per feature holds its entity, DTOs, service and endpoints together: Projects/, Characters/, Chapters/, Beats/, Scenes/, Tags/, Agent/. Common/ holds what genuinely crosses features; Data/ holds the DbContext and EF migrations.
• src/Novelly.AppHost/ — .NET Aspire orchestration; run this to bring up the API and the 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 is what the Husky pre-push hook runs

Best Practices

• Use latest .NET + latest supported nuget packages for that version
• Set langVersion to latest in all csproj files; enable nullable
• Organize code by feature/area, not layer or type. A new capability adds files to one feature folder rather than a row to each of an entity/DTO/service/endpoint folder
• New features need unit tests covering logic as much as possible
• Modified file: check missing test coverage, all tests pass

Architecture

• The React client, the embedded agent, and the MCP server all go through the same REST API. One source of truth — never let a client reach past the API to the database.
• Agent tools and MCP tools call the same application services the endpoints do. New capability = new service method, then surface it in all three.
• Domain has no dependencies. Application depends on Domain. Infrastructure depends on Application. Nothing depends on Api.

Coding

• Descriptive names all classes/methods. No generic: Provider, Manager, Helper
• Match formatting/style from .editorconfig
• Wrap lines at 220 chars, single line if fewer
• Interfaces 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
• PATCH requests are partial: null field = leave alone, empty string = clear. Keep new update endpoints consistent with Patch.Apply.
• Enums cross the wire as names, never ordinals

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 and 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 a chain that stops at the first failure
• Expected exceptions: Assert.That(() => service.Foo(), Throws.TypeOf<NotFoundException>())
• Tests run against real in-memory SQLite via TestDatabase, not the EF InMemory provider — cascade deletes and query translation must be exercised, and the InMemory provider fakes both
• Model calls are faked at the IAgentModelClient seam (see ScriptedModelClient). Never hit the Anthropic API from a test.
• No "Mock" in mocked object names
• No Arrange/Act/Assert comments
• All tests pass before commit

Verifying

Build and tests passing is not the same as working. For anything touching an endpoint, the agent loop, or the MCP server, run it:

• Everything at once: dotnet run --project src/Novelly.AppHost — Aspire starts the API on :5080 and the Vite dev server on :5173, with the dashboard for logs and traces
• API alone: ASPNETCORE_URLS=http://localhost:5080 dotnet run --project src/Novelly.Api, then exercise the route with curl
• Web alone: cd src/Novelly.Web && npm run dev — proxies /api to :5080
• MCP: build it, then drive it over stdio JSON-RPC (initialize → notifications/initialized → tools/list → tools/call)

Several real bugs here — SQLite refusing to ORDER BY a DateTimeOffset, the agent's model client throwing at construction and taking read-only endpoints down with it — passed the build and the test suite and only showed up when the 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 it.
• API key comes from ANTHROPIC_API_KEY or Agent:ApiKey — never commit one. The app must stay fully usable without a key; only the agent endpoints require it.
• EF migrations: dotnet ef migrations add <Name> -p src/Novelly.Api -o Data/Migrations. The API migrates on boot.
• git push runs scripts/ci/prepush.sh through Husky: build, test, then a web build. Run npm install once at the repo root to install the hook.