[Chess] 체스 용어집

1. 문서 목적

이 문서는 JunkBox chess 앱을 개발하고 운영할 때 공통으로 사용할 체스 용어를 정의함.

대상 독자는 체스 규칙을 배우는 중인 개발자와 AI 코딩 에이전트임. 따라서 이 문서는 체스 고급 이론서가 아니라, chess-api, chess-ui, shared-ai, 프롬프트, 로그, DB 필드에서 같은 단어를 같은 의미로 쓰기 위한 기준 문서임.

2. 표기법

2.1 Square

square는 체스판의 한 칸을 뜻함.

체스판은 파일과 랭크로 좌표를 표현함.

• file: 세로줄. 왼쪽부터 a부터 h까지 사용함.
• rank: 가로줄. 흰색 기준 아래에서 위로 1부터 8까지 사용함.
• e4: e file과 4 rank가 만나는 칸임.

프로젝트에서는 칸 좌표를 항상 소문자 algebraic square 문자열로 표현함.

예:

a1
e2
e4
h8

2.2 UCI

UCI는 Universal Chess Interface의 약자임.

원래는 체스 엔진과 GUI가 대화하기 위한 표준 인터페이스 이름임. JunkBox에서는 보통 한 수를 기계가 읽기 쉬운 좌표 문자열로 표현하는 방식을 가리킴.

UCI move는 기본적으로 출발 칸 + 도착 칸 형식임.

예:

e2e4
g1f3
e7e8q

의미:

• e2e4: e2에 있던 기물이 e4로 이동함.
• g1f3: g1에 있던 기물이 f3으로 이동함.
• e7e8q: e7 폰이 e8로 이동하며 queen으로 승진함.

UCI는 경로 전체를 표현하지 않음. 출발 칸과 도착 칸을 표현함. 나이트처럼 점프하는 기물도 g1f3처럼 출발과 도착만 씀.

프로젝트 기준:

• Lichess Bot API move 제출에는 UCI 문자열을 사용함.
• legal_moves는 UCI 문자열 목록으로 다룸.
• DB의 uci 필드는 UCI 문자열을 저장함.
• LLM의 구조화 응답은 UCI 문자열을 직접 출력하지 않고 legal moves choice 목록의 choice 번호를 출력함.
• 앱 계층은 choice 번호를 UCI 문자열로 매핑한 뒤 Lichess Bot API move 제출에 사용함.

2.3 SAN

SAN은 Standard Algebraic Notation의 약자임.

사람이 기보를 읽을 때 쓰는 표준 대수 표기법임. UCI가 기계 친화적이라면 SAN은 사람 친화적임.

예:

e4
Nf3
Qxf7#
O-O
O-O-O

의미:

• e4: 폰이 e4로 이동함.
• Nf3: 나이트가 f3으로 이동함.
• Qxf7#: queen이 f7의 기물을 잡으며 체크메이트함.
• O-O: 킹사이드 캐슬링임.
• O-O-O: 퀸사이드 캐슬링임.

기물 문자는 아래처럼 씀.

• K: King
• Q: Queen
• R: Rook
• B: Bishop
• N: Knight
• 폰은 보통 기물 문자를 쓰지 않음.

SAN에서 자주 보이는 기호:

• x: capture, 기물을 잡음
• +: check
• #: checkmate
• =: promotion

프로젝트 기준:

• UI에서 사람이 읽는 move 배지는 SAN을 우선 표시함.
• DB의 san 필드는 SAN 문자열을 저장함.
• Lichess 제출용 최종 move는 SAN이 아니라 UCI를 사용함.
• LLM 응답에는 SAN이나 UCI move 문자열 대신 choice 번호를 사용함.

2.4 FEN

FEN은 Forsyth-Edwards Notation의 약자임.

현재 체스판 상태 하나를 문자열로 표현하는 표기임. PGN이 대국 전체 기록이라면 FEN은 특정 순간의 스냅샷임.

FEN에는 보통 다음 정보가 들어감.

• 각 칸의 기물 배치
• 현재 차례
• 캐슬링 가능 여부
• 앙파상 가능 칸
• halfmove clock
• fullmove number

예:

rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

프로젝트 기준:

• fen은 해당 로그 시점의 보드 상태를 재현하기 위한 원본임.
• LLM 입력에는 현재 FEN을 포함함.
• Stockfish 사후 분석과 RAG feature 추출의 기준 입력으로 사용할 수 있음.

2.5 PGN

PGN은 Portable Game Notation의 약자임.

대국 전체 기보를 저장하고 교환하기 위한 표기임.

예:

1. e4 e5 2. Nf3 Nc6 3. Bb5 a6

프로젝트 기준:

• DB의 pgn 필드는 해당 로그 시점까지의 대국 흐름을 저장함.
• LLM 입력에는 전체 PGN 대신 최근 구간만 축약해서 넣을 수 있음.
• 게임 후 Stockfish 분석은 PGN 또는 UCI move list를 기반으로 각 ply를 복원함.

3. 수 순서와 로그 용어

3.1 Move

move는 넓게는 한 번의 착수를 뜻함.

다만 프로젝트에서는 move라는 단어만 쓰면 UCI인지 SAN인지 애매해질 수 있음. 따라서 가능한 한 uci, san, selected_move, played_move, candidate_move처럼 구체적인 이름을 씀.

프로젝트 기준:

• LLM 출력은 move 문자열 대신 legal moves choice 목록의 choice 정수를 사용함.
• choice는 앱 계층에서 UCI 문자열로 매핑된 뒤 selected_move 또는 played_move로 다룸.
• DB의 move는 원본 move 문자열을 보존하는 필드임.
• 표시용 move는 SAN이 있으면 SAN을 우선 사용함.

3.2 Ply

ply는 한쪽이 한 번 둔 반수를 뜻함.

예:

1. e4 e5 2. Nf3 Nc6

ply 기준:

• ply 1: white e4
• ply 2: black e5
• ply 3: white Nf3
• ply 4: black Nc6

프로젝트 기준:

• ply_number는 대국의 반수 번호임.
• 흰색 첫 수가 1, 검은색 첫 수가 2임.
• 같은 대국 안에서 move log 정렬의 핵심 기준으로 사용함.

3.3 Full Move

full move는 흰색 한 수와 검은색 한 수를 묶은 단위임.

예:

1. e4 e5

여기서 1은 full move number다. 이 full move에는 white e4와 black e5가 들어 있음.

프로젝트 기준:

• 체스 이론에서 말하는 일반적인 수 번호는 full move number에 가까움.
• DB와 UI에서는 혼동을 줄이기 위해 가능하면 ply_number를 우선 사용함.

3.4 Turn

turn은 일반적으로 "현재 누가 둘 차례인가"를 뜻함.

프로젝트에서는 기존 구현과 UI 관성 때문에 turn_number라는 필드가 있을 수 있음. 단, 체스 이론의 full move number와 반드시 같다고 가정하지 않음.

프로젝트 기준:

• turn_number는 UI와 기존 로그 호환을 위한 표시용 순서 값임.
• 정확한 반수 순서는 ply_number를 기준으로 판단함.
• 신규 코드에서는 체스 규칙 계산이나 분석 기준으로 ply_number를 우선 사용함.

4. 기물 용어

4.1 Piece

piece는 체스 기물을 뜻함.

프로젝트에서는 아래 영어 이름을 기본으로 사용함.

• king: 킹
• queen: 퀸
• rook: 룩
• bishop: 비숍
• knight: 나이트
• pawn: 폰

4.2 Material

material은 양쪽이 가진 기물 가치의 총합 또는 그 차이를 뜻함.

기본 기물 가치는 보통 아래처럼 잡음.

• pawn: 100
• knight: 320
• bishop: 330
• rook: 500
• queen: 900
• king: 점수 계산 대상에서 제외하거나 무한대로 취급

프로젝트 기준:

• 자체 휴리스틱 평가에서 material score를 사용함.
• Stockfish 평가값과 material score는 다른 개념임.

4.3 Hanging Piece

hanging piece는 보호가 약하거나 공짜로 잡힐 수 있는 기물을 뜻함.

프로젝트에서는 특히 queen과 rook을 공짜로 잃는 상황을 우선 감지함.

예:

• hanging_queen
• hanging_rook

프로젝트 기준:

• risk_tags에 hanging 관련 태그를 기록함.
• 후보수 압축 전 단계에서 강한 감점 또는 제거 대상으로 삼음.

5. 전술과 상태 용어

5.1 Legal Move

legal move는 현재 체스 규칙상 실제로 둘 수 있는 합법수임.

프로젝트 기준:

• python-chess의 board.legal_moves를 기준으로 생성함.
• LLM 프롬프트에는 legal_moves를 choice 번호가 붙은 목록으로 렌더링함.
• LLM은 legal moves choice 목록 안의 번호 하나만 선택해야 함.
• 앱 계층은 choice 번호를 UCI move로 매핑하고, 최종 제출 전에도 legal moves 포함 여부를 다시 검증함.

5.2 Candidate Move

candidate move는 legal moves 중에서 도구 평가를 거쳐 LLM에게 보여줄 후보수임.

모든 legal moves가 candidate move는 아님. 전술 안전 필터와 휴리스틱 평가를 통과하거나 상위 점수를 받은 일부 move만 candidate move가 됨.

프로젝트 기준:

• 후보수 압축 이후 LLM 입력에는 candidate_moves를 넘김.
• 각 candidate move는 move, tool_score, risk_tags, tags 같은 정보를 가질 수 있음.

5.3 Check

check는 상대 킹이 공격받는 상태임.

체크를 받은 쪽은 반드시 체크를 해소하는 수를 둬야 함.

프로젝트 기준:

• 체크 상태에서는 체크 해소 legal moves만 존재함.
• 별도 CheckResponseNode를 둘 경우 체크 상황을 우선 처리함.

5.4 Checkmate

checkmate는 체크 상태이고, 체크를 해소할 합법수가 없는 상태임.

프로젝트 기준:

• mate-in-1 감지의 핵심 목표임.
• 사후 분석에서는 missed mate와 allowed mate를 분류할 때 사용함.

5.5 Stalemate

stalemate는 체크는 아니지만 둘 수 있는 합법수가 없는 상태임.

대부분의 체스 규칙에서는 무승부임.

프로젝트 기준:

• 게임 종료 상태 판단에 포함함.
• 이기는 상황에서 stalemate를 허용하는 수는 위험한 후보로 볼 수 있음.

5.6 Mate-in-1

mate-in-1은 지금 한 수만 두면 바로 체크메이트가 되는 상황임.

프로젝트 기준:

• 내가 mate-in-1을 낼 수 있으면 최우선 후보로 다룸.
• LLM이 놓치기 쉬우므로 코드로 감지함.

5.7 Opponent Mate-in-1 Threat

opponent mate-in-1 threat는 내가 어떤 수를 둔 뒤 상대가 다음 한 수로 나를 체크메이트할 수 있는 위험임.

프로젝트 기준:

• 이 위험을 허용하는 후보수는 제거하거나 강하게 감점함.
• risk_tags에는 allows_mate_in_1 같은 태그를 사용할 수 있음.

5.8 Blunder, Mistake, Inaccuracy

게임 후 분석에서 수의 나쁨 정도를 분류하는 용어임.

• inaccuracy: 작은 부정확함
• mistake: 의미 있는 실수
• blunder: 큰 실수

프로젝트 기준:

• 실전 중에는 Stockfish로 이 값을 판단하지 않음.
• 게임 후 Stockfish 분석에서 eval drop 기준으로 분류함.
• 오답노트 생성은 보통 mistake 이상을 대상으로 함.

6. 특수 규칙 용어

6.1 Castling

castling은 킹과 룩을 한 번에 움직이는 특수 수임.

SAN 표기:

• O-O: 킹사이드 캐슬링
• O-O-O: 퀸사이드 캐슬링

UCI 예:

• white kingside castling: e1g1
• white queenside castling: e1c1
• black kingside castling: e8g8
• black queenside castling: e8c8

프로젝트 기준:

• UCI move 제출은 왕의 출발 칸과 도착 칸으로 표현함.
• SAN 표시에서는 O-O, O-O-O를 사용함.
• FEN에는 캐슬링 가능 여부가 포함됨.

6.2 Promotion

promotion은 폰이 마지막 rank에 도달해서 queen, rook, bishop, knight 중 하나로 승진하는 규칙임.

UCI 예:

e7e8q
a2a1n

SAN 예:

e8=Q
a1=N

프로젝트 기준:

• UCI promotion move는 마지막에 승진 기물 문자를 붙임.
• 일반적으로 queen promotion이 가장 흔함.

6.3 En Passant

en passant는 폰과 관련된 특수 capture 규칙임.

상대 폰이 시작 위치에서 두 칸 전진해 내 폰 옆을 지나간 직후, 내 폰이 그 폰을 한 칸 전진한 것처럼 잡을 수 있음.

프로젝트 기준:

• 직접 규칙을 구현하지 않고 python-chess legal moves에 맡김.
• FEN에는 en passant 가능 칸 정보가 포함될 수 있음.

7. AI와 분석 용어

7.1 Thought

thought는 LLM이 관전 로그용으로 남기는 짧은 설명임.

프로젝트 기준:

• 긴 chain-of-thought가 아님.
• 현재 상황과 착수 근거를 짧게 설명하는 사용자 표시용 문장임.
• 실전 프롬프트에서는 JSON 외 사족을 금지함.

7.2 Tool Score

tool_score는 Stockfish 없이 프로젝트 내부 도구가 계산한 후보수 점수임.

프로젝트 기준:

• material, 전개, 중앙 점유, 킹 안전, 위험 태그 등을 조합함.
• Stockfish eval과 혼동하지 않음.
• 후보수 압축에 사용함.

7.3 Risk Tag

risk_tag는 후보수의 위험을 설명하는 짧은 태그임.

예:

hanging_queen
allows_mate_in_1
premature_queen_move
king_exposure

프로젝트 기준:

• 로그와 RAG lesson에서 반복 실수 유형을 연결하는 키로 씀.
• 사람이 읽는 설명보다 짧고 일관된 snake_case를 사용함.

7.4 Lesson

lesson은 게임 후 분석에서 만들어지는 오답노트 항목임.

프로젝트 기준:

• Stockfish 분석 결과와 실전 로그를 바탕으로 생성함.
• best move 암기장이 아니라 다음에 피해야 할 원칙을 담음.
• RAG 검색 대상이 됨.

7.5 RAG

RAG는 Retrieval-Augmented Generation의 약자임.

현재 입력과 관련된 문서를 검색해서 LLM 생성에 참고시키는 방식임.

프로젝트 기준:

• 체스 실전 RAG는 Stockfish 정답지가 아니라 오답노트 검색임.
• 모든 수마다 호출하지 않고 위험 상황에서만 호출함.
• 검색 결과는 짧은 주의 규칙으로만 프롬프트에 넣음.

8. 프로젝트 필드명 기준

8.1 권장 필드명

• fen: 현재 보드 상태 FEN
• pgn: 해당 시점까지의 PGN
• uci: UCI move 문자열
• san: SAN move 문자열
• move: 기존 호환용 move 문자열. 신규 문맥에서는 의미를 명확히 해야 함.
• ply_number: 반수 번호
• turn_number: UI와 기존 로그 호환용 순서 값
• legal_moves: 현재 합법 UCI move 목록
• candidate_moves: LLM에게 넘기는 후보수 목록
• choice: LLM 구조화 응답이 선택한 legal moves 목록의 정수 번호
• selected_move: 최종 선택된 UCI move
• played_move: 실제 제출되거나 실제 둔 UCI move
• risk_tags: 후보수 또는 착수의 위험 태그 목록
• tool_score: 자체 도구 점수
• classification: 사후 분석의 수 분류

8.2 네이밍 원칙

• 기계 제출과 검증에는 UCI를 사용함.
• 사람 표시에는 SAN을 우선 사용함.
• LLM 구조화 응답에는 UCI 문자열 대신 choice 번호를 사용함.
• 분석과 재현에는 FEN과 PGN을 함께 저장함.
• 수 순서 계산은 ply_number를 우선 사용함.
• move만 단독으로 쓰는 신규 필드는 피하고, 가능한 한 uci, san, selected_move, played_move처럼 구체화함.