개발 환경

본 문서는 프로젝트 구성 파일의 역할과 실행 명령을 정의합니다. 각 규칙의 근거는 해당 참조 문서가 원본이며, 본 문서는 그 규칙이 어디에서 강제되는지를 연결합니다.

1. 구성 파일

설정값을 문서에 옮겨 적지 않습니다. 두 벌이 되면 한쪽이 낡습니다. 문서는 규칙과 근거를 담고, 설정 파일이 그 규칙의 실행 형태를 담습니다.

2. 경로 별칭

// tsconfig.json
{ "compilerOptions": { "paths": { "@/*": ["./src/*"] } } }

baseUrl은 지정하지 않습니다. TypeScript 6에서 폐기 예정으로 표시되어 TS5101 오류로 빌드가 실패합니다. 규칙의 원본은 패키지 배치와 참조 규칙 7.3절입니다.

계층 간 임포트에 상대 경로를 쓰는 것은 ESLint no-restricted-imports가 차단합니다. Steiger는 상대 경로로 작성된 위반도 검출하므로 별칭 규칙의 근거는 검출 가능성이 아니라 파일 이동 내성입니다. 슬라이스를 옮길 때 상대 경로는 전부 깨지지만 별칭은 유지됩니다.

3. 줄바꿈 정책

모든 텍스트 파일은 저장소와 체크아웃 양쪽에서 LF를 사용합니다. .gitattributes의 * text=auto eol=lf 선언이 개인의 core.autocrlf 설정보다 우선합니다.

선언하지 않으면 Windows 환경에서 체크아웃 시 CRLF로 변환되어 커밋마다 경고가 발생하고, 협업 시 줄바꿈만 다른 차이가 생깁니다.

4. 디렉터리 골격

src/
├── app/
├── pages/
├── shared/
├── main.ts
├── main.server.ts
├── server.ts
└── index.html

app은 FSD app 계층이자 Angular 루트이며 전역 스타일을 포함합니다. pages는 라우트 단위 화면, shared는 비즈니스 로직이 없는 인프라입니다. 나머지 네 파일은 프레임워크 진입점이며 계층 밖입니다.

features와 entities는 재사용이 확인된 시점에 생성합니다. 빈 폴더를 미리 만들지 않습니다.

전역 스타일은 src/app/styles.css이며 angular.json의 styles 항목이 이 경로를 가리킵니다. Angular CLI 기본값인 src/styles.css에서 이동한 것으로, FSD가 전역 스타일을 app 계층에 두도록 정하고 있기 때문입니다.

5. 명령

npm run check를 통과하지 않은 상태로 병합하지 않습니다. CI는 이 명령 하나만 실행하면 됩니다.

docs:build는 prestart·prebuild·prelint·pretest가 자동으로 앞세우므로 직접 실행할 일은 드뭅니다. 생성물은 src/shared/markdown/generated/에 놓이며 커밋하지 않습니다. OpenAPI 생성 타입을 커밋하는 이유가 계약 변경을 PR 차이에 드러내는 것인데, 문서 HTML 은 원본 마크다운이 같은 저장소에 있어 그 근거가 적용되지 않습니다. 마크다운 차이를 보면 충분합니다.

5.1 문서의 위치와 주소

문서의 계층은 폴더 구조가 원본입니다. 프론트매터에 적지 않습니다. 두 벌이 되면 한쪽이 낡습니다.

docs/
├── architectures/
│   ├── index.md                        영역 개요
│   ├── <domain>/<stack>/index.md       스택 개요
│   └── <domain>/<stack>/<group>/*.md   스택의 문서
└── posts/
    └── <slug>/
        ├── index.md                    글
        └── assets/                     그 글의 이미지

domain은 frontend·backend, group은 references·decisions입니다. 목록에 없는 이름을 쓰면 docs:build가 실패합니다.

주소는 /architectures/<stack>/<slug> 와 /posts/<slug> 로 조립합니다. domain과 group은 주소에 넣지 않습니다. 스택 이름이 이미 유일하고 계층은 사이드바가 보여주므로, 주소에까지 넣으면 길기만 합니다.

글은 폴더 하나가 글 하나입니다. 이미지를 본문 옆에 두어 자산이 문서와 함께 움직입니다. assets/는 문서 수집 대상이 아니므로 그 안에 마크다운을 넣어도 사이트에 나타나지 않습니다. 글의 슬러그는 폴더명이며 프론트매터에 적지 않습니다.

5.2 글의 프론트매터

글은 표준 문서보다 요구하는 값이 많습니다. 목록 카드가 날짜와 표지를 함께 그리기 때문입니다.

5.3 이미지

docs:build가 sharp로 폭별 이미지를 만들어 public/posts/에 놓고 srcset을 심습니다. 생성물은 커밋하지 않습니다. 원본이 docs/posts/에 있어 문서 HTML과 같은 근거가 적용됩니다.

본 저장소 기준으로 원본 3.9MB가 생성물 0.1MB가 됩니다.

외부 주소를 참조하는 이미지는 변환하지 않고 그대로 둡니다. 크기를 알 수 없어 자리를 예약하지 못하므로, 그 이미지가 도착할 때 본문이 밀립니다.

5.4 프론트매터와 본문의 역할

문서마다 slug·title·description을 필수로 둡니다. 누락되면 docs:build가 실패합니다. slug는 주소의 마지막 조각이며 파일명이 한글이어도 주소가 ASCII로 유지되게 하는 수단입니다.

제목을 누가 소유하는지가 영역마다 다릅니다.

표준 문서에서는 프론트매터의 값을 화면에 다시 표시하지 않습니다. 본문이 이미 제목을 갖고 있어 두 값이 같으면 같은 문장이 두 번 보입니다. 두 값이 반드시 같아야 하는 것도 아닙니다. ADR 은 목록용 title이 짧고 본문 제목이 결정 내용을 담은 긴 문장이며, 이 차이는 의도된 것입니다.

글은 반대입니다. 표지와 날짜, 태그가 프론트매터에만 있어 본문이 그것을 담을 수 없습니다. 제목만 본문에 두면 표지와 날짜는 화면이 그리고 제목은 본문이 그리게 되어 헤더가 두 곳으로 갈립니다.

5.5 강조 블록

규칙이 영역마다 다릅니다. 규격을 정의하는 문서와 생각을 풀어 쓰는 글은 강조의 성격이 다릅니다.

표준 문서에서 쓰는 둘의 조건은 다음과 같습니다.

표준 문서에서 [!NOTE]·[!TIP]·[!CAUTION] 을 쓰는 것을 금지합니다. 근거 설명과 환경별 예외는 본문 문장이나 표의 열로 흡수합니다. 종류를 늘리면 강조의 희소성이 사라져 정작 치명적인 경고가 묻힙니다.

빌드나 린터가 즉시 차단하는 규칙은 블록으로 두지 않습니다. 위반하면 그 자리에서 실패하므로 놓칠 수 없습니다. 블록은 조용히 실패하는 것을 위한 자리입니다. 지연 청크가 만들어지지 않거나, 스크롤 위치 복원이 동작하지 않거나, 하이드레이션이 어긋나는 경우처럼 오류 없이 결과만 달라지는 항목이 대상입니다.

블록 내부는 굵은 소제목 한 줄을 먼저 두고 빈 인용 줄로 본문과 나눕니다.

> [!WARNING]
> **한 줄로 끝나는 소제목**
>
> 본문을 서술합니다.

한 절(##)에 하나를 원칙으로 합니다. 두 개를 넘기면 그 절의 구성을 재검토합니다.

5.6 디렉터리 구조 표기

계층은 tree 기호(├──·└──·│)로 표기합니다. 들여쓰기 폭에 의존하지 않아 계층 관계가 기호로 확정됩니다.

코드 블록 안에서 공백으로 열을 맞추는 것을 금지합니다. 본문 글꼴이 한글을 담지 않아 한글만 다른 글꼴로 떨어지며, 그 폭이 고정폭의 배수와 맞지 않아 정렬이 어긋납니다. 원본 마크다운에서만 가지런하고 화면에서는 깨집니다. 근거는 ADR-0014에 있습니다.

항목 설명은 블록 밖에 둡니다. 셋 이상이면 표로, 둘 이하면 본문 문장으로 서술합니다.

shared/auth/
├── session.ts
├── auth-interceptor.ts
└── index.ts

5.7 문서 간 링크

저장소 안을 가리키는 링크는 문서 파일(.md)만 대상으로 합니다. docs:build가 대상 문서를 찾아 사이트 경로로 바꾸며, 찾지 못하면 실패합니다. 사이트 경로는 파일 위치에서 유도하므로 문서에 직접 적지 않습니다.

디렉터리에 링크를 거는 것을 금지합니다. 마크다운 원본에서는 동작하지만 사이트에는 그 경로가 없어 404가 됩니다. 양쪽에서 동시에 성립하지 않는 표기이므로 references/처럼 코드 표기로 언급만 합니다.

5.8 절 참조

절을 가리킬 때는 3.1절 형태로 씁니다. §3.1은 법률·학술 문서의 표기이며 한국어 기술 문서에서는 쓰지 않습니다.

링크를 손으로 만들지 않습니다. docs:build가 절 번호를 해당 절의 앵커로 연결합니다. 세 가지 형태를 인식합니다.

번호에 해당하는 절이 없으면 빌드가 실패합니다. 코드 블록과 인라인 코드 안의 절 표기는 변환하지 않습니다.

다른 저장소의 문서를 절 번호로 가리키지 않습니다. 우리 문서에 그 앵커가 없어 검증할 수 없습니다. 절 이름으로 서술합니다.

6. 강제 수단의 적용 범위

문서에 적힌 규칙 중 어느 것이 자동으로 차단되고 어느 것이 코드 리뷰에 남는지는 아키텍처 11절이 원본입니다.

요약하면 계층 임포트 방향·공개 API·크로스임포트·조기 추출·번들 예산은 자동 차단되고, shared의 비즈니스 로직 금지·적응형 두 모드 테스트·정적 생성 경로의 적응형 컴포넌트 금지는 수동 확인 대상입니다.

7. 실측으로 확인한 사항

본 표준의 규칙 중 실제로 검증한 항목입니다.

8. 규칙의 예외

예외를 추가할 때는 완화한 규칙의 근거가 왜 그 대상에 적용되지 않는지를 함께 적습니다. 사유 없는 예외는 규칙을 무력화합니다.

9. 미확인 항목