doslang-mirror/AGENTS.md

doslang 작업 규칙

DOS용 시스템 프로그래밍 언어 Ferro와 그 컴파일러 fec. 규범 문서는 SPEC.md이며 이 파일은 그것을 구현할 때의 작업 규칙만 다룬다.

문서 지도

파일	역할
SPEC.md	언어 명세. 유일한 규범 문서. 구현 지시서와 표준 라이브러리 명세는 별도 문서
TODO.md	남은 작업, 미결 결정, 순서
fec/tests/*/README.md	각 fixture 디렉터리가 무엇을 검사하는지

테스트 명령과 플래그는 다음 CLI로 확인한다.

uv run python tests/run.py --help

검증 규칙

• 컴파일러는 현재 프런트엔드만 구현되어 있다. 범위: lexer/parser/types/own/check/resolve.
• 코드 생성기(백엔드/IR/lowering)는 아직 없다.
• 호스트 C 컴파일러는 구현/검증 대상이 아니다. 호스트는 편집, Git, 다운로드, 격리 작업공간 준비에만 쓴다.
• 완료하려는 기능을 직접 검사하는 fixture가 통과해야 한다. 테스트가 증명하지 않는 기능은 완료로 처리하지 않는다.
• uv run python tests/run.py 가 유일한 검증 엔트리다. 툴체인은 .dosboxx/watcom에 고정되어 있고, 없으면 오류로 멈춘다.
• 거부를 기대하는 fixture는 첫 줄에 // ERROR:<줄>:<문구> 마커를 둔다. 마커가 없으면 "거부되기만 하면 통과"라 검증이 약하다.
• 과거 VM 이미지나 호스트에 남은 바이너리는 완료 근거로 쓰지 않는다.
• 실행해야만 검증되는 fixture는 fec/tests/pending-backend/에 두고 러너가 건너뛴다.

빌드 함정

• [백엔드 복귀 시 유효] 컴파일러는 16비트 large model로 빌드한다. small model은 메모리 부족으로 실패한다.
• [백엔드 복귀 시 유효] 링크는 *.obj 와일드카드로 한다. DOS 명령줄 길이 제한 때문에 오브젝트를 개별 열거할 수 없다.
• [백엔드 복귀 시 유효] M4 Watcom 테스트는 -wx -wcd=202를 쓴다. 생성 C의 보수적 미 사용 helper 때문에 W202만 끄고 나머지 경고는 오류로 유지한다.
• [백엔드 복귀 시 유효] fixture는 DOS 8.3 이름으로 실행한다. 긴 이름은 registry에서 명시적으로 줄인다.
• [백엔드 복귀 시 유효] R:은 읽기 전용 저장소, W:은 읽기 전용 Watcom이다. 빌드 산출물은 반드시 임시 C:\FEC에 쓴다.
• [백엔드 복귀 시 유효] 실패 분석에는 임시 작업공간 보존이 필요하다. 그 플래그는 런처와 함께 사라졌으므로 다시 만들어야 한다.

작업 흐름

• 명세 판단이 바뀌면 SPEC.md를 즉시 갱신한다. 구현이 명세와 다르면 둘 중 하나가 틀린 것이므로 그 자리에서 결론을 낸다.
• 코드는 컴파일러 단계로 나눈다. 마일스톤 단위 분할은 폐기했다.
• 검증된 단위마다 커밋한다. 푸시는 요청받았을 때만 한다.
• primary 브랜치는 master다.
• .dosboxx/의 다운로드, 실행 작업공간, 로그는 커밋하지 않는다.

현재 상태

uv run python tests/run.py 의 통과 수가 현재 상태다. 남은 작업은 TODO.md에 있다.