huly-mcp: Instructions file for Claude Code

Project Instructions

Rules are reflexive: when adding a rule, apply it immediately.

Legacy requires evidence

Keep or introduce legacy behavior only for a demonstrated current requirement. Before preserving a compatibility path, name the concrete supported consumer that needs it, verify that need, and test whether an update or ordinary client restart resolves it. Apply especially strict scrutiny to every legacy proposal; hypothetical consumers, stale specifications and "just in case" are insufficient. When no current requirement remains, remove the legacy path and update its specification and tests together.

Design Principle: LLM-First API

The primary consumer of this MCP server is an LLM coding agent, not a human developer. All design decisions — tool naming, parameter shapes, description writing, error messages, defaults — must optimize for LLM comprehension and single-call correctness. Prefer fewer tool calls with clear semantics over multi-step protocols. Auto-resolve identifiers where possible rather than requiring the caller to decompose them. Write tool descriptions as if the reader has no documentation beyond the schema and the description string.

Project Harness (COPY TO NEW PROJECTS)

This project's quality harness is the reference template for new TypeScript/Effect projects. When setting up a new project from this one, ALL of these components must be copied:

1. Test coverage (vitest.config.ts): v8 provider, 99% thresholds, test:coverage script. Requires @vitest/coverage-v8 dev dep.
2. Code duplication (.jscpd.json + jscpd src in lint script): threshold 2%, console reporter.
3. Circular dependency detection (dpdm --exit-code circular:1 in circular, wired into check-all): catches import cycles while ignoring type-only dependencies.
4. Cyclomatic complexity (oxlint.complexity.json, wired into check-all): The lint gate caps classic McCabe complexity at 8 for all production TypeScript, with no suppression baseline.
5. Pre-commit hooks (.husky/pre-commit): lint-staged + gitleaks secrets scanning.
6. check-all (pnpm check-all): build + TypeScript 7 and Effect diagnostics + circular + complexity + lint (Oxlint + jscpd) + test. Preserve this full gate; choose its execution cadence according to Verification below.
7. Effect testing (@effect/vitest): Effect-aware test runner integration.
8. Effect language-service diagnostics (effect-tsgo diagnostics --project tsconfig.json --strict --severity error,warning): run through @effect/tsgo as part of typecheck without patching TypeScript; Effect errors and warnings fail the gate.
9. Oxc lint and formatting (.oxlintrc.json + oxlint-tsgolint + dprint.json with dprint-plugin-oxc): type-aware Oxlint plus Oxc formatting through dprint, without the ESLint runtime. Project-only architectural rules live in scripts/oxlint-project-plugin.mjs.
10. Property test placement: fast-check/property-based tests live in *.property.test.ts files only. Oxlint must reject fast-check imports in ordinary *.test.ts files so generated tests stay discoverable and reviewable as a distinct test class.
11. Strict TypeScript 7 baseline (@typescript/native + tsconfig.json): project typechecking uses TypeScript 7 with strict, exactOptionalPropertyTypes, noUncheckedIndexedAccess, noImplicitOverride, and noFallthroughCasesInSwitch. The typescript-compiler-api alias is TypeScript 5 used only by the README AST generator because the native TypeScript 7 package does not expose the JavaScript compiler API.