---
title: "Gessa Context for Claude Code"
description: "Operational guide for Claude Code / Claude agents building in Gessa at engine v1, the discover, build, prove loop plus the repo-aware gen-docs and contract gates."
engineVersion: v1.0.234
date: 2026-09-28
license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/."
canonical: https://gessa.ai/docs/ai/claude-code/
---

# Gessa Context for Claude Code

Operational guide for Claude Code and Claude agents building in Gessa at **engine
version v1**, whether working directly in this repo or driving the engine through
MCP. It mirrors the [Codex guide](./codex.md) and adds the repo-aware workflows
(generated-docs and contract gates) that apply when you have the source tree.

Read [llms-full.md](./llms-full.md) once for the full model. This page is the
short operational checklist plus the repo gates.

## Operating loop

{% ai-context audience="claude-code" priority="must" %}
Discover read-only, build through canonical surfaces, author behavior
semantically, then capture proof. When you also have the source tree, the repo
gates below are part of "done."
{% /ai-context %}

1. **Discover first (read-only).** Learn the live contract before mutating:
   - `project_get_entity`, `project_get_component_definition`, `project_get_script`
     for a targeted read (`project_get_graph_snapshot` reads the whole graph, not for
     targeted lookup); `world_build_get_operation_catalog` for the intent-level
     world-build operations.
   - `engine_list_component_types` / `engine_get_component_schema`: read fields
     before you set them.
   - `engine_list_script_nodes` / `engine_list_script_patterns`.
   - Full list: the [MCP Tool Reference](../../creator/mcp/tool-reference.md).
2. **Prefer MCP + canonical actions.** Build worlds with
   `world.build.from_prompt` / `world.build.from_spatial_asset`; edit through
   cataloged `project.*` actions: `project.world.create`, `project.entity.create`,
   `project.entity.component.set` (see the
   [Action Catalog](../../spec/generated/action-catalog.md)); generate assets via
   `generation_quote_job` then `generation_create_job`.
3. **Never hand-write full Script IR.** Author behavior with Script Semantic Patch
   (`project_apply_script_semantic_patch`); `project_create_script` yields only an
   empty IR shell. See [Script Semantic Patch](../../spec/generated/script-semantic-patch.md).
4. **Require proof before claiming done.** Use `qa_capture_observer_frame`,
   `qa_capture_renderer_viewport`, `simulation_run`. Playable acceptance needs a
   collision proxy, a nav/query proxy, a semantic anchor, and `playability.accepted`
   receipts (see the [World Build Contract](../../spec/generated/world-build-contract.md)).
   Missing proof is `not_run`, not pass, never synthesize a receipt.

## Repo-aware workflows (when you have the source tree)

- **Generated reference is Tier 2: never hand-edit it.** Files under
  [`docs/spec/generated/`](../../spec/generated/) and
  [`docs/creator/mcp/`](../../creator/mcp/) carry the header `GENERATED FILE: do
  not edit by hand.` To change them, change the Tier-1 source and regenerate with
  `npm run gen-docs`; verify with `npm run gen-docs:check` (which is part of the
  global `npm run check`).
- **Respect the gates.** Documentation is guarded like code. The docs guards run
  via `npm run check:docs`: `check:docs-contract-scaffold` (structure),
  `check:docs-links` (every relative link resolves), `check:docs-markdoc` (every
  prose Markdoc tag is well-formed and resolves to its generated reference),
  `check:docs-examples` (every ts/tsx/js/json example carries a conceptual or
  verbatim marker), and `check:docs-claims` (no page asserts an unaccepted
  capability). Engine contracts are guarded by `npm run check:contract-freeze`
  (with `contracts:bump`), `npm run check:version-coordinates`, and the forbidden
  vocabulary gate `npm run check:no-2d-references`. Run the relevant `check:*`
  gates before relying on a contract claim or considering a change complete.
- **Edit hand-authored prose in place at v1.** Tier-3 pages (this folder and
  [`docs/product/v1/`](../../product/v1/index.md)) link to Tier-2 generated tables
  and must not restate them.
- **Cross-reference, do not duplicate.** When a page needs a canonical table, link
  to the generated file rather than copying it. Copying a generated table creates a
  second, un-versioned source of truth that silently rots.

## Hard rules

- Do not invent component, action, or MCP tool names: if it is not in the
  generated reference or a discovery tool's output, it does not exist at v1. The
  built-in ECS components are enumerated in the generated component reference;
  gameplay concepts are script patterns, not components.
- Do not mutate the raw Project Graph in normal paths;
  `project_apply_transaction` is a low-level escape hatch.
- Do not write raw shader/pass fields; reference cataloged capability ids.
- Do not forward your MCP bearer token to downstream tools or services.
- Do not synthesize proof; report degraded captures as degraded.

See also: [Codex guide](./codex.md),
[MCP tool use](./mcp-tool-use.md),
[Common failures and repairs](./common-failures-and-repairs.md),
[Documentation Contract Architecture](../../docs-system/DOCUMENTATION_CONTRACT_ARCHITECTURE.md).

Status: stable, v1 Claude Code operating guide, pinned to engine v1.