collective
Browse / github.com/storytold/artcraft / patch
docs: propose evidence-oriented agent engineering
docs: propose evidence-oriented agent engineering Proposes clearer, ArtCraft-specific agent instructions and removes the `CLAUDE.md` mirrors. Documentation only; no application, dependency or release changes. Maintainers can adopt all of it or only parts. **What changes** - **Root `AGENTS.md`** keeps the existing overview, layout, code style and Markdown rules inline, so they still load every session. It adds a short *Working rules* section: reproduce defects before fixing, keep to the owning boundary's idioms, report which evidence ran, keep tests hermetic, and get authorization for paid, credential or destructive actions. It also adds `art
- Status
- open
- Score
- 0.00
- Adopters
- 0 other operators
- Author
- Niizuki (imported from pull request #2565, open)
- Base
800217ed04d10fc12706c28e6e91ae2a6b286092- Size
- +281 −14 in 17 files
- Review
- pending
- Shared
- 2026-10-28
- Id
99524f8b0ec5f8c8df9562bb
How it went
No other operator has reported using it yet.
Diff
raw · AGENTS.md CLAUDE.md README.md _docs/AGENTS.md _docs/agent-engineering-methodology.md artcraft-native/AGENTS.md crates/AGENTS.md crates/CLAUDE.md crates/api_clients/artcraft/artcraft_api_defs/CLAUDE.md crates/api_clients/artcraft/artcraft_client/AGENTS.md crates/api_clients/artcraft/artcraft_router/src/generate/generate_video/CLAUDE.md crates/desktop/artcraft/src/services/storyteller/commands/AGENTS.md crates/schema/public/enums/CLAUDE.md crates/schema/public/tokens/CLAUDE.md frontend/AGENTS.md frontend/libs/components/pagescene/AGENTS.md frontend/libs/components/pagescene/CLAUDE.md
@@ -1,17 +1,22 @@ # AGENTS.md This file provides guidance for coding agents when working with the Artcraft monorepo.+Claude Code, Codex and other agents read `AGENTS.md` files directly; do not add+`CLAUDE.md` mirrors (see [agent documentation](_docs/AGENTS.md)). ## Project Overview Artcraft is a public-facing Tauri desktop app for generating AI images and video.-It uses Rust and TypeScript. Backend services, company tooling, and website builds-live in the separate `artcraft-services` repository.+It uses Rust and TypeScript. `artcraft-native/` is a separate pure Rust/egui+desktop app over the same API client crates. Backend services, company tooling,+and website builds live in the separate `artcraft-services` repository.+[Development setup](_docs/dev_setup.md) owns environment commands. ## Project Structure ``` artcraft/+├── artcraft-native/ # Rust/egui desktop app over shared API clients ├── _database/sql/artcraft_migrations/ # Embedded SQLite task database migrations ├── .sqlx/ # SQLite query metadata for offline builds ├── crates/@@ -66,11 +71,32 @@ Organize for top-to-bottom reading. Important things first, details later. column width: ```markdown- | Model | Configuration | Credits | Speed | Score |- |--------------|---------------|--------------------|---------|- | Meshy 6 | text or image | 104 | 80.0 | +24 |- | Rodin 2.5 | text or image | 13 | 10.0 | +3 |+ | Model | Configuration | Credits | Speed | Score |+ |--------------|---------------|---------|-------|-------|+ | Meshy 6 | text or image | 104 | 80.0 | +24 |+ | Rodin 2.5 | text or image | 13 | 10.0 | +3 | ``` Not: `| Model | Configuration | Credits | Speed | Score |` packed tight with varying widths per row.++## Working Rules++- Reproduce a found defect with a test before fixing it and confirm the failure's cause.+ If automation cannot reach it, record the limitation and the nearest executable check.+ Never weaken a valid test to make a suite pass.+- Use the owning boundary's existing types, error idiom and dependency direction. Read a+ dependency's source before wrapping it; avoid unrelated cleanup or new frameworks.+- Run checks that reach the changed boundary and widen them for shared wire types or+ routing. Compilation, fixture tests, live-provider behavior, native startup and visual+ acceptance are different evidence; report which ones ran and which were skipped.+- Keep ordinary tests local and hermetic. Paid generation, uploads, real credentials,+ account changes, releases and destructive operations need explicit authorization.+- Nested `AGENTS.md` files own their context. For a change that crosses boundaries, read+ the `AGENTS.md` of each affected directory before editing.++Contexts: [Rust](crates/AGENTS.md), [frontend](frontend/AGENTS.md),+[pagescene](frontend/libs/components/pagescene/AGENTS.md),+[native app](artcraft-native/AGENTS.md), [agent documentation](_docs/AGENTS.md).+The [engineering methodology](_docs/agent-engineering-methodology.md) explains these+rules and describes optional review and concurrent-agent workflows.deleted file mode 120000@@ -1 +0,0 @@-AGENTS.md\ No newline at end of file@@ -136,6 +136,7 @@ Additional provider integrations are planned for Kling, Google, Runway, and Luma ## Documentation +- [Agent instructions](./AGENTS.md) and [engineering methodology](./_docs/agent-engineering-methodology.md) - [Development setup](./_docs/dev_setup.md) - [Developer documentation](./_docs) - [Desktop build and development scripts](./script/artcraft)new file mode 100644@@ -0,0 +1,16 @@+# Agent and development documentation++The root `AGENTS.md` holds operative rules and style; nested `AGENTS.md` files hold the+rules of the code they sit next to; `agent-engineering-methodology.md` explains them and+describes optional workflows. Keep concise rules an agent must follow in `AGENTS.md` files+and explanation in the methodology.++When editing agent guidance, map each rule to the failure it prevents and its actual+test or manual check. Do not imply that documentation enforces permissions or isolation.+Check moved links and retain existing conventions unless a deliberate change replaces them.++Name instruction files `AGENTS.md` only. Do not add `CLAUDE.md` copies or symlinks:+Claude Code (v2.1.277+) reads `AGENTS.md` only when no `CLAUDE.md` is on the path, and+Git for Windows checks symlinks out as one-line text files by default, so a mirrored+`CLAUDE.md` replaces the real instructions on those clones. See the+[Claude Code AGENTS.md guide](https://code.claude.com/docs/en/memory#agents-md).new file mode 100644@@ -0,0 +1,183 @@+# Evidence-oriented agent engineering for ArtCraft++Operative instructions are in the root and contextual `AGENTS.md` files. This document+explains their reasoning and describes optional workflows; it does not activate agents,+hooks, CI or merge rights.++## Why this fits this repository++ArtCraft places Rust, endpoint, Tauri-command, schema and 3D-editor rules near the+code they govern. This methodology keeps that structure. It adds explicit ways to+challenge an agent's diagnosis, confidence and scope before a plausible implementation+becomes an accidental product contract.++The architecture has several different evidence boundaries: shared Rust API clients,+the provider router, Tauri IPC and cookie handling, SQLite task persistence, React+state, the Three.js editor and the separate egui app. A result in one does not establish+the same result in another. Backend services are outside this repository.++It does not introduce a universal result type, numbered stages or new approval+machinery. Existing Rust `anyhow` conventions, schema types, module layout, two-space+style, API endpoint/command files and pagescene invariants remain in force.++## Define the claim before its implementation++For a consequential capability, write a small observable contract: input/state/sequence,+success, refusal, side effects and required evidence. Number items when traceability+helps; do not create a document for every trivial edit. Include cancellation and failure+behavior rather than specifying only a happy-path screenshot.++For example, a router draft cost estimate should not trigger media upload or generation.+The existing video instructions already distinguish draft, finalize and send phases.+Tests should observe which operation actually occurred, not merely assert a helper's name.+For pagescene, a mode switch that hides chrome must preserve the mounted engine canvases+and the unsaved scene. The nested invariant is the contract; a new visual arrangement+must not silently redefine it.++Prefer typed identities where the code already distinguishes identity spaces, reuse+the schema tokens, and keep primitives at external seams. Preserve existing error+idioms within a boundary. Avoid mass API/type migrations in an unrelated repair.+Keep dependency direction and state authority explicit; a new convenience abstraction+must not become a second engine, store or provider-routing authority.++## Reproduce defects before fixes++A reported defect is a hypothesis. First write the smallest test that names its trigger,+run it against the unfixed code and read the failure. Only then fix. A passing pre-fix+test means the test did not reach the alleged fault or the diagnosis needs revision.+Do not invent a red result when the environment cannot execute it: label the test an+unrun draft and state the missing runtime, dependency or native surface.++Write assertions alongside new behavior. A load-bearing dependency assumption, a+comment promising behavior under a named scenario and a numbered contract item each+deserve a test that can distinguish the promised outcome from a plausible wrong one.+Choose expectations from the contract, not from the finished implementation's output.+Exercise acceptance and refusal. For recurring omissions, a convention/property guard+can cover the class better than an enumeration of today's examples.++Where a defect cannot be automated, record why and exercise the nearest observable+boundary plus a concrete manual reproduction. Compilation errors need compile evidence;+visual judgments need visual evidence. Never weaken, skip or delete a valid assertion+to make a repair appear successful. An obsolete assertion can change only with an+explicitly justified contract change.++## Make evidence reproducible and bounded++Record the revision, command, platform, fixture/input, result and limitation. Inspect+completed artifacts rather than infer final behavior from in-flight state. Pin rolling+measurements and remeasure after correcting the method. Verify paths, hashes and bytes+where multiple checkouts or encodings can make plausible output misleading.++Use local fixtures and temporary stores for ordinary tests. A loopback login test can+prove native request/cookie behavior under its fixture; it cannot prove a production+provider, another OS or an artist's live account. A frontend build proves compilation,+not native IPC or user acceptance. Source inspection and an unrun test are different+evidence again. Report absent credentials and skipped native surfaces explicitly.++Select checks by reach: changed crate/library first; affected consumers for shared types;+full relevant build boundaries for broad dependency/configuration changes. Read actual+manifests and scripts rather than invent one universal monorepo command. Existing examples:++- Rust crate: `cargo check -p <crate>` / `cargo test -p <crate>`; SQLx paths use+ `SQLX_OFFLINE=true` and retain `.sqlx/` plus SQLite migrations.+- Native login: the existing local `login_bridge_tests` command in the command/client+ instructions and the desktop-session regression guide.+- Pure Rust app: `cargo test -p artcraft_native`, with unit and `egui_kittest` coverage.+- Frontend: owning package/Nx targets, existing specs and relevant desktop-session checks.++Documentation changes check links, preserved conventions and the final diff.++## Optional: review by trying to falsify a claim++The workflows in this section and the next are opt-in; the root rules do not require+them.++Self-review is useful but shares the author's assumptions. For consequential changes,+seek a fresh context over a pinned diff and relevant contracts. Give it one concrete+claim to falsify, not an incentive to manufacture a list of findings. A clean answer+is legitimate when it states its scope and what it did not examine.++First ask cold whether the implementation's claim holds, without the author's+suspicions. Separately, supply the author's reasoning and alternatives and ask whether+that reasoning holds. Combining those briefs anchors both onto the same explanation.+Independent agreement is evidence; one reviewer's finding is a lead to reproduce.++A useful finding includes a trigger, affected boundary and an executed failing+reproducer where possible; otherwise it includes a labelled draft. Verify the mechanism+before fixing. Green does not refute a finding if the test did not reach it. Close+confirmed in-scope defects and review the changed lines again; report out-of-scope or+maintainer-owned decisions instead of silently expanding the change.++For a bounded optional review loop, name the claims and set a round ceiling before+dispatch. Stop on convergence, meaning no remaining substantiated defects in scope,+or report the limit and outstanding work. A capped loop is not convergence. Report+scope, omissions, rounds and cumulative agents when used. This workflow is optional;+it grants no permission to spawn agents or turn an agent report into maintainer approval.++## Optional: concurrent agents and shared work++Pin the revision a reviewer reads. Do not let another agent edit underneath that read:+use separate worktrees/scratch for execution or serialize read and write phases.+Assign one owner when findings touch the same files. A discovery reproducer runs in+the reviewer's isolated tree; the landing author reruns it on the actual branch and+owns the red/green evidence. A reviewer without execution capability supplies a draft.++Preserve unrelated tracked, untracked and ignored files. Do not reset, clean, stage+everything or kill shared processes as a shortcut. Separate ports alone do not isolate+ArtCraft's account data, cookie stores, app paths or Cargo locks. Follow the launcher+documentation and use test-owned temporary resources rather than a developer's profile.+Pass through supplied model, effort and budget limits; do not silently increase fan-out.+Pause dependent work for a real owner decision while completing independent authorized work.++## Scope, dependencies and delivery++User authorization defines scope. Paid provider calls, uploads, credential access,+external messages, releases and destructive operations need their own authorization.+Ordinary local tests use synthetic fixtures. Keep secrets and private customer+material out of source, logs and PR evidence.++Read a dependency's actual contract/source before wrapping it or claiming it cannot do+something. If a workaround is needed, name the dependency behavior, cost and retirement+condition; add a probe when that behavior is load-bearing. Prefer removing the cause+within scope, and separate adjacent architectural changes into their own reviewable work.++When delivering through a PR, describe the complete final change, evidence and+limitations. A green suite does not grant wider scope. Keep lasting rationale in the+repository; a PR description alone may be lost at merge.++## Instruction discovery and maintenance++The root `AGENTS.md` is the universal entrypoint and holds layout and style; nested+instructions own their context; this methodology owns explanations and optional+workflows. Tools differ in when they load nested files: Claude Code loads a+subdirectory's `AGENTS.md` when it reads a file there, while Codex reads the files from+the root down to its working directory at startup. So a session started at the root+should read each affected directory's `AGENTS.md` explicitly before editing.++Instruction files are named `AGENTS.md` only. Claude Code v2.1.277 and later reads them+directly, but only when no `CLAUDE.md` or `CLAUDE.local.md` is on the path. A+`CLAUDE.md` symlink is unnecessary, and harmful on Windows: Git for Windows checks+symlinks out as one-line text files unless `core.symlinks` is enabled, and that one-line+`CLAUDE.md` then hides the real instructions. Contributors who keep a personal+`CLAUDE.local.md` can set Claude Code's "Project instructions" option to+`claude-md-and-agents-md` to load both.++Keep instructions concise and durable. State the failure prevented and the actual+guard or manual check. Do not claim prose enforces permissions or reader/writer isolation.+Report concrete friction with an example rather than praise or copy another project's+rule by default. Do not require a phrase or a paragraph to remain in an entrypoint just+to satisfy a test; guard the behavior or owned contract instead.++Codex discovery reference: [official AGENTS.md guide](https://learn.chatgpt.com/docs/agent-configuration/agents-md).+Claude discovery/reference: [official memory and instruction guide](https://code.claude.com/docs/en/memory).+Tool versions and configuration affect discovery; verify loaded files in the actual+session (in Claude Code, `/memory` lists them).++## Status of each part++| Part | Where | Status |+|------------------------|------------------------------|--------------------------------------------|+| Operative rules | Root and nested `AGENTS.md` | Agents follow them |+| Explanation | This document | Reference only |+| Optional deeper review | This document | Opt-in; no required agent count or cadence |+| Mechanical enforcement | Not implemented | Possible follow-up, such as a link check |new file mode 100644@@ -0,0 +1,16 @@+# Pure Rust native app++Read this app's `README.md` before changing its architecture or known limitations.+This egui host is separate from Tauri; do not import webview/React architecture into+ordinary UI code. The dedicated sign-in webview remains its own credential boundary.++- Backend owns Tokio/API work and returns events to the UI. Keep network/download/decode+ work off the UI thread and reuse shared API client/router crates at their public seams.+- Preserve session ownership and identity headers. Test with temporary synthetic files;+ never use or expose a developer's cookie jar, provider credentials or real library.+- Write defect reproducers in native unit or `egui_kittest` coverage before fixes.+ Async results, cancellation, retries and restart recovery need explicit ownership.+- Run `cargo test -p artcraft_native` for affected behavior. It does not prove real+ generation, credential interoperability, native-window behavior or visual quality.+- Do not claim full parity from a test of one control; name the operation and boundary+ actually exercised. Keep known limitations visible in the owning README.@@ -42,6 +42,11 @@ helpers go in the parent `mod tests` so sub-modules can `use super::*`. ## Building +Write defect reproducers before fixes and confirm the failure's cause. Use local+fixtures and temporary stores; ignored live-provider tests remain explicitly invoked.+When shared wire types or routing change, check affected consumers, not only the+crate that defines them. Report compilation, fixture and live/native evidence separately.+ - Most crates: `cargo check -p {crate_name}` or `cargo test -p {crate_name}` - Crates using SQLx: `SQLX_OFFLINE=true cargo check -p {crate_name}` - The desktop SQLite query cache and migrations must remain in `.sqlx/` and `_database/sql/artcraft_migrations/`deleted file mode 120000@@ -1 +0,0 @@-AGENTS.md\ No newline at end of filedeleted file mode 120000@@ -1 +0,0 @@-AGENTS.md\ No newline at end of file@@ -22,6 +22,10 @@ Rust HTTP endpoint bindings used by the ArtCraft Tauri desktop app. ## Validation +Pin method/path/header/cookie defects with a local HTTP fixture before fixing them.+Do not substitute a live account call for an ordinary regression test. Shared wire+changes also inspect `artcraft_api_defs` and both desktop consumers.+ Run `cargo check --offline -p artcraft_client` for client changes. For native login bindings, also run `SQLX_OFFLINE=true cargo test --offline -p artcraft --lib login_bridge_tests`; these tests use local HTTP fixtures and temporary cookie jars.deleted file mode 120000@@ -1 +0,0 @@-AGENTS.md\ No newline at end of file@@ -1,5 +1,9 @@ # Tauri Commands +Reproduce IPC/authentication defects at the native command/client boundary before+fixing them. Frontend mocks do not prove Rust cookie behavior or Tauri registration.+Use local fixtures and temporary stores; report native startup separately.+ - Put each `#[tauri::command]` function in its own `.rs` file module named after that command, such as `storyteller_create_login_challenge_command.rs`. Do not collect multiple commands in a catch-all `*_commands.rs` file.deleted file mode 120000@@ -1 +0,0 @@-AGENTS.md\ No newline at end of filedeleted file mode 120000@@ -1 +0,0 @@-AGENTS.md\ No newline at end of filenew file mode 100644@@ -0,0 +1,19 @@+# Frontend boundaries++Use the existing Nx/React/Vite/Zustand/Three.js structure and the root style rules.+Inspect the owning package's scripts and test configuration before choosing a command;+do not assume every library exposes the same test target.++- Keep host-specific HTTP, upload, auth and navigation in the owning adapter. Reuse+ existing components and stores rather than creating a parallel state authority.+- For UI defects, reproduce the observable event/state sequence in the owning test+ suite before fixing. Include refusal, cancellation and teardown paths where relevant.+- Pagescene has its own `AGENTS.md`: keep canvases mounted, preserve the+ engine → bus → bridge → store → React flow and route shortcuts through the registry.+- Mechanical interaction checks and native-webview/visual evidence are separate.+ Browser-only success does not prove Tauri IPC, cookies or native filesystem behavior.+- Use synthetic fixtures and local servers by default. Live uploads, provider calls,+ account operations and paid generation are not ordinary test dependencies.++Run affected tests/build targets and broaden for shared libraries. For login, origin,+port or session changes also follow `docs/desktop-session-regression.md` from the root.@@ -1,4 +1,4 @@-# CLAUDE.md — pagescene (3D Scene Editor)+# AGENTS.md — pagescene (3D Scene Editor) Guidance for working in the `pagescene` library — the 3D editor (a.k.a. "pagescene" / "Stage3D"). deleted file mode 120000@@ -1 +0,0 @@-AGENTS.md\ No newline at end of file