이 문서는 코드베이스에서 일할 때 보는 빠른 참조다.
README.md — 프로젝트가 무엇 인가CONTRIBUTING.md — 어떻게 협업 하는가 (브랜치·hook·PR)AGENTS.md (이 문서) — 어디서 무엇을 만지는가, 무엇을 하지 말아야 하는가
- spec이 코드보다 먼저 —
docs/specs/*.md에 근거 없는 코드는 들어가지 않는다.
- 결정론적 검증 게이트 — LLM은 정답 판단을 하지 않는다 (D-1). SymPy + 학습목표 매칭만 최종 판정.
- 인터페이스 안정, 구현 자유 — agent 코드가 의존하는 건 인터페이스 (
RagClient, MathEngineClient, PromptLoader). 그 뒤 구현은 swap 가능.
main 직접 push 금지 — pre-push hook이 차단. feat/<scope>-<name> 브랜치 → PR.[본인] vs [비할당] 영역 확인 — 무엇을 만져도 되는지 먼저 본다.
| spec |
코드 |
docs/specs/architecture.md §3 components |
packages/{agent,math-engine,web}/ |
docs/specs/architecture.md §7 D-1 (결정론 게이트) |
packages/agent/src/schemas/verification.schema.ts assertVerificationInvariants |
| D-4 (Vercel AI SDK) |
packages/agent/src/tools/llm-provider.ts |
| D-5 (Specialist 구성) |
packages/agent/src/agents/*, packages/agent/src/steps/* |
| D-6 (SSE) |
packages/agent/src/server/sse/progress-stream.ts, packages/agent/src/server/routes/generate.ts |
| D-7 (RagClient) |
packages/agent/src/tools/rag-client.ts |
| D-8 (.md frontmatter) |
packages/agent/src/tools/prompt-loader.ts, packages/agent/prompts/*.md |
| D-9 (Next.js 14 + 듀얼-서피스 디자인) |
packages/web/, packages/web/DESIGN.md |
| D-11 (I-G4 투명 노출 정책) |
packages/agent/src/server/routes/generate.ts, packages/web/DESIGN.md {component.result-card-failed} |
| D-12 (S0-B OCR v2 보류) |
packages/web/ S0 카드 disabled 상태 |
docs/specs/domain.md §2 도메인 |
packages/agent/src/schemas/*.schema.ts |
| 불변식 I-V1 ~ I-V5 |
assertVerificationInvariants |
| 불변식 I-I1 ~ I-I3 |
IntentSchema.regex + assertIntentInvariants |
| 불변식 I-T1 ~ I-T4 |
StrategySchema.regex + assertStrategyInvariants |
| 작업 |
명령 |
| 의존성 설치 + git hooks |
pnpm install |
| 세 서비스 동시 dev |
pnpm dev:all |
| agent만 dev |
pnpm dev (:31415) |
| math-engine만 dev |
pnpm dev:math (:16180) |
| web만 dev |
pnpm dev:web (:27182) |
| Node typecheck (agent + web) |
pnpm typecheck |
| Node unit test (agent) |
pnpm -F @openmath/agent test |
| Node integration test |
pnpm -F @openmath/agent test:integration |
| Python pytest |
pnpm test:python |
| Web build |
pnpm -F @openmath/web build |
| DESIGN.md lint |
npx @google/design.md lint packages/web/DESIGN.md |
| 전체 테스트 (pre-push) |
pnpm test |
pnpm test = Node + Python. integration / web build 는 별도. PR 전엔 모두 확인 권장.
| ID |
결정 |
한 줄 |
| D-1 |
생성·검증 분리 |
LLM 생성, SymPy 검증 |
| D-2 |
Node + Python 두 서비스 |
HTTP/JSON |
| D-3 |
1차 사용자 = 학원 강사 |
인증 1차 MVP out |
| D-4 |
Vercel AI SDK |
ai + @ai-sdk/* |
| D-5 |
(β) 명명 + (ε) Hybrid |
Generation 노드만 multi-agent |
| D-6 |
SSE 스트리밍 |
step bar 라이브 노출 |
| D-7 |
RagClient 인터페이스 + JSONL MVP |
swap 가능 |
| D-8 |
프롬프트 = .md + YAML frontmatter |
hot-reload |
| D-9 |
packages/web Next.js 14 + 듀얼-서피스 DESIGN.md |
editorial + productivity 한 시스템 |
| D-10 |
인증 = Better Auth (v2 트리거) |
1차 MVP 는 인증 없음, 캡스톤 데모 후 도입 |
| 용어 |
의미 |
| SourceProblem |
원본 정규화 문제 (math-sample-unified-v1, 2,400건) |
| Intent |
학습 목표 + 평가 차원 (동형성 판정의 축) |
| GeneratedProblem |
LLM 생성 후보 (검증 전엔 사용자에게 노출 X — I-G4) |
| Verification |
6단계 결과 + overall ∈ {verified, rejected, warning} |
| Strategy |
성취기준별 출제 룰 (data/achievement-standards/<code>.yaml) |
| Structural isomorphic |
숫자·표현 변형, 풀이 단계 동일 |
| Conceptual isomorphic |
학습 목표·평가 차원 보존, 풀이 경로 다름 |
agent 코드를 건드리지 않고 동작이 바뀌는 영역.
| 영역 |
위치 |
누가 만지나 |
| 프롬프트 |
packages/agent/prompts/*.md |
[비할당] |
| 출제 전략 |
packages/agent/data/achievement-standards/*.yaml |
[비할당] |
| RAG corpus |
packages/agent/data/corpus/*.jsonl |
[비할당] |
| 프론트 디자인 토큰 |
packages/web/DESIGN.md frontmatter |
[비할당] (FE 디자이너) |
| 프론트 컴포넌트 |
packages/web/components/**/*.tsx |
[비할당] (FE 엔지니어) |
| 프론트 페이지 (S0~S6) |
packages/web/app/**/page.tsx |
[비할당] (FE 엔지니어) |
이 영역의 변경은 prompt-loader / strategy-loader / rag-client / DESIGN.md 토큰 시스템이 흡수.
architecture.md §7에 D-N 추가 (결정 / 대안 / 채택 사유)- 관련 Q-* 있으면
Closed by D-N 표시
- 코드 변경 같은 PR로 묶음
domain.md §2 갱신packages/agent/src/schemas/*.schema.ts Zod schema 갱신- 새 불변식이면
assertXxxInvariants 추가
tests/placeholder.test.ts에 invariant 테스트 추가
prompts/<id>.md frontmatter version 올림 (semver)- body 수정
- commit. agent 코드 변경 없음
architecture.md D-5 갱신 (Specialist 구성 변경)packages/agent/src/steps/<name>.ts 또는 agents/<name>-agent.ts 추가workflows/verification-workflow.ts orchestrator에 step 삽입schemas/verification.schema.ts의 StepName enum 확장- invariant I-V1 (gates.length=6) 영향 시 도메인 spec 먼저 갱신
| 금지 |
이유 |
| LLM에게 정답 판단 시키기 |
D-1 위반. 검증 게이트는 결정론 (SymPy + objective_map) |
| 멀티에이전트 debate를 검증 게이트로 사용 |
D-5 (ε): debate는 합의 ≠ 정답 |
검증 안 된 GeneratedProblem을 사용자에게 노출 |
I-G4 |
as any / @ts-ignore / @ts-expect-error |
CONTRIBUTING.md 코드 스타일 |
빈 catch(e) {} |
실패 은닉 |
--no-verify로 hook 우회 |
CONTRIBUTING.md — 예외 상황 외 금지 |
main 직접 push |
pre-push hook + GitHub branch protection |
| 실패하는 테스트를 지워서 녹색으로 만들기 |
회귀 무방비 |
grep -rn "not implemented yet" packages/agent/src 로 0곳 — 아래 진입점 모두 구현 완료.
| Priority |
파일 |
비고 |
| P0 |
tools/math-engine-client.ts createMathEngineClient |
구현 완료 |
| P0 |
tools/prompt-loader.ts createFsPromptLoader |
구현 완료 (gray-matter + handlebars) |
| P0 |
tools/llm-provider.ts resolveLanguageModel |
구현 완료 (CLIProxyAPI 우선) |
| P1 |
tools/rag-client.ts createInMemoryRagClient |
구현 완료 (JSONL + filter) |
| P1 |
agents/*-agent.ts (4개) |
구현 완료 |
| P1 |
steps/*.ts (6개) |
구현 완료 |
| P2 |
workflows/verification-workflow.ts |
구현 완료 |
| P2 |
server/routes/generate.ts + sse/progress-stream.ts |
구현 완료 |
| P3 |
src/index.ts main |
구현 완료 |