terms-kr: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents working in this repository.

Project Context

AI/ML 용어집 - 빠르게 변화하는 AI/ML 분야의 용어를 표준화하여 사람과 AI 번역 도구 모두가 일관된 한국어 번역을 사용할 수 있도록 하는 오픈소스 프로젝트. 파이토치 한국 사용자 모임(PyTorchKR) 운영. 현재 PoC 단계이며, 수록된 용어 데이터는 AI 생성 초안.

Repository: PyTorchKR/terms-kr (branch: main)

Commands

npm install        # Install dependencies
npm run dev        # Dev server (http://localhost:5173), auto-copies data/ to public/data/
npm run build      # TypeScript check + Vite production build
npm run lint       # ESLint
npm run preview    # Preview production build

No test framework is configured. Validation runs in CI via inline Node script in .github/workflows/deploy.yml.

Architecture

Static SPA for AI/ML Korean terminology glossary. No backend; all data is JSON fetched at runtime.

Stack: React 19 + TypeScript + Vite + MUI v7, deployed to GitHub Pages (terms.kr).

Routing (App.tsx): HashRouter with lazy-loaded pages.

• / -> SearchPage (search + alphabet filter)
• /term/:termId -> TermDetailPage (accordion per meaning, related terms)
• /about -> AboutPage

Data flow: data/index.json lists alphabet JSON files (a.json..w.json). At build time, prebuild copies data/ -> public/data/. At runtime, loadTerms.ts fetches all files in parallel via Promise.all, flattens, and sorts. The useTerms hook caches this; useSearch debounces (200ms) and filters across term, korean, synonyms.

Homepage: SearchPage embeds HeroSection (stats) + AlphabetNavigation (A-Z chips) + TermCard grid. The Layout component wraps non-home pages with AppBar + footer; home page hides AppBar.

Data Model

Defined in src/types/term.ts:

interface TermExample { en: string; ko: string; source?: string }
interface TermMeaning {
  korean: string              // Required
  definition: string          // Required
  examples: (string | TermExample)[]  // Union type for backward compat
  synonyms: string[]
}
interface Term {
  term: string
  meanings: TermMeaning[]
  issueNumber?: number       // GitHub Issue number for traceability
  notes?: string             // Editorial notes (why this translation was chosen)
}