Fathom: Instructions file for Codex

AGENTS.md - Fathom

Project Overview

VR/AR hand gesture interaction system for a Chinese ancient architecture surveying game. Built with Vite + React + TypeScript + Three.js + MediaPipe Hands.

Build/Test/Lint Commands

# Development
npm run dev           # Start dev server
npm run build         # Production build
npm run preview       # Preview production build

# Testing (Vitest)
npm run test          # Run all tests
npm run test src/hand/gestures/pinch.test.ts  # Single test
npm run test -- --watch                       # Watch mode

# Linting
npx tsc --noEmit      # Type check
npm run lint          # Run ESLint
npm run lint -- --fix # Fix ESLint issues

Code Style

Imports

// Group: React, Third-party, Internal
import React, { useEffect } from 'react';
import * as THREE from 'three';
import { HandLandmarker } from '@mediapipe/tasks-vision';

import { HandState } from '@/hand/types';

Formatting

• 2-space indentation, single quotes, semicolons required
• Max line length: 100, trailing commas in multi-line

Naming Conventions

// PascalCase: Classes, Interfaces, Enums
class HandStateMachine {}
interface GestureConfig {}
enum ToolType { RULER = 'RULER' }

// camelCase: variables, functions, hooks
const handPosition = new THREE.Vector3();
function detectPinch(): boolean {}

// SCREAMING_SNAKE_CASE: constants
const PINCH_THRESHOLD = 0.05;
const CONFIDENCE_MIN = 0.7;

TypeScript Guidelines

• Prefer interface for object shapes, enum for finite states
• Explicit function return types required
• Avoid any, use unknown for unknown types
• Never use @ts-ignore or @ts-expect-error

Quality Standards (Mandatory)

Comments (Chinese Required)

// 中文注释：解释为什么这样做
// 捏合阈值基于人手自然捏合时的平均距离
const PINCH_THRESHOLD = 0.05;

• Comments must be in Chinese (中文)
• Explain why, not what
• Document complex logic, hacks, contracts

Prohibited

• Giant functions (>50 lines) - split into smaller functions
• Implicit state - use explicit state management
• Magic numbers - use named constants
• Deep nesting (>3 levels) - use early returns
• Pinyin naming, ambiguous abbreviations
• @ts-ignore / @ts-expect-error