문서 및 ADR
Archyl은 아키텍처 다이어그램과 함께 풍부하고 연결된 문서를 만들 수 있는 강력한 문서화 기능을 제공합니다. 아키텍처 지식을 체계적으로 정리하고 연결하세요.
문서 작성
수동 문서 작성
문서를 수동으로 작성하려면:
- 프로젝트에서 문서 탭으로 이동합니다
- 새 문서를 클릭합니다
- 제목을 입력하고 Markdown으로 내용을 작성합니다
- 정리를 위해 태그를 추가합니다
- 저장을 클릭합니다
문서는 다음을 포함한 전체 Markdown 구문을 지원합니다:
- 제목 및 서식
- 구문 강조가 포함된 코드 블록
- 표 및 목록
- 이미지 및 링크
Git에서 가져오기
Git 리포지토리에서 기존 문서를 가져올 수 있습니다:
- 프로젝트 설정 > 문서 탐색으로 이동합니다
- 리포지토리 연결을 구성합니다
- 문서 탐색을 클릭합니다
- 발견된 문서를 검토하고 승인합니다
기존 README 파일, 기술 사양 또는 위키 콘텐츠를 가져오기에 적합합니다.
아키텍처 요소에 연결
문서는 아키텍처에 연결될 때 더 강력해집니다:
링크 만들기
- 문서 페이지를 엽니다
- 요소에 연결을 클릭합니다
- 아키텍처 요소를 검색하거나 탐색합니다
- 연결할 요소를 선택합니다
- 완료를 클릭합니다
연결된 문서 보기
다이어그램에서 요소를 볼 때 연결된 문서가 세부 패널에 나타납니다. 다이어그램 뷰를 떠나지 않고도 즉각적인 맥락을 제공합니다.
연결 활용 사례
- API 문서를 서비스 컨테이너에 연결
- 설치 가이드를 인프라 컴포넌트에 연결
- 설계 사양을 시스템 컨텍스트에 연결
- 코드 주석을 코드 요소에 연결
아키텍처 결정 기록 (ADR)
ADR은 중요한 아키텍처 결정을 그 맥락과 결과와 함께 문서화합니다.
ADR이란?
아키텍처 결정 기록은 다음을 포착합니다:
| 필드 | 설명 |
|---|---|
| 제목 | 무엇이 결정되었는지 |
| 상태 | 제안됨, 수락됨, 폐기됨 또는 대체됨 |
| 맥락 | 이 결정이 필요한 이유 |
| 결정 | 무엇이 결정되었는지 |
| 결과 | 결정의 영향 |
ADR 생성
- 프로젝트에서 결정 탭으로 이동합니다
- 새 ADR을 클릭합니다
- ADR 필드를 채웁니다
- 관련 아키텍처 요소에 연결합니다
- 저장을 클릭합니다
ADR 워크플로우
ADR은 생명주기를 따릅니다:
- 제안됨: 초기 초안, 논의 중
- 수락됨: 결정이 내려지고 승인됨
- 폐기됨: 더 이상 관련 없지만 기록을 위해 보존
- 대체됨: 새로운 결정으로 대체됨
ADR 탐색
문서와 마찬가지로 ADR도 리포지토리에서 발견할 수 있습니다:
- 프로젝트 설정 > ADR 탐색으로 이동합니다
- ADR 경로를 구성합니다 (예:
docs/adr/) - ADR 탐색을 클릭합니다
- 발견된 기록을 검토하고 승인합니다
모범 사례
문서를 최신 상태로 유지
- 아키텍처 변경 시 문서 업데이트
- 스프린트 회고 시 문서 검토
- 중요한 결정에 ADR 사용
모든 것을 연결
- 모든 시스템에 설명 문서가 있어야 함
- ADR을 영향받는 컴포넌트에 연결
- 관련 문서를 상호 참조
태그를 효과적으로 사용
- 도메인별 태그 (인증, 결제 등)
- 유형별 태그 (API, 가이드, 사양)
- 상태별 태그 (초안, 검토, 최종)
ADR 가이드라인
- 중요한 결정에 대해 ADR 작성
- 고려된 대안 포함
- 장단점 문서화
- 가능하면 구현 PR에 연결
문서 탐색 설정
문서 탐색 방법을 구성합니다:
경로 패턴
스캔할 경로를 지정합니다:
docs/
wiki/
README.md
*.md
제외 패턴
특정 파일을 건너뜁니다:
node_modules/
vendor/
CHANGELOG.md