feat: AI 번역 일관성 목적 명시 및 LLM 연동 지원

9bow · 9bow · commit 07e1c5454c53 · 2026-02-21T15:54:53.000+09:00
- README/AboutPage에 용어 표준화의 필요성과 AI 번역 일관성 목적 추가
- llms.txt 생성 (llmstxt.org 표준, LLM용 프로젝트 안내 및 데이터 링크)
- AGENTS.md 생성 (agents.md 표준, AI 코딩 에이전트용 가이드)
- AboutPage에 LLM/AI 번역 도구 연동 섹션 추가
- CLAUDE.md에 LLM 연동 정보 및 저장소/도메인 정보 반영
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,74 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents working in this repository.
+
+## Project Overview
+
+AI/ML 용어집 - An open-source glossary that standardizes Korean translations for AI/ML terminology. Operated by PyTorchKR (파이토치 한국 사용자 모임). Currently in PoC stage; all term data is AI-generated draft pending community review.
+
+**Repository**: `PyTorchKorea/kr-terms-poc` | **Branch**: `poc` | **Domain**: `poc.terms.kr`
+
+## Build & Dev Commands
+
+```bash
+npm install        # Install dependencies
+npm run dev        # Dev server at 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
+```
+
+## Architecture
+
+Static SPA (React 19 + TypeScript + Vite + MUI v7). No backend. All term data is JSON fetched at runtime from `public/data/`.
+
+- `data/index.json` → lists alphabet JSON files (`a.json`..`w.json`)
+- `prebuild` script copies `data/` → `public/data/`
+- HashRouter: `/` (search), `/term/:termId` (detail), `/about` (info)
+
+## Data Model
+
+```typescript
+// src/types/term.ts
+interface TermExample { en: string; ko: string; source?: string }
+interface TermMeaning {
+  korean: string              // Required - Korean translation
+  domain: string              // Required - no spaces (e.g., "딥러닝")
+  definition: string          // Required - Korean definition
+  examples: (string | TermExample)[]  // Prefer TermExample objects
+  synonyms: string[]
+}
+interface Term { term: string; meanings: TermMeaning[] }
+```
+
+## Adding/Editing Terms
+
+1. Edit `data/{letter}.json` (alphabetical)
+2. New letter file → add to `data/index.json`
+3. Required fields: `korean`, `domain` (no spaces), `definition`
+4. Examples: prefer `{ "en": "...", "ko": "...", "source": "https://..." }` format
+5. New domains need a color entry in `src/utils/domainColors.ts`
+
+## Code Style
+
+- React functional components with explicit `React.ReactNode` return types
+- MUI v7 `sx` prop for styling (no CSS modules)
+- Named exports (not default exports)
+- Immutable patterns - create new objects, don't mutate
+
+## CI/CD
+
+`.github/workflows/deploy.yml` on push to `poc`:
+1. Validates all JSON files (required fields, domain spacing, TermExample structure)
+2. Builds with `npm run build`
+3. Deploys to GitHub Pages
+
+## Testing
+
+No test framework configured. Validation is done via inline Node script in CI. When editing data, verify with `npm run build` which runs TypeScript checking.
+
+## Security
+
+- No secrets or API keys in this project
+- All data is public static JSON
+- No user input stored server-side (static site)
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -2,6 +2,12 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Project Context
+
+AI/ML 용어집 - 빠르게 변화하는 AI/ML 분야의 용어를 표준화하여 사람과 AI 번역 도구 모두가 일관된 한국어 번역을 사용할 수 있도록 하는 오픈소스 프로젝트. 파이토치 한국 사용자 모임(PyTorchKR) 운영. 현재 PoC 단계이며, 수록된 용어 데이터는 AI 생성 초안.
+
+**Repository**: `PyTorchKorea/kr-terms-poc` (branch: `poc`)
+
 ## Commands
 
 ```bash
@@ -17,7 +23,7 @@ No test framework is configured. Validation runs in CI via inline Node script in
 
 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.
+**Stack**: React 19 + TypeScript + Vite + MUI v7, deployed to GitHub Pages (`poc.terms.kr`).
 
 **Routing** (`App.tsx`): HashRouter with lazy-loaded pages.
 - `/` → `SearchPage` (search + alphabet filter)
@@ -58,10 +64,16 @@ Domain colors are mapped in `utils/domainColors.ts` (29 domains). New domains ne
 
 ## CI/CD
 
-`.github/workflows/deploy.yml`: On push to `main`, validates term data → builds → deploys to GitHub Pages. The validation step checks all JSON files for required fields, domain spacing, and TermExample structure.
+`.github/workflows/deploy.yml`: On push to `poc`, validates term data → builds → deploys to GitHub Pages. The validation step checks all JSON files for required fields, domain spacing, and TermExample structure.
+
+## LLM Integration
+
+- `public/llms.txt`: [llmstxt.org](https://llmstxt.org/) 표준에 따른 LLM용 안내 파일. 프로젝트 개요, 전체 데이터 파일 링크, 데이터 구조 설명 포함. 배포 시 `poc.terms.kr/llms.txt`로 접근 가능.
+- JSON 데이터는 `poc.terms.kr/data/index.json`에서 파일 목록 조회, 각 알파벳별 파일로 직접 접근 가능.
 
 ## Branding
 
 - Project name: "AI/ML 용어집"
 - Organization: "파이토치 한국 사용자 모임" (full) / "PyTorchKR" (short)
 - Theme primary: `#ee4c2c` (PyTorch orange-red), secondary: `#262626`
+- Domain: `poc.terms.kr`
diff --git a/README.md b/README.md
@@ -6,13 +6,27 @@ AI/ML 용어의 한국어 번역을 표준화하는 오픈소스 용어집입니
 
 🌐 **사이트**: [https://poc.terms.kr](https://poc.terms.kr)
 
+## 왜 AI/ML 용어집인가?
+
+번역은 생성형 AI 모델을 사용하여 자동화할 수 있지만, 이러한 번역 시에도 **일관된 용어를 사용하는 것은 매우 중요합니다.** AI/ML 용어집은 빠르게 변화하는 AI/ML 분야의 다양한 용어들을 표준화하고, 이를 공개하여 누구나 사용할 수 있도록 하는 것을 목표로 하고 있습니다.
+
 ## 프로젝트 목적
 
 개발자뿐 아니라 연구자, 번역가, 학생 등 **누구나** GitHub를 통해 AI/ML 용어의 한국어 번역을 제안하고 검토할 수 있는 열린 프로젝트입니다.
 
 - 동일한 용어가 여러 도메인에서 다른 의미로 사용될 때, 각각의 정의를 명확히 구분하여 제공합니다.
 - 코드를 몰라도 [GitHub Issue](https://github.com/PyTorchKorea/kr-terms-poc/issues)를 통해 새로운 용어 추가, 번역 개선, 오류 수정 등을 제안할 수 있습니다.
 
+## LLM / AI 번역 도구 연동
+
+이 용어집은 사람뿐 아니라 AI 도구에서도 활용할 수 있도록 기계 판독 가능한 형식을 제공합니다:
+
+- **[llms.txt](https://poc.terms.kr/llms.txt)**: [llmstxt.org](https://llmstxt.org/) 표준에 따른 LLM용 프로젝트 안내 파일
+- **[AGENTS.md](AGENTS.md)**: [agents.md](https://agents.md/) 표준에 따른 AI 코딩 에이전트용 프로젝트 가이드
+- **[JSON 데이터](https://poc.terms.kr/data/)**: 알파벳별 JSON 파일로 전체 용어 데이터에 접근 가능 (`data/index.json`에서 파일 목록 조회)
+
+AI 번역 시 이 용어집을 컨텍스트로 제공하면, 일관된 한국어 번역을 유지하는 데 도움이 됩니다.
+
 ## 피드백 및 제안
 
 수정이 필요한 사항이나 새로운 용어 제안은 GitHub Issue에서 받고 있습니다:
@@ -25,7 +39,7 @@ AI/ML 용어의 한국어 번역을 표준화하는 오픈소스 용어집입니
 - 🔍 **빠른 검색**: 영문 또는 한국어로 용어를 검색할 수 있습니다
 - 📚 **다의어 지원**: 하나의 용어가 여러 도메인에서 다른 의미로 사용될 때 모든 의미를 표시합니다
 - 🔤 **알파벳 탐색**: A-Z 알파벳별로 용어를 탐색할 수 있습니다
-- 🎨 **반응형 UI**: 모바일과 데스크톱 모두에서 사용하기 편리합니다
+- 🤖 **LLM 연동**: llms.txt 및 JSON API를 통해 AI 번역 도구에서 활용 가능합니다
 
 ## 기술 스택
 
diff --git a/public/llms.txt b/public/llms.txt
@@ -0,0 +1,68 @@
+# AI/ML 용어집 (terms.kr)
+
+> AI/ML 분야의 한국어 번역을 표준화하는 오픈소스 용어집입니다. 파이토치 한국 사용자 모임(PyTorchKR)에서 운영합니다.
+
+번역은 생성형 AI 모델을 사용하여 자동화할 수 있지만, 이러한 번역 시에도 일관된 용어를 사용하는 것은 매우 중요합니다. AI/ML 용어집은 빠르게 변화하는 AI/ML 분야의 다양한 용어들을 표준화하고, 이를 공개하여 누구나 사용할 수 있도록 하는 것을 목표로 하고 있습니다.
+
+이 프로젝트는 현재 PoC 단계이며, 수록된 용어 데이터는 AI가 생성한 초안입니다.
+
+## 용어 데이터
+
+용어 데이터는 알파벳별 JSON 파일로 제공됩니다. 각 용어는 영어 원문(term), 한국어 번역(korean), 분야(domain), 정의(definition), 예시(examples), 유의어(synonyms)를 포함합니다.
+
+- [파일 목록 (index.json)](https://poc.terms.kr/data/index.json): 전체 알파벳별 JSON 파일 목록
+- [A](https://poc.terms.kr/data/a.json): attention, agent, activation function, adversarial example, anchor box, all-reduce, autograd
+- [B](https://poc.terms.kr/data/b.json): B로 시작하는 용어
+- [C](https://poc.terms.kr/data/c.json): C로 시작하는 용어
+- [D](https://poc.terms.kr/data/d.json): D로 시작하는 용어
+- [E](https://poc.terms.kr/data/e.json): E로 시작하는 용어
+- [F](https://poc.terms.kr/data/f.json): F로 시작하는 용어
+- [G](https://poc.terms.kr/data/g.json): G로 시작하는 용어
+- [H](https://poc.terms.kr/data/h.json): H로 시작하는 용어
+- [I](https://poc.terms.kr/data/i.json): I로 시작하는 용어
+- [K](https://poc.terms.kr/data/k.json): K로 시작하는 용어
+- [L](https://poc.terms.kr/data/l.json): L로 시작하는 용어
+- [M](https://poc.terms.kr/data/m.json): M로 시작하는 용어
+- [N](https://poc.terms.kr/data/n.json): N으로 시작하는 용어
+- [O](https://poc.terms.kr/data/o.json): O로 시작하는 용어
+- [P](https://poc.terms.kr/data/p.json): P로 시작하는 용어
+- [Q](https://poc.terms.kr/data/q.json): Q로 시작하는 용어
+- [R](https://poc.terms.kr/data/r.json): R로 시작하는 용어
+- [S](https://poc.terms.kr/data/s.json): S로 시작하는 용어
+- [T](https://poc.terms.kr/data/t.json): T로 시작하는 용어
+- [U](https://poc.terms.kr/data/u.json): U로 시작하는 용어
+- [V](https://poc.terms.kr/data/v.json): V로 시작하는 용어
+- [W](https://poc.terms.kr/data/w.json): W로 시작하는 용어
+
+## 데이터 구조
+
+```json
+{
+  "term": "attention",
+  "meanings": [
+    {
+      "korean": "어텐션",
+      "domain": "딥러닝",
+      "definition": "입력 시퀀스의 각 요소에 서로 다른 가중치를 부여하여 중요한 정보에 집중하는 메커니즘",
+      "examples": [
+        {
+          "en": "The Transformer model uses a self-attention mechanism.",
+          "ko": "트랜스포머 모델은 셀프 어텐션 메커니즘을 사용한다."
+        }
+      ],
+      "synonyms": ["주의 메커니즘", "집중 메커니즘"]
+    }
+  ]
+}
+```
+
+## 기여
+
+- [GitHub 저장소](https://github.com/PyTorchKorea/kr-terms-poc)
+- [기여 가이드](https://github.com/PyTorchKorea/kr-terms-poc/blob/poc/CONTRIBUTING.md)
+- [새 용어 요청](https://github.com/PyTorchKorea/kr-terms-poc/issues/new?template=new-term.yml)
+- [용어 피드백](https://github.com/PyTorchKorea/kr-terms-poc/issues/new?template=term-feedback.yml)
+
+## Optional
+
+- [프로젝트 소개 페이지](https://poc.terms.kr/#/about): 사용 방법, 데이터 구조, 기여 방법 안내
diff --git a/src/pages/AboutPage.tsx b/src/pages/AboutPage.tsx
@@ -17,20 +17,24 @@ export function AboutPage(): React.ReactNode {
           </Typography>
         </Box>
 
-        {/* Section 1: 프로젝트 소개 */}
+        {/* Section 1: 왜 AI/ML 용어집인가? */}
         <Paper elevation={2} sx={{ p: 4, mb: 3 }}>
           <Typography variant="h5" gutterBottom sx={{ fontWeight: 600, mb: 2 }}>
-            📖 프로젝트 목표
+            📖 왜 AI/ML 용어집인가?
+          </Typography>
+          <Typography variant="body1" paragraph>
+            번역은 생성형 AI 모델을 사용하여 자동화할 수 있지만, 이러한 번역 시에도 <strong>일관된 용어를 사용하는 것은 매우 중요합니다.</strong>{' '}
+            AI/ML 용어집은 빠르게 변화하는 AI/ML 분야의 다양한 용어들을 표준화하고, 이를 공개하여 누구나 사용할 수 있도록 하는 것을 목표로 하고 있습니다.
           </Typography>
           <Typography variant="body1" paragraph>
-            AI/ML 분야의 급속한 발전과 함께 다양한 용어들이 등장하고 있지만, 한국어 번역이 통일되지 않아 혼란이 발생하고 있습니다.
             이 프로젝트는 커뮤니티 기반으로 용어의 표준화된 번역을 제공하고, 다의어와 맥락별 번역을 체계적으로 관리합니다.
           </Typography>
           <Box sx={{ display: 'flex', gap: 1, flexWrap: 'wrap', mt: 2 }}>
             <Chip label="오픈소스" color="primary" size="small" />
             <Chip label="커뮤니티 기반" color="secondary" size="small" />
             <Chip label="다의어 지원" color="info" size="small" />
             <Chip label="맥락 기반 번역" color="success" size="small" />
+            <Chip label="LLM 연동" color="warning" size="small" />
           </Box>
         </Paper>
 
@@ -148,6 +152,32 @@ export function AboutPage(): React.ReactNode {
           </Typography>
         </Paper>
 
+        {/* Section 5: LLM / AI 번역 도구 연동 */}
+        <Paper elevation={2} sx={{ p: 4, mb: 3 }}>
+          <Typography variant="h5" gutterBottom sx={{ fontWeight: 600, mb: 2 }}>
+            🤖 LLM / AI 번역 도구 연동
+          </Typography>
+          <Typography variant="body1" paragraph>
+            이 용어집은 사람뿐 아니라 AI 도구에서도 활용할 수 있도록 기계 판독 가능한 형식을 제공합니다.
+            AI 번역 시 이 용어집을 컨텍스트로 제공하면, 일관된 한국어 번역을 유지하는 데 도움이 됩니다.
+          </Typography>
+          <List>
+            <ListItem>
+              <ListItemText
+                primary="llms.txt"
+                secondary="llmstxt.org 표준에 따른 LLM용 프로젝트 안내 파일 (poc.terms.kr/llms.txt)"
+              />
+            </ListItem>
+            <Divider component="li" />
+            <ListItem>
+              <ListItemText
+                primary="JSON 데이터"
+                secondary="알파벳별 JSON 파일로 전체 용어 데이터에 접근 가능 (poc.terms.kr/data/)"
+              />
+            </ListItem>
+          </List>
+        </Paper>
+
         {/* CTA Section */}
         <Box sx={{ textAlign: 'center', mt: 6 }}>
           <Typography variant="h6" gutterBottom sx={{ mb: 3 }}>
