Skip to main content

Operating Guide

Canonical operating guide for all agents working in this repo.

Source: AGENTS.md

Content​

Agent Operating Guide (Read This First)

This repository is worked on by many different coding agents (Cursor, Claude Code, Codex, Antigravity, etc.). To keep changes consistent and reviewable, all agents must read and follow the repo rules before doing anything else.

Canonical rules (mandatory)​

  1. Read all rules in:
    • .agents/rules/*.mdc
  2. Load supporting references when they apply:
    • .agents/references/coding-standard/ for shared Figma, React effect, and page-structure guidance.
    • .agents/references/coding-standard/vercel-react-best-practices/REPO-GUIDANCE.md (and relevant rules/*.md) when work touches React/Next/TS/TSX in src/.
    • .agents/references/features/ for product-domain context before feature work.
    • .agents/references/implementation/ for coordinated implementation, worktree, QA, and review protocols.
  3. Follow them exactly when proposing or implementing changes.

If there is a conflict between an agent’s defaults and this repo, this repo wins.

Required workflow for any task​

  • Start by scanning the rules and identify which ones apply to the change you’re about to make.
  • Use .agents/skills/feature-context/SKILL.md before planning or implementing feature work so the right rules, coding standards, feature references, and live source files are loaded.
  • Prefer existing patterns/components in this codebase over introducing new abstractions.
  • Make the smallest reasonable change that solves the problem.
  • Keep changes local (avoid broad refactors unless explicitly requested).
  • Run the project’s checks/tests appropriate for your change when possible.
  • Do not commit or push unless the user explicitly asks.

Skill map​

Use repo skills when the request matches their purpose:

  • backprop: trace a bug or failing test back to the missing or unclear rule/spec, then update the right source of truth.
  • caveman: write compact, unambiguous SPEC.md and spec-adjacent updates.
  • check: run a read-only drift report between SPEC.md, repo rules, and the current implementation.
  • code-review: review diffs against rules, coding standards, feature references, and clear untwisted logic.
  • create-skeleton: create loading skeletons that match existing UI and design tokens.
  • do-lark-task: implement a NAS frontend ticket from a Lark or Feishu task and prepare PR work.
  • fe-tech-design: create a concise NAS frontend technical design document in Lark for large changes or feature reviews.
  • feature-context: load repo rules, coding standards, feature references, and live code before feature planning or implementation.
  • figma-spacing: implement exact Figma spacing/padding/sizing using the shared Figma guidance.
  • implement-feature: coordinate multi-task implementation with a master checklist, task-specific worktrees/subagents, QA, code review, and final integration.
  • install: local setup, dependency, MCP, RTK, and agent mirror guidance.
  • pr-description: update the current PR title/body from the branch diff.
  • pr-fixer: address PR review feedback locally without committing or pushing.
  • ready-pr: run code review and refresh PR metadata together.
  • self-test-doc: create or update a NAS frontend self-test document in Lark for QA handoff and browser evidence.
  • send-pr-message: draft or send a NAS frontend PR review request to Lark when explicitly requested.

High-impact rules to keep in mind​

These are frequently relevant and easy to accidentally violate:

  • Localization: Use direct t('key') calls with meaningful kebab-case keys and matching placeholders. Add only focused local English keys when required by the current locale rule; do not bulk-edit locale files.
  • React: Prefer clean, modern React; avoid unnecessary useEffect, avoid inline handlers, keep components focused.
  • React/Next performance: For frontend work in src/, follow vercel-react-best-practices/REPO-GUIDANCE.md and applicable rules/*.md; repo .mdc rules override conflicting Vercel guidance.
  • TypeScript: Prefer TypeScript for new files; avoid unsafe assertions (as) and any.
  • Styling: No inline styles (use Tailwind utilities). Use classnames for conditional className.
  • Figma: For Figma-driven work, use Figma MCP/design context and .agents/references/coding-standard/figma-guidance.md; do not guess spacing, sizing, typography, or colors.
  • Apifox API schemas: For frontend API/schema work, use Apifox project 8407323 (https://app.apifox.com/project/8407323) as the source of truth. Confirm authenticated access before real API integration, and do not invent missing endpoint or schema contracts.
  • Page structure: For new or substantially changed pages, put primary pages under src/pages/{specific-page}/index.page.tsx, page-local components/helpers beside that page, shared components in src/components, service/API contracts in src/services, and shared utilities in src/utility; search for reusable code before adding duplicates.
  • Feature context: For domain changes, load the relevant .agents/references/features/*.md pack and verify behavior against live code.
  • Implementation orchestration: For larger features, do not code before requirements, dependencies, master checklist, and worktree/subagent assignments are complete.
  • Worktree env files: When creating a new worktree, copy local .env and .env.* files from the source checkout into the new worktree before running app commands; never print or commit env contents.
  • Bun-first: Prefer bun for scripts/package management.
  • Security: Treat hostile input as default; avoid unsafe HTML injection and other insecure patterns.
  • Code review: Flag logic that is twisted, overly indirect, or inconsistent with existing references/coding standards.

Agent mirrors and MCP​

  • .agents/ is the canonical agent directory.
  • Run bun run sync-agents after editing .agents/; it mirrors content into .cursor, .claude, .codex, and .agent.
  • Shared MCP config lives in .agents/mcp.json.
  • Serena is configured with --open-web-dashboard=false so MCP startup does not auto-open a browser.

When you’re unsure​

  • Search the codebase for an existing example and match the established style.
  • Search .agents/references/ for domain and implementation context before inventing a workflow.
  • Ask for clarification only when needed to avoid incorrect behavior or breaking changes.

@RTK.md