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/codebase-memory-guidance.md for graph-first code discovery, dependency tracing, and impact analysis.
    • .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 codebase-memory MCP first for code discovery: select/index the exact current worktree, then use graph search and traces before shell search. Use rg/find for non-code files or documented fallbacks.
  • 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:

  • 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.
  • Code discovery: Follow codebase-memory-first.mdc; use graph search, dependency traces, and impact analysis before reading/editing central source files.

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.
  • Codebase-memory MCP is the shared stdio server for repository indexing, architecture, symbol search, dependency tracing, source snippets, and changed-code impact analysis.

When you’re unsure​

  • Search the codebase graph first for an existing example and match the established style; fall back to shell search only under the documented codebase-memory guidance.
  • 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

Maintaining this file​

Keep this file for knowledge useful to almost every future agent session in this project. Do not repeat what the codebase already shows; point to the authoritative file or command instead. Prefer rewriting or pruning existing entries over appending new ones. When updating this file, preserve this bar for all agents and keep entries concise.