Skip to content

CLAUDE.md

Latest commit

 

History

History
54 lines (37 loc) · 4.16 KB

CLAUDE.md

File metadata and controls

54 lines (37 loc) · 4.16 KB

Claude / AI tooling guide for the Loom repository

This file tells Claude Code, Cursor, and other AI assistants how to work in this repo. It is also mirrored to .cursorrules for Cursor compatibility. Eventually this file will be generated by Loom itself from fragment definitions; until then, edit it directly.

What Loom is

Loom is a methodology hub for AI-augmented software development. The README has the user-facing description. The design overview (docs/design/loom-design.md) is the source of truth for architecture and intent.

Architecture in one paragraph

Modular monolith, Clean / Onion shape. Loom.Domain has zero dependencies and contains entities, value objects, enums. Loom.Application orchestrates and depends only on Loom.Domain. Loom.Infrastructure, Loom.Agents, Loom.Integrations, and Loom.Mcp depend on Loom.Application via interfaces declared in Loom.Application. Loom.Web depends on Loom.Application and wires DI. Loom.Contracts carries DTOs that cross boundaries (notably the MCP server). Test projects mirror src.

Code conventions

  • C# 13 / .NET 10. File-scoped namespaces. Nullable reference types enabled everywhere. Treat warnings as errors.
  • Records over classes for immutable data; classes for entities with behaviour. Use primary constructors where they read well.
  • No service locator. Constructor injection only.
  • No static state outside genuinely-pure helpers. Time, randomness, IDs go through abstractions (ISystemClock, IGuidProvider) so tests stay deterministic.
  • async all the way down. No .Result or .Wait(). CancellationToken on every async public method.
  • Public surface is explicit. Internal types stay internal. Don't widen access for tests — use InternalsVisibleTo.
  • EF Core lives only in Loom.Infrastructure. Domain types must not reference EF. Repository interfaces are declared in Loom.Application; implementations live in Loom.Infrastructure.
  • Migrations are immutable once merged to main. If a schema change is needed, add a new migration; do not edit a shipped one.
  • Tests use xUnit v3 + FluentAssertions. Test names: Method_State_Expected or sentence-style for behavioural tests.
  • Domain tests must run without any I/O — no database, no filesystem, no HTTP.
  • Infrastructure tests that need MSSQL use Testcontainers; do not assume a local SQL Server.

What to do before changing code

  1. Read the relevant section of docs/design/loom-design.md. Architectural changes that contradict it require an ADR.
  2. Skim recent ADRs in docs/adr/.
  3. Look at neighbouring code first — match local conventions before introducing your own.

What to do when adding a new feature inside this repo

  1. Start in the domain. If the concept doesn't fit the existing entity model cleanly, that's a signal worth raising in PR description.
  2. Application service interfaces declare the seams. Infrastructure implements them.
  3. Tests first when changing domain rules; tests alongside when adding pure infrastructure plumbing.
  4. Update the design doc if the change reaches outside a single feature's scope.

Things to avoid

  • Don't introduce new top-level projects without discussion in PR.
  • Don't add a NuGet package without putting the version in Directory.Packages.props.
  • Don't swallow exceptions. Log with structured properties (no $"..." interpolation in log messages — use _logger.LogX("msg with {Param}", value)).
  • Don't put SQL strings in domain or application code. EF Core LINQ in infrastructure, raw SQL only when necessary and with a comment explaining why.
  • Don't generate large speculative scaffolds. Build the smallest thing that compiles and passes tests, then iterate.

When in doubt

Ask in PR description rather than picking silently. Loom is opinionated; AI-generated code that doesn't match the opinion will be rejected.

Self-reference note

Loom's own development is first-team dogfooding: the methodology Loom encodes is the methodology used to build Loom. PR descriptions, ADRs, and commit messages are seed material for the eventual fragment library. Write them as if a future agent will read them — because one will.