doslang-mirror/AGENTS.md

# doslang 작업 규칙

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

## 문서 지도

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

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

```powershell
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`에 있다.