[{"_1":2,"_2475":-5,"_2476":-5},"loaderData",{"_3":4,"_8":9,"_15":16},"root",{"_5":-5,"_6":7},"theme","locale","en","core/layouts/navigation.layout",{"_10":-5,"_11":-5,"_12":13},"user","profile","headers",["SingleFetchClassInstance",14],{},"features/shop/screens/projects",{"_17":18,"_19":20},"basePath","/shop/projects","projects",[21,498,813,981,1112,1511,1671,2247],{"_22":23,"_24":25,"_26":27,"_28":29,"_30":31,"_32":33,"_34":35,"_36":37,"_38":39,"_40":41,"_484":485},"id","71cc9870-393c-4f3e-9aa7-0e0da2870c85","title","CodeCraft : 대규모 C++ 프로젝트를 위한 코딩 표준 수립 및 자동화","price",199000,"option_type","basic","user_id","2e27b2b8-06cf-4074-8254-b0622de62946","project_id","8ab29730-8056-4438-995e-0d2643297827","created_at","2025-07-01T10:06:23.442Z","updated_at","2025-07-01T10:19:50.305Z","release",false,"project",{"_22":33,"_24":25,"_42":43,"_44":31,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":39,"_56":57,"_58":59,"_60":61,"_62":61,"_63":64,"_70":71,"_478":479},"description","주관적인 코드 리뷰 논쟁으로 시간을 낭비하는 대신, 신뢰할 수 있는 C++ 코드를 만들어나가세요. 이 프로젝트는 명확한 원칙과 언어별 가이드라인을 수립하고, CI를 통해 이를 자동으로 적용하여 C++ 개발을 위한 포괄적인 지식 베이스를 제공합니다. 단순한 스타일 가이드가 아닌, 엔지니어링 품질을 한 단계 끌어올리고 팀의 협업을 강화하는 완전한 시스템입니다.\"","author_id","author_name","captain.dev__","experiences","저를 무너뜨렸던 코드 리뷰가 기억납니다. 중요한 기능에 대해 중괄호 위치와 변수명 같은 사소한 문제로 두 시간 동안 논쟁을 벌였습니다. 로직은 완벽했지만, 논의는 완전히 *개인의 취향* 문제로 번졌습니다. 팀 전체의 에너지와 사기를 꺾는 엄청난 낭비였죠. 그 순간 깨달았습니다. 아무도 읽지 않는 낡은 위키 페이지에 불과했던 우리의 '스타일 가이드'가 근본적으로 잘못되었다는 것을요.\r\n\r\n> 그때 얻은 깨달음은 단순하지만 깊었습니다. **코딩 표준은 권장 사항이 아니라, 아키텍처의 일부입니다.** 컴파일러 오류처럼 강제적이고 타협할 수 없는 것이어야 합니다.\r\n\r\n그래서 저는 이 프로젝트를 또 하나의 문서가 아닌, 살아있는 시스템으로 구축하기 시작했습니다. 먼저 규칙 뒤에 숨은 *이유*, 즉 기본 원칙부터 시작했습니다. 그다음, 그 원칙들을 C++, 셸, 심지어 Markdown 문서에 대한 구체적이고 언어별 가이드라인으로 옮겼습니다. 마지막 핵심 단계는 그 규칙들을 린터와 포맷터로 코드화하고, 이 모든 것을 CI 파이프라인에 연결하는 것이었습니다. 목표는 올바른 일을 하는 것이 *가장 쉬운* 일이 되도록 만드는 것이었습니다.\r\n\r\n결과는 어땠을까요? 이제 우리의 코드 리뷰는 본질에 집중합니다. 누가 작성했든 코드베이스는 일관되고 전문적인 느낌을 줍니다. 표준이 명확하고 자동으로 적용되니 온보딩도 빨라졌습니다. 우리는 의견 기반의 논쟁을 자동화된 객관적인 피드백으로 대체했고, 더 나은 코드를 더 빠르게 출시하고 있습니다. 이 시스템은 여러분에게도 똑같은 힘을 실어줄 것입니다.\"","overview","# 프로젝트 명세서: readable-code-cpp-development-guidelines\r\n\r\n## 1. 프로젝트 정의\r\n\r\n### 1.1. 주요 목표\r\n\r\n- 가독성 높은 C++ 코드 작성을 위한 개발 가이드라인, 원칙, 컨벤션을 정의하는 체계적인 지식 베이스 구축.\r\n\r\n### 1.2. 핵심 기능\r\n\r\n- 개발, 설계, 아키텍처를 위한 정형화된 소프트웨어 엔지니어링 원칙.\r\n- C++, Shell, Markdown, CMake를 위한 언어별 코딩 스타일 가이드라인.\r\n- 린터 및 CI 파이프라인을 통한 코드 스타일 및 포맷팅 자동 강제.\r\n- 일반적인 소프트웨어 엔지니어링 문서를 위한 표준화된 템플릿.\r\n\r\n### 1.3. 결과물\r\n\r\n- 문서화된, 언어에 구애받지 않는 개발 원칙 저장소.\r\n- 언어별 코딩 스타일 가이드 모음.\r\n- 포맷터 설정, CI 워크플로, 설치 스크립트를 포함한 자동화 도구.\r\n- 일관된 문서 작성을 위한 재사용 가능한 Markdown 템플릿 모음.\r\n\r\n## 2. 시스템 아키텍처\r\n\r\n### 2.1. 아키텍처 패턴\r\n\r\n- 구조화된 문서 저장소: 소스 코드처럼 계층적으로 구성되고 버전 관리되는 문서를 핵심 자산으로 삼는 아키텍처. 프로젝트 지식을 하나의 결과물로 취급하며, 자동화를 통해 일관성을 강제합니다.\r\n\r\n### 2.2. 의존성 다이어그램\r\n\r\n- 에픽(epic) 간의 의존성을 시각화한 다이어그램. 기반 작업(원칙, 템플릿)이 특정 가이드라인을 뒷받침하고, 이는 다시 자동화 및 CI 검증을 통해 지원됩니다.\r\n\r\n```mermaid\r\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\r\nflowchart TD\r\n subgraph \"기반\"\r\n FoundationalPrinciples[\"1\\. 개발 기반 원칙
수립\"]\r\n DocTemplates[\"2\\. 표준 문서
템플릿 생성\"]\r\n end\r\n\r\n subgraph \"도구 및 자동화\"\r\n ConfigureFormatters[\"3\\. 코드 및 Markdown
포맷터 구성\"]\r\n InstallScripts[\"4\\. 로컬 포맷터
설치 스크립트 구현\"]\r\n LocalExecScript[\"10\\. 로컬 포맷터
실행 스크립트 구현\"]\r\n end\r\n\r\n subgraph \"세부 가이드라인\"\r\n ShellCMakeGuides[\"5\\. Shell 및 CMake
코딩 스타일 가이드 개발\"]\r\n MarkdownMermaidGuides[\"6\\. Markdown 및 Mermaid
스타일 가이드 개발\"]\r\n CppGuidelines[\"7\\. C++ 코딩 및
포맷팅 가이드라인 개발\"]\r\n CppTestingDoxygenGuides[\"8\\. C++ 테스팅 및
Doxygen 가이드라인 개발\"]\r\n end\r\n\r\n subgraph \"검증\"\r\n CIPipeline[\"9\\. 자동화된 가이드라인 검증을
위한 CI 파이프라인 구현\"]\r\n end\r\n\r\n FoundationalPrinciples --> ConfigureFormatters\r\n ConfigureFormatters --> InstallScripts\r\n InstallScripts --> LocalExecScript\r\n\r\n FoundationalPrinciples --> ShellCMakeGuides\r\n DocTemplates --> ShellCMakeGuides\r\n\r\n FoundationalPrinciples --> MarkdownMermaidGuides\r\n DocTemplates --> MarkdownMermaidGuides\r\n ConfigureFormatters --> MarkdownMermaidGuides\r\n\r\n FoundationalPrinciples --> CppGuidelines\r\n DocTemplates --> CppGuidelines\r\n ConfigureFormatters --> CppGuidelines\r\n\r\n CppGuidelines --> CppTestingDoxygenGuides\r\n\r\n MarkdownMermaidGuides --> CIPipeline\r\n CIPipeline --> LocalExecScript\r\n```\r\n\r\n### 2.3. 프로그램 흐름\r\n\r\n- 지식 베이스의 작성부터 자동 검증까지, 사용자와 시스템의 주요 상호작용을 보여주는 시퀀스 다이어그램.\r\n > **참고**: 이 흐름은 가이드라인 자체의 개발 및 유지보수 생명주기를 나타냅니다.\r\n\r\n```mermaid\r\n%%{ init: { \"sequence\": { \"htmlLabels\": true } } }%%\r\nsequenceDiagram\r\n participant Dev as \"개발자\"\r\n participant KB as \"지식 베이스
(저장소)\"\r\n participant LocalTools as \"로컬 자동화
(스크립트)\"\r\n participant CI as \"CI 파이프라인
(GitHub Actions)\"\r\n\r\n Dev->>KB: \"원칙 및 가이드라인 참고\"\r\n Dev->>Dev: \"문서/코드 작성
또는 수정\"\r\n Dev->>LocalTools: \"'run_formatters.sh' 실행\"\r\n LocalTools-->>Dev: \"포맷팅 적용 및 상태 보고\"\r\n Dev->>KB: \"변경사항 커밋 및 푸시\"\r\n KB->>CI: \"CI 워크플로 트리거\"\r\n CI->>CI: \"린터 실행 (Prettier, markdownlint)\"\r\n CI-->>KB: \"검증 상태 보고 (성공/실패)\"\r\n```\r\n\r\n### 2.4. 컴포넌트별 역할 및 책임\r\n\r\n- **엔지니어링 원칙**\r\n - **역할** 개발, 설계, 네이밍에 대한 근본적이고 언어에 구애받지 않는 규칙을 정의합니다.\r\n - **상호작용** 모든 `언어 가이드라인`과 `자동화 도구` 설정의 개념적 기반 역할을 합니다.\r\n- **언어 가이드라인**\r\n - **역할** 각 기술(C++, Shell 등)에 대한 구체적인 코딩 스타일, 포맷팅, 테스팅 규칙을 제공합니다.\r\n - **상호작용** `문서 템플릿`을 구조로 사용하여 추상적인 `엔지니어링 원칙`을 특정 언어에 맞게 구현합니다. `자동화 도구`에 의해 검증됩니다.\r\n- **자동화 도구**\r\n - **역할** 표준을 강제하기 위한 스크립트, 포맷터 설정(`.prettierrc`, `.clang-format`), CI 워크플로를 포함합니다.\r\n - **상호작용** `엔지니어링 원칙`과 `언어 가이드라인`에 정의된 규칙을 코드화하고 자동으로 강제합니다.\r\n- **문서 템플릿**\r\n - **역할** 일관성 있는 프로젝트 문서 작성을 위한 표준화된 Markdown 템플릿을 제공합니다.\r\n - **상호작용** 모든 `언어 가이드라인` 및 기타 공식 문서를 작성하는 청사진으로 사용되어 통일된 구조를 보장합니다.\r\n\r\n### 2.5. 기술 스택\r\n\r\n- **언어:**\r\n - Markdown\r\n - Shell Script\r\n - YAML\r\n - JSON\r\n - C++\r\n- **프레임워크:**\r\n - GitHub Actions\r\n - Prettier\r\n - markdownlint\r\n - clang-format\r\n - Doxygen\r\n - Homebrew\r\n\r\n## 3. 디렉터리 구조\r\n\r\n### 3.1. 개요\r\n\r\n- 명확성과 확장성을 위해 상위 수준의 원칙, 언어별 가이드라인, 자동화 스크립트, 재사용 가능한 템플릿을 분리한 모듈식 구조.\r\n\r\n### 3.2. 폴더 트리\r\n\r\n```bash\r\n/\r\n├── .github/\r\n│ └── workflows/ # 자동화된 검증을 위한 CI 파이프라인 설정을 정의합니다.\r\n├── guidelines/ # 언어별 코딩 스타일 및 포맷팅 컨벤션을 포함합니다.\r\n├── principles/ # 상위 수준의 소프트웨어 엔지니어링 원칙을 정의하는 Markdown 문서를 포함합니다.\r\n├── scripts/ # 포맷터 설치 및 실행을 위한 자동화 스크립트를 포함합니다.\r\n└── templates/ # 프로젝트 문서를 위한 표준화된 Markdown 템플릿을 포함합니다.\r\n```\r\n\r\n## 4. 실행 계획\r\n\r\n프로젝트는 견고한 기반을 다진 후 완전한 자동화를 향해 단계적으로 실행됩니다. 먼저 보편적인 엔지니어링 원칙과 문서 템플릿을 수립하는 것으로 시작합니다. 이 기반 위에 자동화된 포맷터를 구성하고, 특정 언어 가이드라인을 개발합니다. 마지막으로, 로컬 스크립트와 CI 파이프라인을 구현하여 이러한 가이드라인을 자동으로 강제함으로써 장기적인 일관성과 품질을 보장합니다.\r\n\r\n---\r\n\r\n### 에픽 1: 개발 기반 원칙 수립\r\n\r\n- **목표:** 모든 가이드라인의 개념적 기반이 되는, 언어에 구애받지 않는 완전한 소프트웨어 엔지니어링 원칙 세트를 정의합니다.\r\n- **작업**\r\n - **1.1 핵심 철학 원칙 문서:** 가독성 및 일관성과 같은 프로젝트의 핵심 철학적 가치를 상세히 설명하는 문서 작성.\r\n - **1.2 개발 프로세스 원칙 문서:** 개발 워크플로와 표준 관행을 규정하는 문서 작성.\r\n - **1.3 네이밍 및 포맷팅 원칙 문서:** 명확한 네이밍과 일관된 포맷팅을 위한 언어 독립적 원칙 정의.\r\n - **1.4 설계 원칙 문서:** 견고하고 유지보수 가능하며 잘 구조화된 소프트웨어 설계를 위한 문서 작성.\r\n - **1.5 의존성 및 구조 원칙 문서:** 코드 의존성 및 프로젝트 구조 관리를 위한 가이드라인 정형화.\r\n - **1.6 원칙 색인 문서:** 모든 원칙 문서를 색인하고 연결하는 중앙 README 파일 작성.\r\n\r\n### 에픽 2: 표준 문서 템플릿 생성\r\n\r\n- **목표:** 일관성을 보장하기 위해, 공통 프로젝트 산출물을 위한 표준화되고 재사용 가능한 Markdown 템플릿 모음을 개발합니다.\r\n- **작업**\r\n - **2.1 표준 Markdown 템플릿 모음:** README, 스타일 가이드, 설계 문서를 위한 재사용 가능한 템플릿 전체 세트 개발.\r\n\r\n### 에픽 3: 코드 및 Markdown 포맷터 구성\r\n\r\n- **목표:** 기반 원칙에서 파생된 포맷팅 규칙을 코드화하기 위해 자동화된 포맷터(Prettier, markdownlint, clang-format)를 구성합니다.\r\n- **작업**\r\n - **3.1 Markdown 포맷터 및 린터 설정:** Markdown 스타일 규칙을 강제하기 위한 설정 파일(`.prettierrc`, `.markdownlint.jsonc`) 작성.\r\n - **3.2 C++ 포맷터 설정:** C++ 코딩 스타일을 자동으로 강제하기 위한 `.clang-format` 파일 설정.\r\n\r\n### 에픽 4: 로컬 포맷터 설치 스크립트 구현\r\n\r\n- **목표:** 필요한 포맷팅 및 린팅 도구 설치를 자동화하기 위해 플랫폼별(macOS, Ubuntu) 셸 스크립트를 개발합니다.\r\n- **작업**\r\n - **4.1 macOS 포맷터 설치 스크립트:** Homebrew를 사용하여 macOS에서 포맷터 설치를 자동화하는 셸 스크립트 개발.\r\n - **4.2 Ubuntu 포맷터 설치 스크립트:** apt 및 npm을 사용하여 Ubuntu에서 포맷터 설치를 자동화하는 셸 스크립트 개발.\r\n\r\n### 에픽 5: Shell 및 CMake 코딩 스타일 가이드 개발\r\n\r\n- **목표:** 기반 원칙을 적용하여 Shell 및 CMake 스크립트를 위한 구체적인 코딩 스타일 및 모범 사례 가이드라인을 작성합니다.\r\n- **작업**\r\n - **5.1 Shell 스크립트 코딩 스타일 가이드:** 셸 스크립트의 코딩 표준과 모범 사례를 정의하는 포괄적인 문서 작성.\r\n - **5.2 CMake 코딩 스타일 가이드:** 모던하고 타겟 중심적인 CMake 스크립트 코딩 표준을 수립하는 가이드 작성.\r\n\r\n### 에픽 6: Markdown 및 Mermaid 스타일 가이드 개발\r\n\r\n- **목표:** 자동화된 도구와 연계하여 일관된 Markdown 및 Mermaid 다이어그램 작성을 위한 포괄적인 스타일 가이드를 만듭니다.\r\n- **작업**\r\n - **6.1 Markdown 코딩 스타일 가이드:** Prettier 및 markdownlint로 강제되는 일관된 Markdown 작성을 위한 스타일 가이드 작성.\r\n - **6.2 Mermaid 다이어그램 스타일 가이드:** 명확하고 일관되며 오류 없는 Mermaid 다이어그램 작성을 위한 가이드 작성.\r\n\r\n### 에픽 7: C++ 코딩 및 포맷팅 가이드라인 개발\r\n\r\n- **목표:** 원칙 및 `.clang-format` 설정을 참조하여 C++의 핵심 코딩 스타일, 네이밍, 포맷팅 규칙을 수립합니다.\r\n- **작업**\r\n - **7.1 C++ 핵심 코딩 스타일 가이드:** 헤더, 스코프, 클래스, 함수를 다루는 포괄적인 C++ 스타일 가이드 작성.\r\n - **7.2 C++ 네이밍 및 포맷팅 가이드:** 모든 네이밍 컨벤션을 코드화하고 `.clang-format`의 포맷팅 규칙을 요약한 문서 작성.\r\n\r\n### 에픽 8: C++ 테스팅 및 Doxygen 가이드라인 개발\r\n\r\n- **목표:** 프로젝트의 C++ 테스팅 전략을 정의하고 Doxygen API 문서의 코딩 스타일을 명시합니다.\r\n- **작업**\r\n - **8.1 C++ 테스팅 계획 및 가이드라인:** 프로젝트의 C++ 테스팅 전략, 도구(Catch2, CTest), 품질 표준 정의.\r\n - **8.2 Doxygen 주석 스타일 가이드:** C++ 코드에서 Doxygen API 문서를 작성하기 위한 일관된 스타일 수립.\r\n - **8.3 Doxygen 설정 파라미터 가이드:** 주요 Doxygen 설정 파라미터 관리를 위한 참조 문서 작성.\r\n\r\n### 에픽 9: 자동화된 가이드라인 검증을 위한 CI 파이프라인 구현\r\n\r\n- **목표:** 정의된 포맷팅 표준에 따라 모든 Markdown 파일을 자동으로 검증하는 GitHub Actions 워크플로를 구성합니다.\r\n- **작업**\r\n - **9.1 Markdown 검증을 위한 CI 워크플로:** push 및 pull request 시 Markdown 파일 포맷팅을 자동으로 확인하는 GitHub Actions 워크플로 구현.\r\n\r\n### 에픽 10: 로컬 포맷터 실행 스크립트 구현\r\n\r\n- **목표:** 로컬 환경의 일관성을 보장하기 위해 프로젝트의 모든 Markdown 파일에 포맷터를 실행하는 마스터 셸 스크립트를 개발합니다.\r\n- **작업**\r\n - **10.1 Markdown 포맷터 실행을 위한 로컬 스크립트:** 모든 Markdown 파일의 포맷팅 및 린팅을 자동화하는 실행 스크립트 개발.\r\n","objectives","> 코딩 표준을 '권장 사항'에서 개발 라이프사이클의 '자동화된 필수 요소'로 바꾸세요.\n\n이 프로젝트는 C++와 관련 툴체인에 고품질 코딩 프랙티스를 적용하기 위해, 표준을 정의하고 문서화하며 강제하는 완전한 프레임워크를 제공합니다. 엔지니어링 표준을 버전 관리되고 테스트 가능한 코드로 취급하는 '구조화된 문서 저장소(Structured Documentation Repository)'라는 아키텍처 패턴을 기반으로 구축되었습니다. 이 시스템은 언어에 구애받지 않는 엔지니어링 원칙의 기초를 세우고, 이를 C++, CMake, Shell, 심지어 Markdown 문서에 대한 구체적인 가이드라인으로 구현함으로써 단순한 스타일 가이드를 뛰어넘습니다.\n\n핵심 목표는 모호함을 없애고, 코드 리뷰를 간소화하며, 개발자 온보딩을 가속화하는 단일 진실 공급원(single source of truth)을 만드는 것입니다. 자동화된 포맷터와 CI 검증을 통합하여 모든 커밋이 합의된 표준을 준수하도록 보장합니다. 이를 통해 팀은 구문 논쟁 대신 비즈니스 문제 해결에 집중할 수 있습니다.","result","### 제공 사항\n\n- 설계, 네이밍, 개발 프로세스를 다루는, 언어에 구애받지 않는 소프트웨어 엔지니어링 원칙의 완전한 저장소.\n- C++, CMake, 셸 스크립트, Doxygen, Markdown을 위한 상세하고 실행 가능한 스타일 가이드.\n- 스타일 규칙을 코드화하기 위해 미리 구성된, 프로덕션 환경에 바로 사용 가능한 `clang-format`, `Prettier`, `markdownlint` 설정 파일.\n- 모든 기여가 품질 표준을 충족하도록 보장하는 완전 자동화된 CI 검증을 위한 GitHub Actions 워크플로.\n- 일관성 있고 수준 높은 문서를 작성하기 위한 재사용 가능한 Markdown 템플릿 모음.\n\n### 기대 효과\n\n- 코드 리뷰에서 주관적이고 시간 소모적인 논쟁을 없애고, 논의의 초점을 로직과 아키텍처에 맞춥니다.\n- 명확하고 강제성 있는 표준을 제공하여 신규 개발자의 온보딩 시간을 획기적으로 단축합니다.\n- 코드 포맷팅과 스타일 검사 등 수작업을 자동화하여 개발 속도를 향상시킵니다.\n- 회복력 있고 예측 가능한 코드베이스를 구축하여 장기적인 코드 건전성과 유지보수성을 개선합니다.\n- 품질이 자동화된 공동의 책임이 되는 탁월한 엔지니어링 문화를 조성합니다.","completed","updatedAt","2025-07-01T10:19:50.165Z","purchaseCount",46,"rating",0,"ratingCount","recommendations",[65,66,67,68,69],"C++ 기술 리드: 성장하는 팀의 코드 품질과 일관성을 향상시켜야 하는 분","소프트웨어 아키텍트: 장기적인 시스템을 설계하며 처음부터 기술 부채를 최소화하고자 하는 분","DevOps 또는 플랫폼 엔지니어: 개발자 툴체인과 CI/CD 파이프라인을 구축하고 자동화하는 책임을 맡은 분","시니어 C++ 개발자: 일관성 없는 코드베이스에 지쳤으며, 조직 내에서 최고의 프랙티스를 주도하고 싶은 분","엔지니어링 매니저: 팀의 개발 속도를 높이고 개발 과정의 마찰을 줄이는 데 집중하는 분","tasks",[72,100,117,134,151,168,184,204,222,240,258,276,294,312,330,348,366,384,402,420,438,458],{"_22":73,"_24":74,"_75":76,"_77":78,"_79":80,"_51":98,"_42":99},"task-1751362967700","핵심 철학 원칙 문서","content","# 작업: 핵심 철학 원칙 문서\n\n> **에픽**: 개발 기본 원칙 수립\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 프로젝트의 핵심 철학 원칙을 상세히 기술하는 마크다운 문서를 작성합니다.\n- **근거**: 이 작업은 전체 프로젝트의 기반을 다지는 단계입니다. 이러한 핵심 원칙을 문서로 공식화함으로써 프로젝트 가치에 대한 단일 진실 공급원(Single Source of Truth)을 확립합니다. 이를 통해 모든 후속 가이드라인, 코드, 아키텍처 결정이 가독성과 유지보수성에 중점을 둔 일관되고 공유된 철학에 뿌리를 내리도록 보장합니다. 이는 소프트웨어 엔지니어링 원칙을 공식화한다는 핵심 목표를 직접적으로 지원합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 가독성, 일관성, 인지 부하 최소화와 같은 기본 가치를 정의하는 문서 세트.\n- **명세**: 다음과 같은 새 파일이 생성됩니다:\n - `New file: principles/core-philosophy/readability-first.md`\n - `New file: principles/core-philosophy/minimize-review-debates.md`\n - `New file: principles/core-philosophy/reduce-cognitive-load.md`\n - `New file: principles/core-philosophy/explicit-is-better-than-implicit.md`\n - `New file: principles/core-philosophy/maintain-consistent-style.md`\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── principles/\n# └── core-philosophy/ <-- New\n# ├── explicit-is-better-than-implicit.md <-- New\n# ├── maintain-consistent-style.md <-- New\n# ├── minimize-review-debates.md <-- New\n# ├── readability-first.md <-- New\n# └── reduce-cognitive-load.md <-- New\n```\n\n- **프로세스 흐름도**\n 이 문서들은 개발 라이프사이클의 개념적 입력 자료로 사용됩니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"지식 베이스 (리포지토리)\"\n A[\"핵심 철학
문서 (이 작업)\"]\n end\n \n subgraph \"개발 라이프사이클\"\n B[\"개발자, 원칙
참조\"]\n C[\"개발자, 가이드라인
및 코드 작성\"]\n D[\"자동화 및 CI,
산출물 검증\"]\n end\n\n A --> B\n B --> C\n C --> D\n```\n\n### 1.3. 인수 기준\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트이며, 각 항목에 대한 상세 구현은 3절에 있습니다.\n\n- [ ] '가독성 우선' 원칙 문서.\n- [ ] '리뷰 논쟁 최소화' 원칙 문서.\n- [ ] '인지 부하 줄이기' 원칙 문서.\n- [ ] '암묵적인 것보다 명시적인 것이 좋다' 원칙 문서.\n- [ ] '일관된 스타일 유지' 원칙 문서.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 리포지토리\n- **관련 주요 구성 요소**:\n - **엔지니어링 원칙**: 이 구성 요소는 프로젝트의 근본적이고 언어에 구애받지 않는 규칙을 정의하는 역할을 합니다. 이 작업은 이 구성 요소를 위한 초기 핵심 산출물을 직접 생성하여, 다른 모든 원칙과 가이드라인이 구축될 철학적 기반을 마련합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `principles/core-philosophy/readability-first.md`\n- `principles/core-philosophy/minimize-review-debates.md`\n- `principles/core-philosophy/reduce-cognitive-load.md`\n- `principles/core-philosophy/explicit-is-better-than-implicit.md`\n- `principles/core-philosophy/maintain-consistent-style.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 기준**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공할 것입니다.\n\n---\n\n### 단계 1: '가독성 우선' 원칙 문서\n\n#### 1. '가독성 우선' 원칙 문서 생성하기\n\n이 작업은 전체 지식 베이스의 최우선 가치를 확립합니다: 코드는 다른 무엇보다도 사람이 이해하기 쉽게 최적화되어야 한다는 것입니다. 이 원칙은 모든 기술적 논쟁에서 최종적인 판단 기준이 되며, 명확한 표준과 자동화에 대한 프로젝트의 집중을 정당화합니다. 지정된 파일을 이 원칙을 정의하는 전체 내용으로 생성합니다.\n\n**파일**: `principles/core-philosophy/readability-first.md`\n\n```markdown\n# 원칙: 가독성 우선\n\n**태그**: 핵심 철학, 가독성, 최우선 순위\n\n---\n\n## 1. 핵심 정의\n\n> 코드는 성능이나 간결함 같은 다른 어떤 가치보다 사람이 이해하기 쉬워야\n> 합니다. 코드는 기계가 아닌 동료 개발자를 위해 작성됩니다.\n\n## 2. 근거 (왜?)\n\n소프트웨어의 전체 수명 주기 비용의 대부분은 유지보수 단계에서 발생하며, 코드는\n작성되는 것보다 훨씬 더 자주 읽힙니다. 가독성이 높은 코드는 버그를 찾기 쉽고,\n수정하기 쉬우며, 새로운 팀원이 시스템에 적응하는 시간을 단축시킵니다. 단기적인\n작성의 편리함이나 약간의 성능 향상을 위해 가독성을 희생하는 것은 장기적으로\n훨씬 더 큰 비용을 초래할 기술 부채를 쌓는 행위입니다.\n\n- _유지보수 비용을 절감하고 시스템의 수명을 연장합니다._\n- _코드의 의도를 명확히 하여 잠재적인 버그를 줄입니다._\n- _팀 협업 효율성과 지식 공유를 촉진합니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **설명적인 이름 사용**: 변수, 함수, 클래스의 이름은 그 역할과 의도를 명확하게\n 설명해야 합니다.\n- **로직 단순화**: 복잡한 표현식이나 긴 함수는 더 작고 이해하기 쉬운 부분으로\n 나눕니다.\n- **일관성 유지**: 프로젝트 전반에 걸쳐 일관된 코딩 스타일, 패턴, 구조를\n 유지하여 예측 가능성을 높입니다.\n\n### 금지 사항 (Don't)\n\n- **지나친 영리함 금지**: 잘 알려지지 않은 언어 기능이나 지나치게 영리한 코드\n 기법을 사용하여 동료를 혼란스럽게 만들지 않습니다.\n- **섣부른 최적화 금지**: 성능 병목 현상이 측정을 통해 입증되기 전까지는\n 가독성을 희생하면서 코드를 최적화하지 않습니다.\n- **주석으로 가독성 해결 금지**: 주석 없이는 이해할 수 없을 정도로 코드가\n 복잡하다면, 주석을 추가하기 전에 먼저 코드를 더 읽기 쉽게 리팩터링하는 것을\n 고려합니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 가독성이 매우 높은 코드\n\n```plaintext\nfunction getActiveUsers(users) {\n const activeUsers = [];\n for (const user of users) {\n if (user.isActive) {\n activeUsers.push(user);\n }\n }\n return activeUsers;\n}\n```\n\n### 나쁜 예시: 가독성을 해치는 간결함\n\n```plaintext\n// 기능적으로는 동일하지만, 코드가 무엇을 하는지 즉시 파악하기 어렵습니다.\n// 다른 사람이 이 코드를 이해하고 수정하는 데 더 많은 시간이 걸릴 것입니다.\nfunction getActiveUsers(users) {\n return users.filter(u => u.isActive);\n}\n\n// 위 예시는 언어에 따라 수용 가능할 수도 있지만, 아래와 같은 코드는 피해야 합니다.\nfunction getActiveUsers(users) {\n let result = [];\n users.forEach(u => u.isActive && result.push(u));\n return result;\n}\n```\n\n```\n\n---\n\n### 단계 2: '리뷰 논쟁 최소화' 원칙 문서\n\n#### 1. '리뷰 논쟁 최소화' 원칙 문서 생성하기\n\n이 작업은 주관적인 스타일 논쟁을 해결하기 위해 자동화를 사용하는 원칙을 문서화하여, 코드 리뷰를 더 효율적이고 객관적으로 만듭니다. 이는 포매터와 린터(에픽 3, 9) 구현의 근거를 제공하며, 이를 단순히 일관성을 위한 도구가 아니라 팀 협업을 개선하는 필수적인 도구로 규정합니다. 지정된 파일을 이 원칙을 정의하는 전체 내용으로 생성합니다.\n\n**파일**: `principles/core-philosophy/minimize-review-debates.md`\n\n```markdown\n# 원칙: 주관적인 리뷰 논쟁 최소화\n\n**태그**: 핵심 철학, 코드 리뷰, 협업\n\n---\n\n## 1. 핵심 정의\n\n> 명확하고 의무적인 가이드라인을 수립하고 자동화된 도구를 적극적으로 사용하여\n> 코드 스타일과 같은 주관적인 선호도에 대한 논쟁을 없앱니다.\n\n## 2. 근거 (왜?)\n\n코드 리뷰의 목적은 잠재적인 버그를 찾고, 설계의 약점을 개선하며, 지식을\n공유하는 것입니다. 하지만 명확한 가이드라인이 없으면 리뷰는 종종 \"어떤 방식이\n더 나은가?\"가 아닌 \"나는 이 스타일을 선호한다\"와 같은 비생산적인 개인 취향\n싸움으로 변질됩니다. 이러한 논쟁은 팀의 시간을 낭비하고, 개발자 간의 감정을\n상하게 하며, 더 중요한 로직 리뷰에 집중하지 못하게 만듭니다. 모든 주관적인\n요소를 규칙으로 정의하고 자동화함으로써, 리뷰는 객관적인 사실에 기반한 건설적인\n프로세스가 될 수 있습니다.\n\n- _코드 리뷰에서 소모적인 스타일 논쟁을 없애 시간을 절약합니다._\n- _리뷰가 설계나 로직과 같은 더 중요한 문제에 집중하도록 보장합니다._\n- _팀원 간의 불필요한 마찰을 줄여 긍정적인 협업 문화를 조성합니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **포괄적인 스타일 가이드 문서화**: 이름 규칙, 서식, 아키텍처 패턴을 포함한\n 모든 스타일에 대한 규칙을 명확하게 문서화합니다.\n- **자동화된 도구로 규칙 강제**: 코드 포매터와 린터를 사용하여 스타일 가이드를\n 자동으로 강제하고, 위반 시 CI 빌드가 실패하도록 구성합니다.\n- **리뷰는 '왜'에 집중**: 리뷰에서는 무언가가 '어떻게' 구현되었는지(스타일)가\n 아닌 '왜' 그렇게 구현되었는지(설계, 로직)를 묻고 논의합니다.\n\n### 금지 사항 (Don't)\n\n- **개인적인 선호도 강요 금지**: \"제가 보기엔 이 방식이 더 좋아 보이네요\"와\n 같은 주관적인 의견을 남기지 않습니다. 모든 피드백은 문서화된 가이드라인에\n 근거해야 합니다.\n- **자동화할 수 있는 것을 수동으로 지적 금지**: 린터나 포매터가 잡아낼 수 있는\n 문제를 사람이 코드 리뷰에서 지적하지 않습니다.\n- **규칙에 없는 것으로 논쟁 금지**: 가이드라인에 다뤄지지 않은 새로운 사례가\n 발생하면 논쟁을 멈추고, 팀 전체가 규칙을 정한 뒤 논의를 재개합니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 가이드라인에 기반한 객관적인 리뷰\n\n```plaintext\n// 리뷰어의 코멘트:\n// \"가이드라인 3.2항에 따라 API 호출 시 예외 처리를 위해 항상 try-catch 블록을 사용해야 합니다.\n// 여기에 try-catch를 추가해 주시겠어요?\"\n\n// 또 다른 좋은 예시:\n// \"이 함수의 로직이 복잡하네요. 어떤 엣지 케이스들을 고려하셨는지 설명해주실 수 있나요?\"\n```\n\n### 나쁜 예시: 개인적 선호도에 기반한 주관적인 리뷰\n\n```plaintext\n// 리뷰어의 코멘트:\n// \"저는 for-loop보다 forEach를 사용하는 것을 선호합니다. 이걸로 바꿔주세요.\"\n// (가이드라인에 관련 규칙이 없다면, 이것은 순전히 개인 취향의 문제입니다.)\n\n// 또 다른 나쁜 예시:\n// \"이 변수 이름이 마음에 안 드네요. 더 좋은 걸로 바꿔주세요.\"\n// (구체적인 대안이나 이유 없이 막연한 불평에 불과합니다.)\n```\n\n```\n\n---\n\n### 단계 3: '인지 부하 줄이기' 원칙 문서\n\n#### 1. '인지 부하 줄이기' 원칙 문서 생성하기\n\n이 작업은 개발자 생산성을 높이기 위해 의도적으로 기술적 선택을 제한하는 전략을 성문화합니다. 공통 문제에 대한 도구, 패턴, 해결책을 표준화함으로써, 프로젝트는 개발자를 \"결정 피로\"에서 해방시키고 비즈니스 로직에 집중할 수 있게 합니다. 이 원칙은 특정 기술 가이드라인과 템플릿의 생성을 정당화합니다. 지정된 파일을 이 원칙을 정의하는 전체 내용으로 생성합니다.\n\n**파일**: `principles/core-philosophy/reduce-cognitive-load.md`\n\n```markdown\n# 원칙: 선택지를 제한하여 인지 부하 줄이기\n\n**태그**: 핵심 철학, 생산성, 인지 부하\n\n---\n\n## 1. 핵심 정의\n\n> 동일한 문제를 해결하는 여러 방법이 있을 때, 프로젝트는 공식적으로 가장 좋은\n> 단 하나의 방법을 지정하고 개발자는 이를 따릅니다. 이는 개발자의 불필요한\n> 고민과 선택을 줄여 인지 부하를 낮춥니다.\n\n## 2. 근거 (왜?)\n\n개발자가 마주하는 모든 선택에는 인지적 비용이 따릅니다. '어떤 라이브러리를\n써야 할까?', '이 비동기 작업은 어떻게 처리해야 하지?', '에러 코드는 어떤 형식으로\n반환해야 하나?'와 같은 고민들은 쌓여서 중요한 비즈니스 로직 구현에 사용되어야\n할 정신적 에너지를 고갈시킵니다. 프로젝트 차원에서 기술 스택, 디자인 패턴, 코드\n구조에 대한 표준을 명확히 설정함으로써, 개발자들은 이러한 반복적인 고민에서\n해방되어 더 중요한 문제 해결에 집중할 수 있습니다. 이는 개인의 생산성을\n높일 뿐만 아니라 팀 전체의 기술적 통일성을 확보하여 유지보수 비용을 절감하는\n결과로 이어집니다.\n\n- _결정 피로를 줄여 개발자가 집중력을 유지하도록 돕습니다._\n- _프로젝트의 기술적 일관성을 보장하여 예측 가능성을 높입니다._\n- _프로젝트에 새로 합류하는 팀원의 학습 곡선을 완만하게 만듭니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **표준 라이브러리/프레임워크 지정**: 프로젝트에서 사용할 핵심 라이브러리와\n 프레임워크를 명확히 정의하고 대안 사용을 제한합니다.\n- **공통 문제에 대한 해결책 문서화**: 자주 발생하는 문제(예: 설정 관리, 로깅,\n 에러 처리)에 대한 표준화된 해결책이나 패턴을 '쿡북(Cookbook)' 형태로\n 제공합니다.\n- **재사용 가능한 컴포넌트 제공**: 여러 곳에서 사용될 수 있는 기능에 대해서는\n 잘 설계된 공통 컴포넌트나 모듈을 만들어, 개발자가 직접 구현할 필요 없이\n 가져다 쓸 수 있게 합니다.\n\n### 금지 사항 (Don't)\n\n- **무분별한 기술 도입 금지**: 새롭거나 흥미롭다는 이유만으로 충분한 검토 없이\n 새로운 라이브러리나 기술을 도입하지 않습니다.\n- **하나의 문제에 여러 해결책 허용 금지**: 프로젝트 내에 동일한 기능적 역할을\n 하는 여러 라이브러리(예: 여러 HTTP 클라이언트 라이브러리)나 패턴이\n 공존하도록 두지 않습니다.\n- **'최선'의 방법 탐색 강요 금지**: 특정 문제에 대해 '가장 이상적인' 해결책을\n 개별 개발자가 스스로 찾도록 요구하지 않고, '충분히 좋은' 표준 방법을\n 제시합니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 표준화된 방법만 사용하는 프로젝트\n\n```plaintext\n// 프로젝트 가이드라인: \"모든 비동기 API 요청은 'createApiRequest' 유틸리티 함수를 사용해야 합니다.\"\n\n// 개발자 A\ncreateApiRequest('/users/1').then(handleSuccess).catch(handleError);\n\n// 개발자 B\ncreateApiRequest('/products/123').then(handleSuccess).catch(handleError);\n\n// -> 누가 작성하든 코드가 동일한 구조를 가져 이해하고 유지보수하기 쉽습니다.\n// -> 개발자는 내부에 fetch가 쓰이는지 axios가 쓰이는지 고민할 필요가 없습니다.\n```\n\n### 나쁜 예시: 여러 방법이 혼재된 프로젝트\n\n```plaintext\n// 개발자 A는 fetch API를 직접 사용\nfetch('/users/1')\n .then(response => response.json())\n .then(data => console.log(data))\n .catch(error => console.error('Error:', error));\n\n// 개발자 B는 axios 라이브러리 사용\naxios.get('/products/123')\n .then(response => console.log(response.data))\n .catch(error => console.error('Error:', error));\n\n// -> 두 코드는 같은 작업을 하지만 구조와 에러 처리 방식이 완전히 다릅니다.\n// -> 프로젝트의 의존성이 불필요하게 늘어나고, 코드를 이해하는 데 더 많은 노력이 필요합니다.\n```\n\n```\n\n---\n\n### 단계 4: '암묵적인 것보다 명시적인 것이 좋다' 원칙 문서\n\n#### 1. '암묵적인 것보다 명시적인 것이 좋다' 원칙 문서 생성하기\n\n이 작업은 코드가 스스로를 설명해야 하며, 개발자가 의도를 추측하게 만드는 \"마법\"이나 숨겨진 동작을 피해야 한다는 규칙을 문서화합니다. 이 원칙은 의존성과 부작용을 명확하게 만들어 코드를 예측 가능하고 디버깅하기 쉽게 함으로써 가독성과 유지보수성에 직접적으로 기여합니다. 지정된 파일을 이 원칙을 정의하는 전체 내용으로 생성합니다.\n\n**파일**: `principles/core-philosophy/explicit-is-better-than-implicit.md`\n\n```markdown\n# 원칙: 독자가 코드의 의도를 추측하게 만들지 마라\n\n**태그**: 핵심 철학, 명시성, 가독성\n\n---\n\n## 1. 핵심 정의\n\n> 코드의 모든 로직과 동작은 이름, 매개변수, 구조를 통해 명확하게 드러나야\n> 합니다. 독자가 코드의 의도를 추측하게 만드는 숨겨진 기능(Magic)이나 암묵적인\n> 규칙에 의존해서는 안 됩니다.\n\n## 2. 근거 (왜?)\n\n코드는 동료 개발자와의 소통 수단입니다. 코드가 암묵적인 규칙이나 '마법적인'\n동작에 의존할 때, 독자는 그것을 이해하기 위해 더 많은 맥락을 머릿속에 담고\n있어야 합니다. 이는 상당한 인지 부하를 유발하고 코드를 오해할 가능성을 높여\n버그로 이어집니다. 모든 것이 명시적인 코드는 그 자체로 문서 역할을 하여,\n특별한 배경 지식 없이도 누구나 쉽게 이해하고 안전하게 수정할 수 있게 합니다.\n\n- _코드를 이해하는 데 필요한 사전 지식과 맥락을 최소화합니다._\n- _숨겨진 부작용으로 인한 버그 발생 가능성을 줄입니다._\n- _코드의 동작을 예측 가능하게 만들고 디버깅을 용이하게 합니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **함수 의존성 명시**: 함수가 사용하는 모든 외부 상태나 데이터는 매개변수를\n 통해 명시적으로 전달해야 합니다.\n- **명시적인 조건문 사용**: `if (user.isActive)`와 같이 불리언 값의 의미가\n 명확하도록 조건문을 작성합니다. `if (user.status == 1)`과 같은 매직 넘버\n 사용을 피합니다.\n- **설정 명시적으로 전달**: 전역 설정이나 환경 변수에 암묵적으로 의존하는 대신,\n 필요한 설정을 객체나 매개변수로 명시적으로 주입합니다.\n\n### 금지 사항 (Don't)\n\n- **매직 넘버/문자열 금지**: 코드에 하드코딩된 숫자나 문자열 대신 의미를 설명하는\n 이름 있는 상수를 사용합니다.\n- **숨겨진 부작용 금지**: 함수는 이름에 명시된 동작만 수행해야 합니다. 예를 들어,\n `getUser()` 함수가 내부에서 몰래 사용자의 마지막 로그인 시간을 갱신해서는 안\n 됩니다.\n- **암묵적 타입 변환 의존 금지**: 언어의 암묵적인 타입 변환 규칙에 의존하는\n 코드를 작성하지 않습니다. `if (count)`보다 `if (count != 0)`이 더 명확합니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 모든 것이 명시적인 경우\n\n```plaintext\nconst int MAX_LOGIN_ATTEMPTS = 5;\n\nfunction canLogin(user, loginAttempts) {\n const isAccountActive = user.status === 'ACTIVE';\n const hasLoginAttemptsLeft = loginAttempts < MAX_LOGIN_ATTEMPTS;\n\n return isAccountActive && hasLoginAttemptsLeft;\n}\n\n// 사용법\nif (canLogin(currentUser, userLoginCount)) {\n // ... 로그인 처리\n}\n```\n\n### 나쁜 예시: 암묵적인 규칙과 매직 넘버에 의존하는 경우\n\n```plaintext\n// 암묵적 규칙: user.status == 1은 활성 상태를 의미 (매직 넘버)\n// 로그인 시도 제한이 5라는 사실이 코드 안에 숨겨져 있음 (매직 넘버)\n// user 객체에 loginAttempts 속성이 있어야 한다는 사실이 숨겨져 있음 (암묵적 의존성)\nfunction canLogin(user) {\n return user.status == 1 && user.loginAttempts < 5;\n}\n\n// 사용법\nif (canLogin(currentUser)) { // currentUser는 반드시 status와 loginAttempts를 가져야 함\n // ... 로그인 처리\n}\n```\n\n```\n\n---\n\n### 단계 5: '일관된 스타일 유지' 원칙 문서\n\n#### 1. '일관된 스타일 유지' 원칙 문서 생성하기\n\n이 작업은 프로젝트 전체에 걸쳐 통일된 스타일을 요구하는, 타협할 수 없는 요구사항을 확립합니다. 일관성은 코드베이스를 예측 가능하게 만들어, 가독성과 인지 부하 감소 원칙을 직접적으로 지원합니다. 이 문서는 \"로마에 가면 로마법을 따르라\"는 규칙을 공식화하여, 프로젝트가 마치 한 명의 훈련된 저자에 의해 작성된 것처럼 느껴지도록 보장합니다. 지정된 파일을 이 원칙을 정의하는 전체 내용으로 생성합니다.\n\n**파일**: `principles/core-philosophy/maintain-consistent-style.md`\n\n```markdown\n# 원칙: 일관된 스타일 유지\n\n**태그**: 핵심 철학, 일관성, 가독성\n\n---\n\n## 1. 핵심 정의\n\n> 프로젝트 내의 모든 코드는 서식, 이름 짓기, 구조, 패턴 등 모든 면에서 일관된\n> 스타일을 유지해야 합니다. 이는 잘 쓰인 책 한 권이 일관된 어조와 용어, 편집\n> 스타일을 유지하는 것과 같습니다.\n\n## 2. 근거 (왜?)\n\n인간의 뇌는 패턴을 인식하고 예측하는 데 익숙합니다. 코드 스타일이 일관되면\n개발자는 코드의 구조를 더 빠르게 예측하고 파악할 수 있어, 불필요한 인지 부하를\n크게 줄여줍니다. 서로 다른 스타일이 섞인 코드를 읽는 것은 여러 사람이 각기 다른\n사투리로 쓴 글을 읽는 것과 같아서, 의미를 이해하는 데 더 많은 노력이 필요합니다.\n일관성은 코드를 예측 가능하게 만들고, 가독성을 높이며, 새로운 코드를 작성할 때\n따라야 할 명확한 청사진을 제공하여 유지보수 비용을 절감합니다.\n\n- _코드의 예측 가능성을 높여 독자가 더 빠르게 이해하도록 돕습니다._\n- _익숙한 패턴을 통해 개발자의 인지 부하를 줄여줍니다._\n- _프로젝트 전반의 통일성을 보장하여 장기적인 유지보수 비용을 낮춥니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **자동화된 도구 활용**: 코드 포매터와 린터를 사용하여 서식과 기본적인 규칙의\n 일관성을 강제합니다.\n- **기존 코드 존중**: 새로운 코드를 추가하거나 기존 코드를 수정할 때는 항상\n 주변 코드의 스타일과 패턴을 따릅니다.\n- **패턴 일관성 유지**: 특정 문제를 해결하기 위해 특정 디자인 패턴(예: 팩토리\n 패턴, 옵저버 패턴)이 선택되었다면, 프로젝트 내 모든 유사한 문제에 대해 동일한\n 패턴을 일관되게 적용합니다.\n\n### 금지 사항 (Don't)\n\n- **한 프로젝트에 여러 스타일 혼용 금지**: 한 파일에서는 `camelCase`를 쓰고 다른\n 파일에서는 `snake_case`를 쓰는 등 일관성을 해치는 행위를 피합니다.\n- **자신만의 스타일 고집 금지**: 팀에서 정한 규칙이나 프로젝트의 기존 스타일보다\n 개인적인 선호도를 우선시하지 않습니다.\n- **일관성을 깨는 예외를 자주 만들지 않기**: 매우 구체적이고 정당한 이유 없이\n 기존의 스타일이나 패턴을 깨는 예외적인 코드를 작성하지 않습니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 일관된 구조와 패턴을 따르는 코드\n\n```plaintext\n// 프로젝트 규칙: \"모든 이벤트 핸들러 함수명은 'handle'로 시작하고\n// 이벤트명을 뒤따른다. 예: handleUserClick, handleInputChange\"\n\nbutton.addEventListener('click', handleUserClick);\ninput.addEventListener('change', handleInputChange);\nform.addEventListener('submit', handleFormSubmit);\n\nfunction handleUserClick(event) { /* ... */ }\nfunction handleInputChange(event) { /* ... */ }\nfunction handleFormSubmit(event) { /* ... */ }\n```\n\n### 나쁜 예시: 일관성 없는 코드\n\n```plaintext\n// 네이밍 컨벤션이 모두 제각각이다.\nbutton.addEventListener('click', onButtonClick);\ninput.addEventListener('change', handleInputChange);\nform.addEventListener('submit', submitTheForm);\n\n// 함수 선언 스타일도 일관성이 없다.\nconst onButtonClick = (event) => { /* ... */ };\nfunction handleInputChange(event) { /* ... */ }\nconst submitTheForm = function(event) { /* ... */ };\n\n// -> 독자는 각 함수가 무슨 일을 하는지, 왜 다르게 작성되었는지 파악하는 데\n// 추가적인 노력을 들여야 하므로 인지 부하가 증가한다.\n```\n\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 개발자는 새 디렉터리와 5개의 마크다운 파일이 모두 올바른 위치에 생성되었고, 그 내용이 명세와 일치하는지 확인해야 합니다.\n\n```bash\n# 1. 디렉터리 및 파일 생성 확인.\n# 프로젝트 루트로 이동하여 'find' 명령을 실행합니다.\nfind principles/core-philosophy -type f\n\n# 2. 개념적으로 포매팅 확인.\n# 아직 실행 스크립트는 없지만(에픽 10), 파일들은 Prettier와\n# markdownlint 표준을 준수하도록 작성되어야 합니다.\n# 수동 검사나 로컬 포매터를 실행하여 이를 확인할 수 있습니다.\n```\n\n### 4.2. 예상 결과\n\n- `find` 명령어는 다음 5개의 파일을 나열하여 생성을 확인해야 합니다.\n\n```\nprinciples/core-philosophy/explicit-is-better-than-implicit.md\nprinciples/core-philosophy/maintain-consistent-style.md\nprinciples/core-philosophy/minimize-review-debates.md\nprinciples/core-philosophy/readability-first.md\nprinciples/core-philosophy/reduce-cognitive-load.md\n```\n\n- 수동 또는 자동 포맷/린트 검사는 오류 없이 통과해야 합니다.","results","가독성, 일관성, 인지 부하 최소화와 같은 기초 가치를 정의하는 문서 세트","checklists",[81,86,89,92,95],{"_24":82,"_83":39,"_84":61,"_85":61},"'가독성 우선' 원칙 문서","checked","taskIndex","checklistIndex",{"_24":87,"_83":39,"_84":61,"_85":88},"'리뷰 논쟁 최소화' 원칙 문서",1,{"_24":90,"_83":39,"_84":61,"_85":91},"'인지 부하 감소' 원칙 문서",2,{"_24":93,"_83":39,"_84":61,"_85":94},"'암시적인 것보다 명시적인 것이 낫다' 원칙 문서",3,{"_24":96,"_83":39,"_84":61,"_85":97},"'일관된 스타일 유지' 원칙 문서",4,"프로젝트의 핵심 철학 원칙을 상세히 기술하는 마크다운 문서를 작성","",{"_22":101,"_24":102,"_75":103,"_77":104,"_79":105,"_51":116,"_42":99},"task-1751363025664","개발 프로세스 원칙 문서","# 과업: 개발 프로세스 원칙 문서\n\n> **에픽**: 핵심 개발 원칙 수립\n\n## 1. 과업 정의\n\n### 1.1. 목표\n\n- **목표**: 개발 워크플로와 표준 관행을 규정하는 문서 작성.\n- **근거**: 개발 생명주기의 모범 사례에 대한 표준화되고 공유된 이해를 구축하기 위함. 이 원칙들은 팀이 구현, 테스트, 최적화 및 코드 리뷰에 접근하는 방식의 일관성을 보장하며, 고품질의 가독성 있고 유지보수 가능한 소프트웨어 결과물을 만든다는 프로젝트의 핵심 목표에 직접적으로 기여함.\n\n### 1.2. 결과물\n\n- **예상 결과**: 구현부터 코드 리뷰까지 전체 개발 생명주기를 포괄하는 포괄적인 원칙 모음.\n- **명세**: 각각 특정 개발 프로세스 원칙을 정의하는 12개의 새로운 마크다운 문서 생성. 이 파일들은 수립된 문서 구조와 스타일을 따름.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── principles/\n# └── development-process/\n# ├── automate-pipelines.md <-- 신규\n# ├── boy-scout-rule.md <-- 신규\n# ├── fail-fast.md <-- 신규\n# ├── fixed-environment.md <-- 신규\n# ├── keep-it-simple.md <-- 신규\n# ├── make-it-work-then-right.md <-- 신규\n# ├── mandatory-code-reviews.md <-- 신규\n# ├── measure-before-optimizing.md <-- 신규\n# ├── no-broken-commits.md <-- 신규\n# ├── test-dont-debug.md <-- 신규\n# ├── verify-with-tests.md <-- 신규\n# └── yagni.md <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 개발자가 일상적인 워크플로 중에 개발 프로세스 원칙을 어떻게 참고하고 적용하는지 보여주며, 코드와 문서를 생성하고 유지보수하기 위한 기본 가이드 역할을 합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"개발자 워크플로\"\n Dev[\"개발자\"] --> Consult[\"개발
프로세스 원칙 참고\"];\n Consult --> Implement[\"코드 구현/수정
(예: KISS, YAGNI 적용)\"];\n Implement --> Test[\"테스트 작성/실행
('디버깅 대신 테스트' 적용)\"];\n Test --> Review[\"코드 리뷰를 위한
풀 리퀘스트 생성\"];\n end\n\n subgraph \"품질 보증 및 통합\"\n Review --> Peer[\"동료 개발자 코드 리뷰
('필수 코드 리뷰' 적용)\"];\n Peer --> CI[\"CI 파이프라인 검증
('파이프라인 자동화' 적용)\"];\n CI --> Merge[\"main 브랜치에 병합
('깨진 커밋 금지' 보장)\"];\n end\n\n style Dev fill:#f9f,stroke:#333,stroke-width:2px\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 과업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] YAGNI, KISS, '작동하게 만든 후, 올바르게 만들기' 원칙 문서.\n- [ ] 테스트 및 최적화 원칙 문서 (최적화 전 측정, 디버깅 대신 테스트).\n- [ ] 자동화, 환경, 코드 리뷰 원칙 문서.\n- [ ] 코드 품질 원칙 문서 (Fail-fast, 보이스카우트 규칙).\n- [ ] 커밋 및 빌드 안정성 원칙 문서.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 저장소\n- **관련 주요 구성 요소**:\n - **엔지니어링 원칙**: 이 과업은 이 핵심 구성 요소 내에 새로운 자산을 직접 생성합니다. 이 문서들은 전체 지식 기반의 언어 독립적인 기반 역할을 합니다.\n - **언어 가이드라인**: 이 과업에서 정의된 원칙들은 모든 미래의 언어별 가이드라인(예: C++, Shell)에서 특정 규칙에 대한 근거와 정당성으로 사용될 것입니다.\n - **자동화 도구**: 자동화와 CI/CD 원칙은 이 구성 요소의 스크립트 및 워크플로 구현을 안내할 것입니다.\n\n### 2.2. 영향받는 파일\n\n이 과업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `principles/development-process/yagni.md`\n- `principles/development-process/keep-it-simple.md`\n- `principles/development-process/make-it-work-then-right.md`\n- `principles/development-process/measure-before-optimizing.md`\n- `principles/development-process/verify-with-tests.md`\n- `principles/development-process/automate-pipelines.md`\n- `principles/development-process/fixed-environment.md`\n- `principles/development-process/test-dont-debug.md`\n- `principles/development-process/fail-fast.md`\n- `principles/development-process/mandatory-code-reviews.md`\n- `principles/development-process/boy-scout-rule.md`\n- `principles/development-process/no-broken-commits.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 한 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공할 것입니다.\n\n---\n\n### 1단계: YAGNI, KISS, '작동하게 만든 후, 올바르게 만들기' 원칙 문서\n\n#### 1. YAGNI 원칙 문서 생성\n\n이 작업은 \"You Ain't Gonna Need It\"(YAGNI) 원칙을 정의하는 마크다운 파일을 생성하는 것을 포함합니다. 이 원칙은 추측성 기능 구현을 지양함으로써 과도한 엔지니어링을 방지하고 코드베이스를 간결하게 유지하는 데 기본이 됩니다. 문서는 그 근거를 설명하고 좋은 예와 나쁜 예시를 제공할 것입니다.\n\n**파일**: `principles/development-process/yagni.md`\n\n```markdown\n# 원칙: YAGNI (You Ain't Gonna Need It)\n\n**태그**: 개발 프로세스, 단순성, YAGNI\n\n---\n\n## 1. 핵심 정의\n\n> \"You Ain't Gonna Need It\"(YAGNI) 원칙은 현재 요구사항을 충족하는 데 필요한\n> 기능만 구현하고, 미래의 필요를 '예측'하여 기능을 만들지 말아야 한다는\n> 원칙입니다.\n\n## 2. 근거 (왜?)\n\n미래를 예측해서 만든 기능은 사용되지 않을 가능성이 매우 높습니다. 이는 불필요한\n코드의 확산으로 이어져 시스템의 복잡성과 테스트 및 유지보수 비용을 증가시킵니다.\n또한, 미리 만든 기능은 실제 미래의 요구사항과 맞지 않아 버려지거나, 잘못된\n가정을 기반으로 만들어져 시스템 전체 설계를 왜곡시킬 수도 있습니다. 지금 당장\n필요한 가장 단순한 것을 구현하는 것이 가장 빠르고 경제적인 길입니다.\n\n- _불필요한 기능을 개발하는 데 드는 시간과 노력을 절약합니다._\n- _코드베이스를 단순하고 작게 유지하여 유지보수 비용을 줄입니다._\n- _잘못된 예측에 기반한 결함 있는 설계를 방지하고 시스템의 유연성을 높입니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **현재 요구사항에 집중하기**: 명확하게 정의된 현재의 요구사항을 해결하는 가장\n 단순한 코드를 작성합니다.\n- **필요할 때 확장하기**: 새로운 기능이 실제로 필요해졌을 때 코드를 리팩토링하고\n 확장합니다.\n- **'만약에' 질문 경계하기**: \"나중에 이런 기능이 필요하면 어떡하지?\"라는 생각이\n 들 때 YAGNI 원칙을 떠올리며, 지금은 불필요한 고민임을 인지합니다.\n\n### 금지 사항 (Don't)\n\n- **미래 예측 기반 코딩 금지**: \"언젠가 필요할지 모른다\"는 생각으로 당장 사용되지\n 않는 클래스, 함수, 매개변수 등을 만들지 않습니다.\n- **과도한 일반화 금지**: 지금은 하나의 케이스만 존재하는데, 여러 미래의 케이스를\n 대비하기 위해 지나치게 유연하고 복잡한 설계를 만들지 않습니다.\n- **사용하지 않는 코드 남겨두지 않기**: 주석 처리된 코드나 현재 어디에서도 호출되지\n 않는 '죽은 코드(dead code)'를 과감히 삭제합니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 현재 요구사항만 만족하는 코드\n\n```plaintext\n// 요구사항: \"사용자 정보를 CSV 파일로 내보낼 수 있어야 한다.\"\n\nclass CsvExporter {\npublic:\n string exportUsers(const vector& users) {\n // CSV 형식으로 변환하는 로직만 구현한다\n // ...\n return csvData;\n }\n};\n```\n\n### 나쁜 예시: 미래 예측에 기반한 과도한 엔지니어링 코드\n\n```plaintext\n// \"나중엔 CSV뿐만 아니라 JSON이나 XML로도 내보내야 할지 몰라.\"라는 생각에 기반한\n// 불필요하게 복잡한 설계\n\n// 인터페이스 정의\nclass IExporter {\npublic:\n virtual ~IExporter() = default;\n virtual string exportUsers(const vector& users) = 0;\n};\n\n// CSV 익스포터 구현\nclass CsvExporter : public IExporter {\npublic:\n string exportUsers(const vector& users) override { /* ... */ }\n};\n\n// JSON 익스포터 (현재 아무도 사용하지 않음)\nclass JsonExporter : public IExporter {\npublic:\n string exportUsers(const vector& users) override { /* ... */ }\n};\n\n// -> 현재 요구사항은 CSV뿐인데 불필요한 인터페이스와 사용되지 않는 클래스가 추가되어\n// 코드 구조가 복잡해지고 유지보수 포인트가 늘어났다.\n```\n\n```\n\n#### 2. KISS 원칙 문서 생성\n\n이 작업은 \"Keep It Simple, Stupid\"(KISS) 원칙에 대한 문서를 생성합니다. 이 원칙은 가독성을 높이고 버그를 줄이며 유지보수성을 향상시키기 위해 설게의 주요 목표로 단순성을 옹호합니다. 이 파일은 원칙을 정의하고 복잡한 문제를 더 간단하고 관리하기 쉬운 함수로 분해하여 적용하는 방법을 설명합니다.\n\n**파일**: `principles/development-process/keep-it-simple.md`\n\n```markdown\n# 원칙: KISS (Keep It Simple, Stupid)\n\n**태그**: 단순성, 디자인, 유지보수성\n\n---\n\n## 1. 핵심 정의\n\n> 대부분의 시스템은 복잡하게 만드는 것보다 단순하게 유지할 때 가장 잘 작동합니다.\n> 따라서 단순성은 설계의 핵심 목표가 되어야 하며, 불필요한 복잡성은 피해야 합니다.\n\n## 2. 근거 (왜?)\n\n복잡한 코드는 이해하기 어렵고, 유지보수하기 힘들며, 버그의 주된 원인이 됩니다.\n단순하고 명확한 코드는 읽기 쉽고, 테스트하기 쉬우며, 디버깅하기 쉽습니다. 이는\n개발자의 인지 부하를 줄여주어, 코드 자체를 해독하는 대신 실제 비즈니스 문제를\n해결하는 데 집중할 수 있게 합니다. 단순성은 신뢰할 수 있고 유지보수 가능한\n소프트웨어를 만드는 전제 조건입니다.\n\n- _코드 가독성을 향상시키고 이해하는 데 필요한 시간을 줄입니다._\n- _유지보수나 확장 시 버그가 발생할 위험을 낮춥니다._\n- _테스트를 더 쉽고 효과적으로 만듭니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **가장 단순한 해결책 선택하기**: 항상 요구사항을 충족하는 가장 간단한 해결책으로\n 시작합니다.\n- **문제 분해하기**: 복잡한 문제를 더 작고, 독립적이며, 관리 가능한 부분으로\n 분해합니다.\n- **명확한 코드 작성하기**: 직접적인 로직을 사용하고 다른 사람을 혼란스럽게 할 수\n 있는 영리하거나 모호한 언어 기능을 피합니다.\n- **단순성을 위해 리팩토링하기**: 코드 조각이 너무 복잡해지고 있다면, 구조를\n 단순화하기 위해 적극적으로 리팩토링합니다.\n\n### 금지 사항 (Don't)\n\n- **과도한 엔지니어링 금지**: 현재 요구사항으로 정당화되지 않는 복잡한 디자인\n 패턴이나 추상화 계층을 구현하지 않습니다.\n- **기능 조기 추가 금지**: 미래의 필요에 대한 추측에 기반하여 기능을 추가하지\n 않습니다 (YAGNI 참조).\n- **간결함을 위해 명확성 희생 금지**: 코드를 더 이해하기 어렵게 만든다면, 더 적은\n 줄의 코드를 작성하는 것이 목표가 아닙니다.\n\n## 4. 코드 예시\n\n### 나쁜 예시: 하나의 복잡한 함수\n\n이 함수는 소계 계산, 할인 적용, 배송비 추가 등 여러 책임을 혼합하여 읽고\n테스트하기 어렵게 만듭니다.\n\n```plaintext\nfunction calculate_total_price(list_of_items, is_vip_member, use_express_shipping)\n // 나쁨: 이 함수는 한 번에 너무 많은 일을 합니다.\n\n // 1. 소계 계산\n subtotal = 0\n for each item in list_of_items\n subtotal = subtotal + item.price\n end for\n\n // 2. 할인 적용\n discounted_total = subtotal\n if is_vip_member is true then\n if subtotal > 100 then\n discounted_total = subtotal * 0.90 // 10% 할인\n else\n discounted_total = subtotal * 0.95 // 5% 할인\n end if\n end if\n\n // 3. 배송비 추가\n final_total = discounted_total\n if use_express_shipping is true then\n final_total = discounted_total + 10 // $10 특급 배송비\n end if\n\n return final_total\nend function\n```\n\n### 좋은 예시: 단순하고 단일 책임 함수로 분해\n\n로직을 더 작고 집중된 함수로 분해함으로써 코드는 자체적으로 문서화되고,\n테스트하기 쉬우며, 재사용 가능해집니다.\n\n```plaintext\n// 좋음: 각 함수는 단일하고 명확한 책임을 가집니다.\n\nfunction calculate_subtotal(list_of_items)\n subtotal = 0\n for each item in list_of_items\n subtotal = subtotal + item.price\n end for\n return subtotal\nend function\n\nfunction apply_vip_discount(price, is_vip_member)\n if is_vip_member is false then\n return price\n end if\n\n if price > 100 then\n return price * 0.90\n else\n return price * 0.95\n end if\nend function\n\nfunction add_shipping_fee(price, use_express_shipping)\n if use_express_shipping is true then\n return price + 10\n end if\n return price\nend function\n\n// 이제 메인 함수는 단순하고 읽기 쉬우며, 다른 함수들을 조합합니다.\nfunction calculate_total_price(list_of_items, is_vip_member, use_express_shipping)\n subtotal = calculate_subtotal(list_of_items)\n price_after_discount = apply_vip_discount(subtotal, is_vip_member)\n final_price = add_shipping_fee(price_after_discount, use_express_shipping)\n return final_price\nend function\n```\n\n```\n\n#### 3. '작동하게 만든 후, 올바르게 만들기' 원칙 문서 생성\n\n이 작업은 \"Make It Work, Then Make It Right\" 원칙을 정의하는 문서를 생성합니다. 이 접근 방식은 반복적인 개발 프로세스를 장려하여, 먼저 기능적인 해결책을 우선시하고 그 다음에 품질을 위한 리팩토링을 수행합니다. 이는 초기 제공을 가속화하고 후속 개선을 위한 안정적인 기반을 제공하며, 이는 팀의 핵심 프로세스입니다.\n\n**파일**: `principles/development-process/make-it-work-then-right.md`\n\n```markdown\n# 원칙: 먼저 작동하게 만들고, 그 다음에 올바르게 만들라\n\n**태그**: 개발 프로세스, 점진적 개선, 리팩토링\n\n---\n\n## 1. 핵심 정의\n\n> 새로운 기능을 개발할 때, 처음부터 완벽하고 최적화된 코드를 추구하는 대신, 먼저\n> 요구사항을 충족하고 작동하는 가장 단순한 코드를 작성합니다. 그런 다음 테스트가\n> 통과하는 것을 확인한 후, 코드를 점진적으로 리팩토링하여 '올바르게' 만듭니다.\n\n## 2. 근거 (왜?)\n\n처음부터 완벽한 설계를 시도하면 종종 과도한 추상화나 불필요한 복잡성으로 이어져\n개발 속도를 늦춥니다. 먼저 '작동하는' 코드를 확보함으로써 기능이 올바른 방향으로\n가고 있는지 빠르게 확인하고 피드백을 얻을 수 있습니다. 이 안정적인 기반 위에서,\n우리는 코드를 더 읽기 쉽고, 효율적이며, 유지보수하기 쉬운 '올바른' 형태로 자신\n있게 개선할 수 있습니다. 이 접근 방식은 분석 마비(Analysis Paralysis)를 피하고\n지속적인 성취감을 통해 개발 동기를 유지하는 데 도움이 됩니다.\n\n- _빠른 피드백 루프를 통해 개발 방향의 불확실성을 줄입니다._\n- _초기 개발 속도를 높여 가치를 더 빨리 전달합니다._\n- _작동하는 코드를 기반으로 리팩토링하므로 개선 과정이 더 안정적입니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **가장 단순한 해결책으로 시작하기**: 먼저, 요구사항을 만족하는 가장 직접적이고\n 단순한 코드를 작성합니다.\n- **먼저 작동하는지 확인하기**: 코드를 작성한 후에는 항상 테스트를 통해 의도한 대로\n 작동하는지 확인합니다.\n- **별도의 단계로 리팩토링하기**: 기능 구현과 리팩토링을 동시에 하지 않습니다.\n 코드가 작동하는 것을 확인한 후, 별도의 '리팩토링' 단계에서 코드 품질을\n 향상시킵니다.\n\n### 금지 사항 (Don't)\n\n- **성급한 최적화 금지**: 코드가 작동하는지 확인하기 전에 성능 최적화나 복잡한\n 디자인 패턴을 적용하지 않습니다.\n- **완벽주의로 인한 지연 금지**: 완벽한 아키텍처를 고민하느라 코딩을 시작하지\n 못하는 상황을 피합니다. 시작해서 작동하게 만드는 것이 중요합니다.\n- **리팩토링 중 기능 변경 금지**: 리팩토링은 코드의 구조를 개선하는 과정입니다. 이\n 과정에서 새로운 기능을 추가하거나 기존 기능의 동작을 변경해서는 안 됩니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 점진적 개선 과정\n\n```plaintext\n// 1단계: 작동하게 만들기 (가장 단순한 방법)\n// 요구사항: \"숫자 배열이 주어졌을 때, 짝수를 찾아 제곱한 후 그 합을 구하라.\"\nfunction calculateSumOfSquaredEvens(numbers) {\n let sum = 0;\n for (let i = 0; i < numbers.length; i++) {\n if (numbers[i] % 2 === 0) {\n sum += numbers[i] * numbers[i];\n }\n }\n return sum;\n}\n// -> 먼저, 코드가 작동하게 하고 테스트를 통과시킵니다.\n\n// 2단계: 그 다음에 올바르게 만들기 (리팩토링)\nfunction calculateSumOfSquaredEvensRefactored(numbers) {\n return numbers\n .filter(num => num % 2 === 0)\n .map(num => num * num)\n .reduce((sum, squared) => sum + squared, 0);\n}\n// -> 더 나은 가독성과 표현력을 위해 코드를 개선합니다.\n```\n\n### 나쁜 예시: 처음부터 과도한 엔지니어링\n\n```plaintext\n// 처음부터 모든 것을 추상화하고 유연성을 위해 복잡한 클래스와 메소드를 설계합니다.\nclass NumberProcessor {\n constructor(numbers) {\n this.numbers = numbers;\n }\n\n filter(predicate) {\n return new NumberProcessor(this.numbers.filter(predicate));\n }\n\n map(transformer) {\n return new NumberProcessor(this.numbers.map(transformer));\n }\n\n reduce(reducer, initialValue) {\n return this.numbers.reduce(reducer, initialValue);\n }\n}\n\n// 사용법\nconst processor = new NumberProcessor([1, 2, 3, 4]);\nconst result = processor\n .filter(n => n % 2 === 0)\n .map(n => n * n)\n .reduce((sum, n) => sum + n, 0);\n\n// -> 이것은 단순한 요구사항에 비해 너무 복잡하고 과도하게 엔지니어링되었습니다.\n// -> 또한 YAGNI 원칙을 위반합니다.\n```\n\n```\n\n---\n### 2단계: 테스트 및 최적화 원칙 문서 (최적화 전 측정, 디버깅 대신 테스트).\n\n#### 1. '최적화 전 측정' 원칙 문서 생성\n\n이 작업은 데이터 기반 최적화 원칙을 정의하는 파일을 생성합니다. 성능 개선은 직관이 아닌 프로파일링 도구의 증거에 기반해야 한다는 규칙을 공식화하여, 낭비되는 노력을 방지하고 코드 품질을 보존합니다. 이것은 고성능이면서도 읽기 쉬운 코드베이스를 유지하는 데 중요합니다.\n\n**파일**: `principles/development-process/measure-before-optimizing.md`\n\n```markdown\n# 원칙: 추측이 아닌 측정을 기반으로 최적화하라\n\n**태그**: 개발 프로세스, 성능, 최적화\n\n---\n\n## 1. 핵심 정의\n\n> 성능 최적화는 개발자의 직감이나 추측이 아닌, 프로파일링 도구를 사용한 정확한\n> 데이터 측정으로 병목 지점을 확인한 후에만 수행해야 합니다. \"성급한 최적화는 모든\n> 악의 근원이다.\" (도널드 커누스)\n\n## 2. 근거 (왜?)\n\n개발자의 직감은 틀리는 경우가 많습니다. 실제 성능 병목은 종종 예상치 못한 곳에서\n발생합니다. 측정 없는 최적화는 다음과 같은 문제로 이어집니다.\n\n1. **시간 낭비**: 실제 병목이 아닌 부분에 노력을 쏟게 됩니다.\n2. **코드 품질 저하**: 최적화는 종종 코드의 가독성과 단순성을 해칩니다. 불필요한\n 최적화는 성능 이득 없이 코드만 복잡하게 만듭니다.\n3. **새로운 버그 유발**: 복잡해진 코드는 새로운 버그를 만들 가능성을 높입니다.\n\n가장 효율적이고 안전한 방법은 정확한 측정을 통해 진짜 문제 지점을 찾아내고, 오직\n그곳에만 최적화 노력을 집중하는 것입니다.\n\n- _실제 문제에 집중하여 개발 시간을 효율적으로 사용합니다._\n- _불필요한 코드 변경을 막아 코드의 가독성과 안정성을 보호합니다._\n- _최적화 효과를 정량적으로 증명하여 작업의 가치를 입증합니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **프로파일러 사용하기**: 코드를 최적화하기 전에 항상 프로파일링 도구를 사용하여\n 가장 많은 시간이 소요되는 '핫스팟'을 찾습니다.\n- **벤치마크 작성하기**: 최적화 전후의 성능을 비교하여 개선 사항을 정량적으로\n 측정하기 위한 벤치마크 테스트를 작성합니다.\n- **80/20 법칙 적용하기**: 시스템 성능 문제의 80%는 20%의 코드에서 비롯된다는\n 점을 기억하고, 가장 큰 영향을 미치는 부분에 집중합니다.\n\n### 금지 사항 (Don't)\n\n- **직감에 기반한 최적화 금지**: \"이 부분이 느릴 것 같다\"는 생각만으로 코드를\n 수정하지 않습니다.\n- **모든 코드 최적화 시도 금지**: 중요하지 않은 부분의 미미한 성능을 개선하기\n 위해 전체 코드베이스의 가독성을 희생하지 않습니다.\n- **측정 없는 알고리즘 변경 금지**: 이론적으로 더 빠르다는 이유만으로, 측정 없이\n 더 복잡한 자료 구조나 알고리즘을 도입하지 않습니다. 실제 데이터 환경에서는 오히려\n 더 느릴 수도 있습니다.\n\n## 4. 코드 예시\n\n### 나쁜 예시: 직감에 의한 최적화\n\n```plaintext\n// 개발자는 for-loop가 느릴 것이라고 '추측'하고 코드를 복잡하게 변경하여\n// 가독성을 해쳤습니다. 하지만 이 부분은 실제 병목 지점이 아니었습니다.\n\n// 원래 코드\nlet total = 0;\nfor (const item of items) {\n total += item.price;\n}\n\n// 성급한 최적화 시도 (가독성 저하, 성능 이득 미미)\nlet totalOptimized = 0;\nlet i = items.length;\nwhile (i--) {\n totalOptimized += items[i].price;\n}\n\n// -> 실제 병목은 'items' 배열을 생성하는 과정에 있었고, 이 최적화는 의미가 없었습니다.\n```\n\n### 좋은 예시: 측정에 기반한 최적화\n\n```plaintext\n// 1. 프로파일링 결과, findUserById 함수가 반복적으로 호출되며 가장 많은 시간을 소모하는 것으로 나타났습니다.\n// 원인: 매번 전체 사용자 목록을 순회합니다.\n\n// 최적화 전\nfunction findUserById(users, id) {\n return users.find(user => user.id === id);\n}\n\n// 2. 병목 지점을 개선하기 위해 자료 구조를 변경하여 최적화합니다.\n\n// 최적화 후\n// 사용자 목록을 미리 Map으로 변환하여 O(1) 시간 복잡도로 조회할 수 있게 합니다.\nconst usersById = new Map(users.map(user => [user.id, user]));\n\nfunction findUserByIdOptimized(usersMap, id) {\n return usersMap.get(id);\n}\n\n// -> 벤치마크 결과, 사용자 검색 속도가 100배 이상 개선되었음을 확인했습니다.\n```\n\n```\n\n#### 2. '테스트로 검증' 원칙 문서 생성\n\n이 작업은 자동화된 테스트와 정적 분석의 중요성을 공식화하는 문서를 생성합니다. 이는 코드의 정확성이 수동 확인이 아닌 객관적인 증거로 입증되어야 함을 확립합니다. 이 원칙은 리팩토링 및 기능 개발 중 소프트웨어 안정성과 개발자 신뢰를 보장하기 위한 초석입니다.\n\n**파일**: `principles/development-process/verify-with-tests.md`\n\n```markdown\n# 원칙: 테스트와 정적 분석으로 검증하라\n\n**태그**: 개발 프로세스, 품질, 테스트, 정적 분석\n\n---\n\n## 1. 핵심 정의\n\n> 코드가 올바르게 작동한다는 확신은 개발자의 수동 확인이나 희망에 기반해서는 안\n> 되며, 자동화된 테스트와 정적 분석 도구와 같은 객관적인 증거를 통해 확보해야\n> 합니다.\n\n## 2. 근거 (왜?)\n\n사람은 반복적으로 실수하지만 잘 작성된 테스트와 컴퓨터는 그렇지 않습니다. 자동화된\n검증 시스템은 코드를 변경했을 때 예상치 못한 부작용이 발생했는지 즉시 알려주는\n안전망 역할을 합니다. 이를 통해 개발자는 기존 기능이 깨질 것을 두려워하지 않고\n새로운 기능을 추가하거나 리팩토링할 때 자신감을 갖고 작업할 수 있습니다. 또한,\n정적 분석은 코드를 실행하지 않고도 잠재적인 오류, 버그, 스타일 위반을 조기에\n발견하여 높은 수준의 품질을 유지하는 데 도움을 줍니다.\n\n- _코드 변경에 대한 자신감을 주어 개발 속도와 안정성을 높입니다._\n- _잠재적인 버그를 조기에 발견하여 디버깅에 소요되는 시간을 줄입니다._\n- _테스트 코드 자체가 살아있는 문서 역할을 하여 코드 이해를 돕습니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **단위 테스트 작성하기**: 모든 새로운 로직에 대해 해당 기능만 독립적으로\n 검증하는 단위 테스트를 작성합니다.\n- **정적 분석 도구 도입하기**: 린터, 코드 포맷터와 같은 정적 분석 도구를 도입하고,\n CI 파이프라인에 통합하여 모든 커밋을 자동으로 검사합니다.\n- **테스트 커버리지 측정하기**: 테스트 커버리지를 측정하여 테스트되지 않은 코드를\n 식별하고 중요한 로직이 항상 테스트되도록 보장합니다.\n\n### 금지 사항 (Don't)\n\n- **테스트 없는 코드 금지**: 테스트 작성이 어렵다는 이유만으로 테스트 없이 코드를\n 작성하지 않습니다. 테스트하기 어려운 코드는 보통 잘못 설계된 코드입니다.\n- **수동 테스트에 의존 금지**: 반복적인 회귀 테스트를 수동으로 수행하지 않습니다.\n 모든 것은 자동화되어야 합니다.\n- **정적 분석 경고 무시 금지**: 정적 분석 도구가 보고하는 경고나 오류를 무시하지\n 않습니다. 그것들은 잠재적인 버그의 신호일 수 있습니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 테스트 코드로 검증하기\n\n```plaintext\n// 기능 코드 (src/utils.js)\nfunction add(a, b) {\n return a + b;\n}\n\n// 테스트 코드 (test/utils.test.js)\n// 1. 기본 케이스\ntest('add(1, 2) should return 3', () => {\n expect(add(1, 2)).toBe(3);\n});\n\n// 2. 엣지 케이스 (음수)\ntest('add(-1, -1) should return -2', () => {\n expect(add(-1, -1)).toBe(-2);\n});\n\n// -> 기능이 변경될 때마다 이 테스트들이 자동으로 실행되어 안정성을 보장합니다.\n```\n\n### 나쁜 예시: 수동으로 확인하고 넘어가기\n\n```plaintext\nfunction add(a, b) {\n return a + b;\n}\n\n// 개발자: \"콘솔에 찍어보니 잘 되네. 문제없음!\"\nconsole.log(add(1, 2)); // 3\nconsole.log(add(5, 10)); // 15\n\n// -> 나중에 누군가 add 함수를 다음과 같이 수정했다고 가정해봅시다.\nfunction add(a, b) {\n // 숫자 덧셈 대신 문자열 연결로 변경됨\n return String(a) + String(b);\n}\n\n// -> 자동화된 테스트가 없으면, 이 변경이 어떤 문제를 일으킬지 아무도 모릅니다.\n// 콘솔 로깅은 일회성 확인일 뿐이며 지속적인 품질을 보장할 수 없습니다.\n```\n\n```\n\n#### 3. '디버깅 대신 테스트' 원칙 문서 생성\n\n이 작업은 \"Test, Don't Debug\" 원칙에 대한 문서를 생성합니다. 이는 버그 수정 및 검증에 대해 테스트 우선 접근 방식을 의무화하며, 자동화된 테스트가 수동 디버깅을 대체하는 주요 도구가 됩니다. 이는 버그 수정이 영구적이고 검증 가능하도록 보장하며, 회귀를 방지하고 시간이 지남에 따라 견고한 테스트 스위트를 구축합니다.\n\n**파일**: `principles/development-process/test-dont-debug.md`\n\n```markdown\n# 원칙: 디버깅이 아닌 테스트로 검증하라\n\n**태그**: 개발 프로세스, 테스트, 디버깅, 품질\n\n---\n\n## 1. 핵심 정의\n\n> 코드 동작을 검증하는 주요 수단은 디버거를 이용한 수동 추적이 아니라, 특정\n> 시나리오를 재현하고 결과를 단언하는 자동화된 테스트여야 합니다. 버그가 발견되면\n> 먼저 이를 재현하는 테스트를 작성한 후, 그 테스트를 통과하도록 코드를 수정합니다.\n\n## 2. 근거 (왜?)\n\n디버깅은 일회성, 수동 활동입니다. 같은 버그가 다시 발생하면 똑같은 디버깅 과정을\n반복해야 합니다. 반면, 테스트 케이스는 버그가 발생한 특정 조건을 영구적으로\n기록하고, 문제가 해결되었음을 보장하며, 미래에 같은 실수가 반복되는 것을 막는\n자동화된 안전망이 됩니다. 이러한 접근 방식(테스트 주도 개발, TDD)은 개발 과정을\n'디버깅'에서 '테스트 통과시키기'로 전환하여 개발자에게 더 명확한 목표와 빠른\n피드백을 제공하고, 점진적으로 코드베이스 전체의 품질과 안정성을 향상시킵니다.\n\n- _버그 수정 과정을 재사용 가능한 자산(테스트 코드)으로 전환합니다._\n- _동일한 버그의 재발을 근본적으로 방지합니다._\n- _코드의 동작에 대한 신뢰도를 높여 리팩토링과 기능 추가를 용이하게 합니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **버그 재현 테스트 작성하기**: 버그 리포트를 받으면 디버거를 켜기 전에 버그를\n 재현하는 실패하는 테스트 케이스를 먼저 작성합니다.\n- **테스트 통과로 버그 수정하기**: 작성한 테스트가 통과하도록 코드를 수정합니다.\n 테스트 통과는 버그가 수정되었음을 의미합니다.\n- **테스트 주도 개발(TDD) 실천하기**: 새로운 기능을 추가할 때, 먼저 실패하는\n 테스트를 작성하고 그 다음 이를 통과시키는 코드를 작성하는 것을 목표로 합니다.\n\n### 금지 사항 (Don't)\n\n- **디버거에만 의존하지 않기**: 반복적으로 중단점을 설정하고 코드를 한 줄씩 실행하며\n 동작을 확인하는 것에만 의존하지 않습니다.\n- **테스트 없이 버그 수정 금지**: 실패하는 테스트 케이스 없이 '감'으로 버그를\n 수정하지 않습니다. 수정이 올바른지, 다른 문제를 일으키지 않는지 보장할 수 없습니다.\n- **콘솔 로그 디버깅 남용 금지**: 값을 확인하기 위해 코드 곳곳에 `console.log`나\n `printf`를 삽입하는 것은 일회성 해결책이며 코드를 지저분하게 만듭니다. 테스트로\n 검증하는 것이 더 체계적입니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 테스트로 버그를 잡는 과정\n\n```plaintext\n// 버그 시나리오: 'calculateDiscount' 함수는 100달러 이상 구매 시 10% 할인을 적용해야 하는데, 정확히 100달러일 때 적용되지 않음.\n\n// 1. 먼저, 버그를 재현하는 실패하는 테스트를 작성합니다.\n// test/discount.test.js\ntest('should apply a 10% discount for a $100 purchase', () => {\n expect(calculateDiscount(100)).toBe(90);\n});\n// -> 이 테스트는 초기에 실패할 것입니다 (결과는 100이 나옴).\n\n// 2. 테스트가 통과하도록 코드를 수정합니다.\n// src/discount.js\nfunction calculateDiscount(price) {\n if (price > 100) { // 버그의 원인: '>'가 '>='여야 함\n return price * 0.9;\n }\n return price;\n}\n\n// 수정 후\nfunction calculateDiscount(price) {\n if (price >= 100) { // 올바른 로직\n return price * 0.9;\n }\n return price;\n}\n\n// 3. 테스트를 다시 실행하면 통과합니다. 버그가 수정되었고, 이 테스트는 미래의 실수를 방지합니다.\n```\n\n### 나쁜 예시: 디버거와 콘솔 로그에만 의존하기\n\n```plaintext\n// 개발자가 버그 리포트를 받고 디버거를 시작합니다.\n// price가 100일 때 if (price > 100) 조건이 통과하지 않는 것을 발견합니다.\n\nfunction calculateDiscount(price) {\n console.log('Current price:', price); // 확인을 위해 로그 추가\n if (price > 100) {\n return price * 0.9;\n }\n return price;\n}\n\n// 코드를 수정합니다.\nfunction calculateDiscount(price) {\n if (price >= 100) {\n return price * 0.9;\n }\n return price;\n}\n\n// -> 버그는 수정되었지만, 이 과정을 기록하는 테스트 코드가 없습니다.\n// -> 나중에 다른 개발자가 이 코드를 '최적화'하면서 다시 '>'로 변경해도 아무도 알 수 없습니다.\n```\n\n```\n\n---\n### 3단계: 자동화, 환경, 코드 리뷰 원칙 문서.\n\n#### 1. '파이프라인 자동화' 원칙 문서 생성\n\n이 작업은 자동화된 CI/CD 파이프라인 사용 원칙을 정의하는 문서를 생성합니다. 모든 코드는 자동화되고 반복 가능한 프로세스를 통해 빌드, 테스트 및 통합되어야 한다는 요구사항을 공식화합니다. 이는 인적 오류를 제거하고 일관된 품질 검사를 보장하며 전반적인 개발 속도를 높입니다.\n\n**파일**: `principles/development-process/automate-pipelines.md`\n\n```markdown\n# 원칙: 자동화된 파이프라인을 구축하고 활용하라\n\n**태그**: 개발 프로세스, 자동화, CI/CD\n\n---\n\n## 1. 핵심 정의\n\n> 개발자의 수동 개입 없이 코드 빌드, 테스트, 정적 분석, 배포 등 일련의 과정을\n> 자동으로 실행하는 파이프라인(CI/CD)을 구축하고, 모든 코드 변경은 이 파이프라인을\n> 통해 검증 및 통합되도록 보장해야 합니다.\n\n## 2. 근거 (왜?)\n\n사람이 수동으로 처리하는 반복적인 작업은 언제나 실수가 발생하기 쉽습니다. 자동화된\n파이프라인은 \"내 컴퓨터에서는 잘 됐는데\"와 같은 문제를 근본적으로 제거하고, 모든\n코드 변경이 일관된 환경에서 동일한 절차를 통해 검증되도록 보장합니다. 이는 안정적인\n소프트웨어 품질을 유지하고, 개발자들이 빌드나 배포 같은 부수적인 작업에 시간을\n낭비하지 않고 핵심 개발 활동에 집중할 수 있게 합니다. 또한, 빠른 피드백 루프는\n문제를 조기에 발견하고 해결하는 데 도움을 주어 전반적인 개발 속도를 가속화합니다.\n\n- _인적 오류를 제거하여 빌드 및 배포 과정의 안정성을 보장합니다._\n- _개발자들을 반복적인 작업에서 해방시켜 생산성을 향상시킵니다._\n- _코드 통합부터 배포까지의 과정을 가속화하여 시장에 더 빨리 가치를 전달합니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **CI/CD 도구 도입하기**: GitHub Actions, Jenkins, GitLab CI와 같은 CI/CD 도구를\n 사용하여 파이프라인을 구축합니다.\n- **빌드 실패 조건 명시하기**: 테스트 실패, 린트 오류, 보안 취약점 등 품질 기준을\n 충족하지 못하면 파이프라인이 즉시 실패하고 개발자에게 알리도록 구성합니다.\n- **점진적 자동화**: 처음부터 완벽한 파이프라인을 구축하려 하지 말고, 빌드 -> 테스트\n -> 배포 순으로 자동화 범위를 점차 확장합니다.\n\n### 금지 사항 (Don't)\n\n- **로컬 환경에 의존하지 않기**: 특정 개발자의 로컬 환경에서만 성공하는 빌드나\n 테스트에 의존하지 않습니다. 모든 검증은 격리되고 통제된 파이프라인 환경에서\n 이루어져야 합니다.\n- **깨진 빌드 방치 금지**: 파이프라인이 실패하면(빌드가 깨지면), 새로운 기능을\n 개발하기 전에 최우선으로 수정해야 합니다.\n- **수동 배포에 의존 금지**: 자동화된 검증 과정 없이 사람이 직접 파일을 복사하는\n 등의 수동적인 방법으로 중요한 프로덕션 환경에 코드를 배포하지 않습니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 자동화된 CI/CD 파이프라인 흐름\n\n```plaintext\n1. 개발자가 원격 저장소(예: GitHub)에 코드를 푸시합니다.\n |\\\n V\n2. [자동 실행] CI 서버가 변경을 감지하고 파이프라인을 시작합니다.\n - 소스 코드를 체크아웃\n - 의존성 설치\n - 코드 빌드\n - 정적 분석 실행 (Linter, Formatter) -> 실패 시 중단 및 알림\n - 단위/통합 테스트 실행 -> 실패 시 중단 및 알림\n |\\\n V\n3. [자동 실행] 모든 검증이 통과하면 아티팩트(결과물)를 생성합니다.\n |\\\n V\n4. [자동 또는 수동 실행] 생성된 아티팩트를 스테이징 또는 프로덕션 환경에 배포합니다.\n\n// -> 전체 프로세스가 자동화되어 일관성과 안정성을 보장합니다.\n```\n\n### 나쁜 예시: 수동적이고 불안정한 프로세스\n\n```plaintext\n1. 개발자 A가 자신의 로컬 머신에서 코드를 빌드합니다.\n2. 빌드가 성공하면 메신저 앱을 통해 개발자 B에게 파일을 전송합니다.\n3. 개발자 B가 받은 파일을 FTP를 통해 테스트 서버에 수동으로 업로드합니다.\n4. 개발자 B가 서버에 접속하여 몇 가지 기능을 수동으로 클릭하며 테스트합니다.\n5. 문제가 없어 보이면, 개발자 A 또는 B가 같은 방식으로 프로덕션 서버에 파일을 올립니다.\n\n// -> 각 단계에서 사람의 개입으로 인한 오류 발생 확률이 높습니다.\n// -> 누가 어떤 버전의 코드를 언제 배포했는지 추적하기 어렵습니다.\n// -> 개발자 환경이 달라 \"내 컴퓨터에서는 됐는데\" 문제가 발생하기 쉽습니다.\n```\n\n```\n\n#### 2. '고정된 환경' 원칙 문서 생성\n\n이 작업은 개발 환경이 코드로 고정되고 정의되어야 한다는 문서를 생성합니다. 이 원칙은 모든 개발자와 CI 시스템이 동일하고 재현 가능한 환경에서 작동하도록 보장하여 \"내 컴퓨터에서는 되는데\" 문제를 제거하는 데 중요하며, 일반적으로 컨테이너화 및 버전 관리되는 구성 파일을 통해 관리됩니다.\n\n**파일**: `principles/development-process/fixed-environment.md`\n\n```markdown\n# 원칙: 개발 환경은 고정되어야 한다\n\n**태그**: 개발 프로세스, 환경, 일관성\n\n---\n\n## 1. 핵심 정의\n\n> 모든 팀원과 CI/CD 파이프라인이 사용하는 개발 환경(운영체제, 언어 버전,\n> 라이브러리, 도구 등 포함)은 완전히 동일해야 하며, 이는 코드로 명확하게 정의되고\n> 관리되어야 합니다.\n\n## 2. 근거 (왜?)\n\n\"제 컴퓨터에서는 잘 되는데요\"는 개발에서 가장 흔하고 파괴적인 문제 중 하나입니다.\n개발 환경이 다르면 동일한 코드가 각 환경에서 다르게 동작하여 예측할 수 없는\n버그로 이어질 수 있습니다. 개발 환경을 코드로 정의하고 고정함으로써, 모든\n팀원과 자동화 시스템이 정확히 동일한 환경에서 코드를 실행하도록 보장할 수\n있습니다. 이는 새로운 팀원의 온보딩 시간을 극적으로 단축시키고, 빌드\n재현성을 보장하며, 환경 차이로 인한 버그를 근본적으로 방지합니다.\n\n- _\"내 컴퓨터에서는 되는데\" 문제를 완전히 제거합니다._\n- _새로운 팀원이 프로젝트에 빠르게 기여할 수 있도록 돕습니다._\n- _모든 빌드가 예측 가능하고 일관된 결과를 내도록 보장합니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **컨테이너화 기술 사용하기**: Docker와 같은 컨테이너 기술을 사용하여 OS부터 모든\n 의존성을 포함하는 개발 환경 이미지를 만듭니다.\n- **환경 정의 파일 버전 관리하기**: `Dockerfile`, `docker-compose.yml`,\n `.tool-versions`, 그리고 의존성 잠금 파일(`package-lock.json`, `poetry.lock` 등)과\n 같은 환경 정의 파일들을 소스 코드와 함께 버전 관리 시스템에 포함시킵니다.\n- **스크립트로 환경 설정 자동화하기**: 개발 환경 설정의 모든 단계를 위한 자동화된\n 스크립트를 제공하여, 단일 명령어로 환경을 구성할 수 있게 합니다.\n\n### 금지 사항 (Don't)\n\n- **수동 설치 가이드에 의존하지 않기**: README 파일에 \"Node.js 16.x 버전 설치\"와\n 같이 모호하고 수동적인 설치 절차를 나열하지 않습니다.\n- **개발자 로컬 환경에 의존하지 않기**: 각 개발자의 머신에 이미 설치된 전역 도구나\n 라이브러리에 의존하는 코드를 작성하지 않습니다.\n- **OS나 아키텍처를 가정하지 않기**: 코드가 특정 운영체제(예: macOS)나 CPU\n 아키텍처(예: x86)에서만 실행될 것이라고 가정하지 않습니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 코드로 정의된 개발 환경 (Dockerfile)\n\n```dockerfile\n# Dockerfile\n\n# 1. OS와 언어의 특정 버전을 명시\nFROM node:18.17.1-slim\n\n# 2. 작업 디렉토리 설정\nWORKDIR /app\n\n# 3. 캐싱을 활용하기 위해 의존성 잠금 파일을 먼저 복사\nCOPY package-lock.json ./\n\n# 4. 정의된 버전으로 의존성 설치\nRUN npm ci\n\n# 5. 소스 코드 복사\nCOPY . .\n\n# 6. 실행 명령어 정의\nCMD [ \"npm\", \"start\" ]\n\n# -> 이 Dockerfile 하나만 있으면 누구나 `docker build`와 `docker run` 명령어로\n# 즉시 100% 동일한 환경을 구성하고 실행할 수 있습니다.\n```\n\n### 나쁜 예시: 수동 설치 절차에 의존하는 환경\n\n```markdown\n# README.md\n\n## 개발 환경 설정\n\n1. Ubuntu 22.04 또는 최신 버전의 macOS를 준비합니다.\n2. Node.js 18 버전을 설치합니다. (nvm 사용 권장)\n3. `npm install` 명령어를 실행하여 의존성을 설치합니다.\n4. `npm start`로 애플리케이션을 실행합니다.\n\n// -> Node.js의 정확한 패치 버전이 다를 수 있어 라이브러리 호환성 문제를 일으킬 수 있습니다.\n// -> `npm install` 결과는 개발자의 OS나 기존 설정에 따라 달라질 수 있습니다.\n// -> 새로운 팀원은 환경 설정에 많은 시간을 낭비하게 됩니다.\n```\n\n```\n\n#### 3. '필수 코드 리뷰' 원칙 문서 생성\n\n이 작업은 모든 코드 변경에 대해 의무적인 동료 리뷰를 확립하는 문서를 생성합니다. 이 원칙은 핵심적인 품질 게이트이자 지식 공유 메커니즘입니다. 코드가 두 번째 눈으로 확인되기 전에 병합되지 않도록 보장하여 코드 품질을 향상시키고, 일관성을 유지하며, 코드베이스에 대한 공동 소유권을 육성합니다.\n\n**파일**: `principles/development-process/mandatory-code-reviews.md`\n\n```markdown\n# 원칙: 모든 코드는 동료 리뷰 후 병합된다\n\n**태그**: 개발 프로세스, 코드 리뷰, 품질, 협업\n\n---\n\n## 1. 핵심 정의\n\n> 어떤 코드도 작성자 본인의 단독 판단으로 메인 브랜치에 병합될 수 없습니다. 모든\n> 코드는 최소 한 명 이상의 다른 동료 개발자에게 리뷰를 받고 승인을 받아야 합니다.\n\n## 2. 근거 (왜?)\n\n코드 리뷰는 단순히 버그를 찾는 것 이상의 의미를 가지며, 팀의 전반적인 코드 품질을\n향상시키고 지식을 공유하는 핵심적인 협업 과정입니다. 다른 사람의 관점은 작성자가\n놓쳤을 수 있는 논리적 오류, 엣지 케이스, 더 나은 설계 방식을 발견하는 데 도움을\n줍니다. 또한, 코드 리뷰 과정을 통해 팀원들은 서로의 코드에 익숙해지며 특정 코드에\n대한 정보가 한 사람에게만 국한되는 지식 사일로(knowledge silo) 현상을 방지합니다.\n이는 프로젝트의 장기적인 유지보수성을 크게 향상시킵니다.\n\n- _잠재적인 결함을 조기에 발견하여 품질을 향상시킵니다._\n- _팀 전체에 걸쳐 일관된 코드 스타일과 설계 원칙을 유지합니다._\n- _코드와 시스템에 대한 지식을 팀 전체에 공유하여 공동 코드 소유권을 강화합니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **풀 리퀘스트(PR) 활용하기**: 모든 코드 변경 사항을 풀 리퀘스트(또는 병합 요청)를\n 통해 제출하고, 리뷰어를 지정하여 코드 리뷰를 요청합니다.\n- **리뷰 가능한 작은 단위로 제출하기**: 한 번에 수천 줄의 코드를 리뷰 요청하는\n 대신, 작고 논리적으로 완결된 단위로 변경 사항을 제출합니다.\n- **건설적인 피드백 제공하기**: 리뷰어는 비난이 아닌 대안을 제시하는 건설적인\n 피드백을 제공하고, 피리뷰어는 열린 마음으로 피드백을 수용해야 합니다.\n\n### 금지 사항 (Don't)\n\n- **셀프 병합(Self-Merging) 금지**: 아무리 작은 변경이라도 리뷰 없이 자신의\n 변경 사항을 병합하지 않습니다. (사전에 합의된 예외적인 경우 제외).\n- **리뷰 요청 방치 금지**: 리뷰 요청을 보낸 후 피드백만 기다리지 말고, 리뷰어가\n 쉽게 이해할 수 있도록 코드의 배경과 목적을 충분히 설명합니다.\n- **리뷰 장시간 지연 금지**: 다른 사람의 리뷰 요청을 오랫동안 방치하여 개발\n 프로세스를 막지 않습니다. 코드 리뷰는 높은 우선순위를 가집니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 풀 리퀘스트를 통한 코드 리뷰 프로세스\n\n```plaintext\n// 1. 기능 개발 완료 후, 'feature/add-user-login' 브랜치를 원격 저장소에 푸시합니다.\n\n// 2. GitHub에서 'main' 브랜치를 대상으로 풀 리퀘스트(PR)를 생성합니다.\n// - PR 제목: \"Feat: 사용자 로그인 기능 추가\"\n// - PR 본문:\n// - 이 기능이 해결하려는 문제를 설명합니다.\n// - 구현의 핵심 로직을 요약합니다.\n// - 리뷰어가 집중해서 봐주었으면 하는 부분을 명시합니다.\n// - 관련 이슈 번호를 링크합니다 (예: Closes #123).\n\n// 3. 동료 개발자 두 명을 리뷰어로 지정합니다.\n\n// 4. 리뷰어들이 질문이나 개선 제안이 담긴 코멘트를 남깁니다.\n\n// 5. 작성자는 피드백을 바탕으로 코드를 수정하고 다시 푸시합니다.\n\n// 6. 모든 논의가 해결되고 최소 한 명 이상의 리뷰어가 승인하면 PR이 병합됩니다.\n```\n\n### 나쁜 예시: 리뷰 없이 메인 브랜치에 직접 푸시하기\n\n```plaintext\n// 개발자가 로컬 'main' 브랜치에서 중요한 결제 관련 로직을 수정했습니다.\n\n// git add .\n// git commit -m \"결제 로직 긴급 수정\"\n// git push origin main\n\n// -> 아무런 리뷰 없이 코드가 프로덕션에 배포될 수 있는 위험한 상태입니다.\n// -> 만약 코드에 논리적 오류가 있었다면, 아무도 모르는 사이에 배포되었을 것입니다.\n// -> 다른 팀원들은 이 변경이 이루어졌다는 사실조차 파악하기 어렵습니다.\n// -> 프로젝트의 안정성과 신뢰도가 심각하게 훼손됩니다.\n```\n\n```\n\n---\n### 4단계: 코드 품질 원칙 문서 (Fail-fast, 보이스카우트 규칙).\n\n#### 1. 'Fail-Fast' 원칙 문서 생성\n\n이 작업은 \"Fail-Fast\" 원칙에 대한 문서를 생성합니다. 이는 시스템이 유효하지 않은 상태로 계속 진행하는 대신 오류를 즉시 보고하고 실행을 중단해야 함을 의무화합니다. 이 관행은 문제의 정확한 위치를 찾아내어 디버깅을 대폭 단순화하고 오류 전파를 중단시켜 데이터 손상을 방지합니다.\n\n**파일**: `principles/development-process/fail-fast.md`\n\n```markdown\n# 원칙: 조용한 실패 대신, 빠르게 실패하고 오류를 명확히 드러내라\n\n**태그**: 개발 프로세스, 오류 처리, 안정성\n\n---\n\n## 1. 핵심 정의\n\n> 문제가 발생했을 때, 오류를 무시하고 불확실한 상태로 실행을 계속하는 대신, 즉시\n> 실행을 멈추고 오류의 원인을 명확하게 보고해야 합니다.\n\n## 2. 근거 (왜?)\n\n'조용한 실패(Silent Failure)'는 오류가 발생한 지점과 멀리 떨어진 곳에서 예기치 않은\n동작으로 나타나기 때문에 버그를 가장 찾기 어렵게 만듭니다. '빠른 실패(Fail-Fast)'는\n문제가 발생한 위치에서 즉시 시스템을 멈춤으로써 디버깅 과정을 극적으로\n단순화합니다. 이는 문제 원인의 신속한 파악과 수정으로 이어지며, 잘못된 데이터가\n시스템의 다른 부분으로 전파되어 더 큰 문제를 일으키는 것을 방지합니다.\n\n- _버그 발생 즉시 원인을 파악하여 디버깅 시간을 단축시킵니다._\n- _유효하지 않은 상태가 시스템 전체로 퍼지는 것을 막아 2차, 3차 피해를\n 예방합니다._\n- _코드의 계약을 명확히 하고 시스템의 안정성과 예측 가능성을 높입니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **단언(Assertions) 사용하기**: 함수 시작 부분에서 단언을 사용하여 매개변수나 시스템\n 상태가 유효한지 검사합니다.\n- **Null 값 확인하기**: 포인터나 객체를 사용하기 전에 항상 null이 아닌지 확인하고,\n null이라면 즉시 예외를 던집니다.\n- **예외(Exceptions) 활용하기**: 복구할 수 없는 오류가 발생했을 때, 오류 코드를\n 반환하는 대신 예외를 던져 정상적인 실행 흐름을 멈춥니다.\n\n### 금지 사항 (Don't)\n\n- **빈 catch 블록 사용 금지**: 예외를 잡고 아무것도 하지 않는 것은 오류를 숨기는\n 최악의 방법입니다. 최소한 로그라도 남겨야 합니다.\n- **null 반환 남용 금지**: 오류 발생 시 null을 반환하는 패턴은 호출자가 null\n 체크를 잊기 쉬워 NullPointerException으로 이어지는 경우가 많습니다.\n- **기본값으로 오류 덮어쓰기 금지**: 유효하지 않은 입력에 대해 임의의 기본값으로\n 처리를 계속하지 않습니다. 이는 문제의 본질을 숨길 뿐입니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 빠른 실패 (Fail-Fast)\n\n```plaintext\nfunction processUser(user)\n // 함수의 진입점에서 계약을 확인하고 위반 시 즉시 실패.\n assert(user is not null, \"User cannot be null\")\n\n // ... user를 사용하는 로직 ...\nend function\n\nfunction divide(a, b)\n if b is 0 then\n // 0으로 나누는 것은 복구 불가능한 오류이므로, 즉시 멈추기 위해 예외를 던진다.\n throw InvalidArgumentException(\"Divisor cannot be zero.\")\n end if\n\n return a / b\nend function\n```\n\n### 나쁜 예시: 조용한 실패 (Silent Failure)\n\n```plaintext\nfunction processUser(user)\n // null 입력에 대한 검사 없이 로직을 진행.\n // 나중에 user.getName() 같은 코드에서 런타임 오류가 발생하겠지만,\n // 원인을 찾기 위해 상당한 디버깅이 필요할 것이다.\n // ...\nend function\n\nfunction divide(a, b)\n if b is 0 then\n // 오류를 무시하고 임의의 값(0)을 반환.\n // 이 함수를 호출하는 쪽에서는 0이 올바른 결과인지 오류인지 구분할 수 없다.\n return 0\n end if\n\n return a / b\nend function\n```\n\n```\n\n#### 2. '보이스카우트 규칙' 원칙 문서 생성\n\n이 작업은 \"보이스카우트 규칙\"(\"항상 코드를 처음 봤을 때보다 더 좋게 남겨두라\")을 정의하는 문서를 생성합니다. 이 원칙은 코드베이스의 지속적이고 점진적인 개선을 촉진합니다. 모든 개발자가 정규 작업 중에 작은 리팩토링을 수행하도록 권한을 부여하여 기술 부채 축적을 방지하고 공동의 코드 품질 소유권 문화를 조성합니다.\n\n**파일**: `principles/development-process/boy-scout-rule.md`\n\n```markdown\n# 원칙: 항상 처음 봤을 때보다 코드를 더 좋게 남겨두라 (보이스카우트 규칙)\n\n**태그**: 개발 프로세스, 리팩토링, 코드 품질\n\n---\n\n## 1. 핵심 정의\n\n> 캠프장을 처음 발견했을 때보다 더 깨끗하게 떠나야 한다는 보이스카우트 규칙처럼,\n> 코드를 수정한 후에는 원래보다 더 읽기 쉽고, 구조가 좋으며, 깨끗하게 남겨두어야\n> 합니다.\n\n## 2. 근거 (왜?)\n\n소프트웨어는 끊임없이 변화하며, 시간이 지남에 따라 코드베이스는 자연스럽게 더\n복잡해지고 품질이 저하되는 경향(엔트로피 증가)이 있습니다. 보이스카우트 규칙은 모든\n팀원이 코드를 수정할 때 작은 개선이라도 하도록 장려하여, 코드베이스 전체의 품질이\n점진적이고 지속적으로 향상되도록 보장합니다. 이는 대규모 리팩토링의 부담을\n줄여주고, 기술 부채가 쌓이는 것을 방지하며, 모든 팀원에게 코드 품질에 대한 공동의\n책임감을 심어줍니다.\n\n- _시간이 지남에 따라 코드베이스가 자연스럽게 개선됩니다._\n- _기술 부채가 눈덩이처럼 불어나는 것을 방지합니다._\n- _모든 팀원에게 코드 품질에 대한 주인의식을 심어줍니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **작은 개선에 집중하기**: 버그를 수정하거나 기능을 추가할 때, 명확성을 위해 변수\n 이름을 바꾸거나 작은 함수를 추출하는 등의 소소한 리팩토링을 수행합니다.\n- **중복 제거하기**: 수정 중인 코드 주변에서 명백한 코드 중복을 발견하면 즉시\n 제거합니다.\n- **가독성 향상시키기**: 이해하기 어려운 코드 블록이 있다면, 구조를 개선하거나\n 주석을 추가하여 다른 사람이 이해하기 쉽게 만듭니다.\n- **불필요한 요소 제거하기**: 사용되지 않는 변수나 불필요한 주석을 과감히\n 삭제합니다.\n\n### 금지 사항 (Don't)\n\n- **대규모 리팩토링 금지**: 현재 작업 범위와 관련 없는 대규모 리팩토링을 하나의\n 커밋에 포함시키지 않습니다. 이는 코드 리뷰를 어렵게 하고 버그 추적을 방해합니다.\n- **스타일 강요 금지**: 자신의 개인적인 코딩 스타일과 다르다는 이유만으로 코드를\n 변경하지 않습니다. 개선은 객관적인 품질 향상에 초점을 맞춰야 합니다.\n- **테스트 없는 리팩토링 금지**: 리팩토링 전후에 반드시 테스트를 실행하여 기존\n 기능이 깨지지 않았음을 보장해야 합니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 작은 개선을 함께하기\n\n```plaintext\n// 버그 수정 요청: 중간 이름이 없을 경우 사용자의 전체 이름을 반환할 때 불필요한 공백이 추가되는 문제 수정.\n\n// 수정 전\nfunction getUserFullName(firstName, middleName, lastName)\n // 이 함수는 모호한 변수명(n1, n2, n3)과 복잡한 구조를 가지고 있다.\n let n1 = firstName\n let n2 = middleName\n let n3 = lastName\n return n1 + \" \" + n2 + \" \" + n3\nend function\n\n// 수정 후 (보이스카우트 규칙 적용)\nfunction getUserFullName(firstName, middleName, lastName)\n // 1. 버그를 수정하면서 변수명을 더 명확하게 변경했다.\n // 2. 중간 이름이 없는 경우를 처리하는 로직을 추가하여 코드의 안정성을 높였다.\n let fullName = firstName\n if middleName is not empty then\n fullName += \" \" + middleName\n end if\n fullName += \" \" + lastName\n return fullName.trim() // 불필요한 공백 제거\nend function\n```\n\n### 나쁜 예시: 필요한 수정만 하기\n\n```plaintext\n// 버그 수정 요청: 위와 동일\n\n// 수정 후\nfunction getUserFullName(firstName, middleName, lastName)\n // 변수명은 여전히 모호하고, 코드 구조는 개선되지 않았다.\n // 오직 버그만 수정되었을 뿐, 코드는 더 나아지지 않았다.\n let n1 = firstName\n let n2 = middleName\n let n3 = lastName\n if n2 is empty then\n return n1 + \" \" + n3\n else\n return n1 + \" \" + n2 + \" \" + n3\n end if\nend function\n```\n\n```\n\n---\n### 5단계: 커밋 및 빌드 안정성 원칙 문서.\n\n#### 1. '깨진 커밋 금지' 원칙 문서 생성\n\n이 작업은 마지막 원칙 문서인 \"깨진 커밋을 푸시하지 마라\"를 생성합니다. 이 규칙은 팀 협업과 생산성에 매우 중요합니다. 중앙 저장소에 푸시되는 모든 커밋은 안정적이고 실행 가능한 상태여야 함을 의무화하여, 메인 브랜치가 항상 신뢰할 수 있고 다른 개발자의 불안정한 변경으로 인해 워크플로가 막히지 않도록 보장합니다.\n\n**파일**: `principles/development-process/no-broken-commits.md`\n\n```markdown\n# 원칙: 깨진 커밋을 푸시하지 마라\n\n**태그**: 개발 프로세스, 안정성, 협업\n\n---\n\n## 1. 핵심 정의\n\n> 모든 커밋은 안정적이고 실행 가능한 상태를 유지해야 하며, 빌드를 깨뜨리거나 핵심\n> 기능을 동작하지 않게 만드는 변경을 포함해서는 안 됩니다.\n\n## 2. 근거 (왜?)\n\n이 원칙은 팀 전체의 생산성을 보호하기 위해 필수적입니다. 만약 깨진 코드가 중앙\n저장소에 푸시되면, 다른 팀원들이 그 코드를 기반으로 작업을 진행할 수 없게 되어\n개발 워크플로가 중단됩니다. 이는 즉시 다른 사람들의 시간을 낭비하게 하고, 버그의\n원인을 추적하기 어렵게 만듭니다. 모든 커밋이 안정적인 상태를 보장할 때, 누구나\n안심하고 최신 코드를 내려받아 작업을 이어갈 수 있으며, 코드베이스는 항상 예측\n가능하고 신뢰할 수 있는 상태로 유지됩니다.\n\n- _팀 전체의 개발 중단을 막아 생산성을 유지합니다._\n- _다른 팀원들이 불안정한 코드 위에서 작업하는 것을 막아 잠재적인 버그를\n 줄입니다._\n- _코드베이스가 항상 안정적인 상태로 유지되어 신뢰도를 높입니다._\n- _자동화된 빌드 및 테스트 파이프라인의 효율성을 보장합니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **푸시 전 항상 로컬에서 테스트하기**: 중앙 저장소에 코드를 푸시하기 전에, 최소한\n 전체 빌드가 성공하고 주요 테스트 스위트가 통과하는지 로컬에서 확인합니다.\n- **기능 브랜치 활용하기**: 새로운 기능이나 큰 변경 사항은 별도의 브랜치에서\n 작업하고, 충분히 안정화된 후에 메인 브랜치에 통합합니다.\n- **CI (지속적 통합) 구축하기**: 푸시된 코드를 자동으로 빌드하고 테스트하는 CI\n 시스템을 도입하여 문제가 발생했을 때 즉각적인 피드백을 받습니다.\n- **작업 단위를 작게 유지하기**: 관련된 변경 사항을 작은 단위의 커밋으로 묶으면\n 문제가 발생했을 때 원인을 찾고 수정하기가 더 쉽습니다.\n\n### 금지 사항 (Don't)\n\n- **\"나중에 고칠게\"라는 생각으로 푸시 금지**: 사소해 보이더라도 해결되지 않은 문제가\n 있는 코드를 푸시하지 않습니다. 그 문제는 다른 사람에게는 사소하지 않을 수\n 있습니다.\n- **컴파일조차 안 되는 코드 푸시 금지**: 이는 협업의 기본을 무시하는 행위이며, 팀\n 전체의 작업을 마비시킬 수 있습니다.\n- **테스트 비활성화 후 푸시 금지**: 기존 테스트를 통과하지 못한다는 이유로\n 일시적으로 테스트를 비활성화하고 코드를 푸시해서는 안 됩니다.\n\n## 4. 코드 예시\n\n이 원칙은 특정 코드 스타일보다는 개발 워크플로와 더 관련이 있으므로, 코드 예시\n대신 상황별 예시로 설명합니다.\n\n### 좋은 예시: 원칙을 준수하는 워크플로\n\n```plaintext\n// 1. 로컬에서 새로운 기능 개발 및 테스트 완료\n$ git checkout -b new-feature\n// ... 코드 수정 ...\n$ make build && make test\n// 모든 테스트 통과 확인\n\n// 2. 메인 브랜치의 최신 변경 사항을 통합하고 다시 테스트\n$ git fetch origin\n$ git rebase origin/main\n$ make build && make test\n// 통합 후에도 모든 테스트 통과 확인\n\n// 3. 중앙 저장소에 푸시\n$ git push origin new-feature\n```\n\n### 나쁜 예시: 원칙을 위반하는 워크플로\n\n```plaintext\n// 동료 A가 컴파일 에러가 있는 코드를 푸시함\n$ git commit -am \"WIP: 작업 중인 기능\"\n$ git push origin main // 컴파일 에러가 있는 코드가 메인 브랜치에 푸시됨\n\n// 동료 B가 작업을 위해 최신 코드를 받음\n$ git pull origin main\n// 로컬 환경에서 빌드 실패. 동료 A가 코드를 고칠 때까지 작업 중단.\n$ make build\n// ... 컴파일 에러 발생 ...\n```\n\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 이 과업의 성공적인 완료를 검증하기 위해, 개발자는 프로젝트의 포맷팅 및 린팅 스크립트를 실행해야 합니다. 이는 새로 생성된 모든 마크다운 파일이 정의된 코딩 스타일 표준을 준수하는지 확인합니다.\n\n```bash\n# 1. 프로젝트 루트 디렉토리로 이동\ncd /path/to/readable-code-cpp-development-guidelines\n\n# 2. 포맷터 스크립트를 실행 가능하게 만듭니다 (아직 안 했다면)\nchmod +x scripts/executables/run_formatters.sh\n\n# 3. 포맷터 및 린터 스크립트 실행\n./scripts/executables/run_formatters.sh\n```\n\n### 4.2. 예상 결과\n\n- 스크립트는 아무런 오류 없이 실행되어야 합니다. 출력은 새로 생성된 원칙 문서를 포함한 모든 파일이 검사되었고 올바르게 포맷되었음을 확인해야 합니다. 성공적인 실행은 다음과 유사한 출력을 생성하며, 린팅 오류가 보고되지 않아야 합니다.\n\n```\nRunning Prettier formatter...\n[info] principles/development-process/automate-pipelines.md\n[info] principles/development-process/boy-scout-rule.md\n[info] principles/development-process/fail-fast.md\n... (다른 파일들) ...\n[info] All matched files use Prettier code style!\n\nRunning markdownlint...\nAll markdown files are valid.\nFormatters executed successfully.\n```","구현부터 코드 리뷰까지 전체 개발 라이프사이클을 다루는 포괄적인 원칙 세트",[106,108,110,112,114],{"_24":107,"_83":39,"_84":88,"_85":61},"YAGNI, KISS, '작동하게 만든 후, 올바르게 만들기' 원칙 문서",{"_24":109,"_83":39,"_84":88,"_85":88},"테스팅 및 최적화 원칙 문서 (최적화 전 측정, 디버깅 대신 테스트)",{"_24":111,"_83":39,"_84":88,"_85":91},"자동화, 환경, 코드 리뷰 원칙 문서",{"_24":113,"_83":39,"_84":88,"_85":94},"코드 품질 원칙 문서 (Fail-fast, 보이스카우트 규칙)",{"_24":115,"_83":39,"_84":88,"_85":97},"커밋 및 빌드 안정성 원칙 문서","개발 워크플로와 표준 관행을 규정하는 문서를 작성",{"_22":118,"_24":119,"_75":120,"_77":121,"_79":122,"_51":133,"_42":99},"task-1751363079612","이름 및 서식 원칙 문서","# 태스크: 이름짓기 및 형식화 원칙 문서\n\n> **에픽**: 개발 기반 원칙 수립\n\n## 1. 태스크 정의\n\n### 1.1. 목표\n\n- **목표**: 언어에 구애받지 않는 이름짓기 및 형식화 원칙 정의\n- **근거**: 이 태스크는 `readable-code-cpp-development-guidelines` 리포지토리 내 모든 코드와 문서의 기초 문법을 수립합니다. 이름짓기와 형식화에 대한 모호하지 않고 언어에 구애받지 않는 규칙들을 만듦으로써, \"소프트웨어 엔지니어링 원칙 공식화\"라는 프로젝트의 핵심 목표를 직접적으로 지원합니다. 이 원칙들은 이후 모든 언어별 가이드라인과 자동화 도구 설정의 기준이 되는 단일 소스(single source of truth) 역할을 하여, 프로젝트 전반의 일관성을 보장하고, 가독성을 높이며, 개발자의 인지 부하를 줄여줄 것입니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 모호하지 않은 이름을 만들고 일관된 코드 형식을 유지하기 위한 명확한 규칙 모음\n- **명세**: `principles/` 디렉터리 내에 13개의 새로운 마크다운 문서가 생성됩니다. 각 문서는 이름짓기 또는 형식화와 관련된 특정 원칙을 정의합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── principles/\n# ├── formatting/\n# │ ├── formatting-is-a-rule.md <-- 신규\n# │ ├── newline-at-eof.md <-- 신규\n# │ ├── no-unnecessary-alignment.md <-- 신규\n# │ ├── no-unnecessary-whitespace.md <-- 신규\n# │ └── use-auto-formatters.md <-- 신규\n# └── naming/\n# ├── clear-and-objective-names.md <-- 신규\n# ├── enforce-naming-conventions.md <-- 신규\n# ├── name-active-objects-as-verb-er.md <-- 신규\n# ├── name-functions-as-verbs.md <-- 신규\n# ├── name-passive-objects-as-nouns.md <-- 신규\n# ├── no-ambiguous-abbreviations.md <-- 신규\n# ├── no-meaningless-names.md <-- 신규\n# └── no-subjective-names.md <-- 신규\n```\n\n- **프로세스 흐름도**\n (이 다이어그램은 이 태스크에서 생성된 원칙이 다른 시스템 구성요소의 기반이 되는 방식을 보여줍니다.)\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"태스크: 이름짓기 및 형식화 원칙\"\n A[\"이름짓기 원칙 문서 생성\"]\n B[\"형식화 원칙 문서 생성\"]\n end\n\n subgraph \"소비 주체\"\n C[\"언어별 가이드라인
(예: C++, Shell)\"]\n D[\"자동화 도구
(예: clang-format, Prettier)\"]\n end\n\n A --> C\n A --> D\n B --> C\n B --> D\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 태스크를 완료로 표시하기 위해 다음 항목들을 완수해야 합니다. 이것은 개괄적인 체크리스트이며, 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] 명확성과 객관성을 위한 일반적인 이름짓기 원칙 문서\n- [ ] 수동 객체, 능동 객체, 함수에 대한 구체적인 이름짓기 규칙\n- [ ] 무의미하거나, 주관적이거나, 모호한 이름에 대한 금지 규칙\n- [ ] 일반적인 형식화 원칙 (취향이 아닌 규칙, 자동화)\n- [ ] 공백 및 파일 끝에 대한 구체적인 형식화 규칙\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 리포지토리\n- **관련 주요 구성요소**:\n - **엔지니어링 원칙**: 이 태스크의 영향을 받는 주요 구성요소입니다. 새로운 마크다운 파일들은 이 구성요소를 직접 채우며, 전체 프로젝트의 근본적이고 언어에 구애받지 않는 규칙들을 정의하는 역할을 합니다. 이 태스크는 이 원칙들의 이름짓기 및 형식화 섹션의 핵심 내용을 구성합니다.\n - **언어별 가이드라인**: 이 구성요소는 이 태스크에서 생성된 원칙들을 소비하게 됩니다. 향후 C++, Shell 및 기타 언어에 대한 스타일 가이드는 이러한 기초 규칙들을 참조하여 언어별 컨벤션을 도출할 것입니다.\n - **자동화 도구**: 이 구성요소는 이 태스크의 원칙들을 기계가 읽을 수 있는 설정으로 성문화할 것입니다. 예를 들어, `.clang-format` 및 `.prettierrc` 파일은 여기서 수립된 형식화 원칙에 따라 설정될 것입니다.\n\n### 2.2. 영향받는 파일\n\n이 태스크를 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `principles/naming/clear-and-objective-names.md`\n- `principles/naming/name-passive-objects-as-nouns.md`\n- `principles/naming/name-active-objects-as-verb-er.md`\n- `principles/naming/name-functions-as-verbs.md`\n- `principles/naming/no-meaningless-names.md`\n- `principles/naming/no-ambiguous-abbreviations.md`\n- `principles/naming/no-subjective-names.md`\n- `principles/naming/enforce-naming-conventions.md`\n- `principles/formatting/formatting-is-a-rule.md`\n- `principles/formatting/use-auto-formatters.md`\n- `principles/formatting/no-unnecessary-alignment.md`\n- `principles/formatting/no-unnecessary-whitespace.md`\n- `principles/formatting/newline-at-eof.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 1단계: 명확성과 객관성을 위한 일반적인 이름짓기 원칙 문서\n\n#### 1. 파일 생성: `principles/naming/clear-and-objective-names.md`\n\n이 작업은 모든 이름이 객관적이고 모호하지 않아야 한다는 핵심 원칙을 수립합니다. 이는 주관적인 해석을 배제하기 위해 설계된 기초 규칙으로, 주관적 해석은 버그를 유발하고 코드를 이해하는 데 필요한 인지 부하를 증가시킬 수 있습니다. 명확하고 사실 기반의 이름짓기를 강제함으로써 코드가 스스로를 문서화하게 만들어, 프로젝트의 주요 목표인 가독성을 높이는 데 기여합니다.\n\n**파일**: `principles/naming/clear-and-objective-names.md`\n\n```markdown\n# 원칙: 이름은 의도와 목적을 명확히 드러내도록 객관적이고 모호하지 않아야 한다\n\n**태그**: 이름짓기, 명확성, 가독성\n\n---\n\n## 1. 핵심 정의\n\n> 변수, 함수, 클래스의 이름은 주관적인 표현을 배제하고, 누구나 그 역할과\n> 데이터의 의미를 동일하게 해석할 수 있도록 명확하게 작성해야 한다.\n\n## 2. 근거 (왜?)\n\n모호하거나 주관적인 이름은 읽는 사람마다 다르게 해석할 여지를 남긴다. 이는\n잘못된 가정하에 코드가 수정될 때 오해를 낳고 잠재적인 버그를 유발할 수 있다.\n만약 코드의 동작을 이름만으로 예측할 수 있다면, 불필요한 코드 분석 시간을\n줄이고 생산성을 높이며, 코드를 이해하려는 동료 개발자의 인지 부하를 크게 낮출\n수 있다. 명확한 이름은 그 자체로 최고의 문서다.\n\n- _코드의 의도를 명확히 전달하여 오해의 소지를 없앤다._\n- _이름만으로 코드의 동작을 유추할 수 있게 하여 가독성과 유지보수성을\n 향상시킨다._\n- _새로운 팀원이 시스템을 이해하는 데 걸리는 시간을 줄여준다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **구체적인 명사 사용**: 데이터의 의미를 정확하게 설명하는 구체적인 명사를\n 사용한다(예: `userList` 대신 `activeUsers`).\n- **측정 가능한 용어 사용**: 이름에 포함되는 정보는 측정 가능하고 객관적이어야\n 한다(예: `MAX_CONNECTIONS`, `REQUEST_TIMEOUT_MS`).\n- **전체 단어 사용**: 의미를 명확히 하기 위해 약어보다는 완전한 단어를\n 사용한다(예: `dest` 대신 `destination`).\n- **역할 표현**: 이름에 역할이나 단위를 포함하여 의미를 더 명확하게 만든다(예:\n `width` 대신 `widthInPixels`, `user` 대신 `loggedInUser`).\n\n### 금지 사항 (Don't)\n\n- **주관적인 형용사 사용 금지**: `beautiful`, `good`, `nice`처럼 사람마다\n 다르게 해석될 수 있는 주관적인 단어를 사용하지 않는다.\n- **모호한 약어 사용 금지**: 팀에서 합의되지 않은 모호한 약어는 혼란을 야기할 수\n 있다(예: `proc`이 `process`인지 `procedure`인지 불분명).\n- **데이터 타입만으로 이름짓기 금지**: `stringList`, `userMap`처럼 데이터\n 타입만으로 이름을 짓는 것은 변수의 실제 목적을 설명하지 못한다(예: `userMap`\n 대신 `usersById`).\n- **부정적인 이름 사용 금지**: `isNotEnabled`보다 `isDisabled`처럼 긍정적인\n 형태의 이름이 이해하기 더 쉽다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 객관적이고 명확한 이름\n\n```plaintext\n// 최대 사용자 로그인 시도 횟수. 이름만으로 그 의미와 제약 조건을 알 수 있다.\nconst MAX_LOGIN_ATTEMPTS = 5\n\n// 활성 사용자 목록. 'active'라는 상태가 명확히 드러난다.\nfunction getActiveUsers()\n // ...\nend function\n\n// 사용자 ID를 키로 사용하는 사용자 맵. 'ById' 접미사가 자료 구조를 명확히 설명한다.\nlet usersById = mapUsersById(userList)\n```\n\n### 나쁜 예시: 주관적이고 모호한 이름\n\n```plaintext\n// 'important'는 주관적이고 'data'는 너무 일반적이다.\n// 어떤 데이터가 왜 중요한지 알 수 없다.\nlet importantData = fetchData()\n\n// 'proc'이 무엇의 약어인지, 함수가 어떤 처리를 하는지 불분명하다.\nfunction proc(data)\n // ...\nend function\n\n// 'list'라는 이름은 변수가 리스트라는 사실 외에는 아무 정보도 주지 않는다.\n// 리스트에 무엇이 들어있는지 알 수 없다.\nlet list = getItems()\n```\n\n```\n\n#### 2. 파일 생성: `principles/naming/enforce-naming-conventions.md`\n\n이 문서는 이름짓기 컨벤션(예: `camelCase`, `PascalCase`)이 필수라는 규칙을 수립합니다. 이름짓기 컨벤션의 일관성은 개발자가 심볼(클래스, 함수, 변수)의 유형을 이름만으로 추론할 수 있게 해주어, 가독성을 극적으로 향상시키고 오류를 줄입니다. 이 원칙은 컨벤션을 선호 사항에서 규칙으로 격상시키며, 이는 대규모로 깨끗하고 전문적인 코드베이스를 유지하는 데 필수적입니다.\n\n**파일**: `principles/naming/enforce-naming-conventions.md`\n\n```markdown\n# 원칙: 이름짓기 컨벤션을 정의하고 엄격하게 준수한다\n\n**태그**: 이름짓기, 일관성, 팀워크\n\n---\n\n## 1. 핵심 정의\n\n> 프로젝트에서 사용할 변수, 함수, 클래스, 상수 등의 이름짓기 표기법(예:\n> camelCase, PascalCase, snake_case)과 규칙을 명확하게 정의하고, 모든 코드에\n> 예외 없이 일관되게 적용해야 한다.\n\n## 2. 근거 (왜?)\n\n이름짓기 컨벤션은 코드의 '문법'과 같다. 문법이 일관될 때 우리는 문장의 구조를\n더 쉽게 파악하고 내용에 집중할 수 있다. 마찬가지로 이름짓기 컨벤션이 일관되면,\n개발자는 이름의 형식만 보고도 그것이 클래스인지, 함수인지, 변수인지, 상수인지\n즉시 구별할 수 있다. 이는 코드 가독성을 극적으로 향상시키고 불필요한 추측과\n실수를 줄여준다. 컨벤션은 개인의 취향 문제가 아니라 팀 전체의 생산성과 코드\n품질을 위한 약속이다. 이 약속이 지켜지지 않으면 코드베이스는 순식간에 혼란스러워지고\n유지보수 비용이 치솟는다.\n\n- _이름의 형식만으로 코드 요소(클래스, 함수, 변수 등)를 구별할 수 있게\n 해준다._\n- _팀 전체의 코드 스타일을 통일하여 일관성을 보장한다._\n- _새로운 팀원이 코드에 적응하는 시간을 단축시킨다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **언어 표준 컨벤션 따르기**: 사용 중인 프로그래밍 언어의 표준 라이브러리나\n 커뮤니티에서 널리 사용되는 컨벤션을 우선적으로 따른다.\n- **프로젝트 규칙 문서화**: 팀의 이름짓기 규칙을 `CONTRIBUTING.md`나 위키와 같은\n 공유 문서에 명확하게 문서화한다.\n- **자동화 도구 활용**: 린터나 정적 분석 도구에 이름짓기 컨벤션 규칙을 설정하여\n 준수 여부를 자동으로 검사하고 강제한다.\n\n### 금지 사항 (Don't)\n\n- **개인 취향 고집하지 않기**: 팀이 결정한 컨벤션과 다르다는 이유만으로 자신의\n 스타일을 고수하지 않는다.\n- **여러 컨벤션 혼용 금지**: 하나의 파일이나 프로젝트 내에서 `camelCase`와\n `snake_case`를 비일관적으로 섞어 쓰지 않는다.\n- **잦은 예외 만들지 않기**: 특별한 이유 없이 컨벤션에 예외를 두기 시작하면\n 규칙은 금방 무너진다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 이름짓기 컨벤션의 일관된 적용\n\n```plaintext\n// 클래스, 구조체: PascalCase\nclass UserProfile {\n // 멤버 변수: snake_case\n string user_name\n integer user_age\n\n // 멤버 함수: camelCase\n function updateUserName(newName) {\n user_name = newName\n }\n}\n\n// 상수: ALL_CAPS_SNAKE_CASE\nconstant MAX_LOGIN_ATTEMPTS = 5\n\n// 전역 함수: snake_case\nfunction print_user_profile(profile) {\n // ...\n}\n```\n\n### 나쁜 예시: 여러 컨벤션의 혼용\n\n```plaintext\n// 클래스 이름에 snake_case 사용 (X)\nclass user_profile {\n // 멤버 변수에 camelCase와 PascalCase 혼용 (X)\n string userName\n integer UserAge\n\n // 멤버 함수에 PascalCase 사용 (X)\n function UpdateUserName(newName) {\n userName = newName\n }\n}\n\n// 상수에 camelCase 사용 (X)\nconstant maxLoginAttempts = 5\n\n// 전역 함수에 camelCase 사용 (X)\nfunction printUserProfile(profile) {\n // ...\n}\n```\n\n```\n\n---\n\n### 2단계: 수동 객체, 능동 객체, 함수에 대한 구체적인 이름짓기 규칙\n\n#### 1. 파일 생성: `principles/naming/name-passive-objects-as-nouns.md`\n\n이 원칙은 수동적인 데이터 컨테이너(변수, 필드 등)를 명사로 이름 지어야 한다고 정의합니다. 이는 데이터와 행위(함수)를 명확하게 구별합니다. 이 관행은 코드의 데이터 모델을 직관적으로 만들고 코드가 자연어 문장처럼 읽히게 하여 전반적인 가독성과 명확성을 향상시킵니다.\n\n**파일**: `principles/naming/name-passive-objects-as-nouns.md`\n\n```markdown\n# 원칙: 데이터를 나타내는 수동 객체(Passive Object)는 명사나 명사구를 사용한다\n\n**태그**: 이름짓기, 가독성, 데이터 모델링\n\n---\n\n## 1. 핵심 정의\n\n> 데이터를 담고 있는 변수, 상수, 클래스 필드와 같은 수동 객체(passive\n> object)의 이름은 그것이 '무엇'인지를 명확하게 설명하는 명사나 명사구여야\n> 한다.\n\n## 2. 근거 (왜?)\n\n데이터 객체의 본질은 '상태'나 '값'을 나타내는 것이다. 이름이 명사일 때, 코드를\n읽는 사람은 그 객체가 어떤 종류의 정보를 담고 있는지 즉시 파악할 수 있다. 만약\n데이터 객체에 `calculate`나 `process`와 같은 동사성 이름이 사용된다면, 그것이\n동작을 수행하는 함수인지 데이터를 담는 변수인지 혼란을 야기한다. 명확한 명사\n이름은 코드의 데이터 모델을 이해하기 쉽게 만들고 코드 전체의 가독성을 높인다.\n\n- _객체의 역할(데이터 저장)을 이름에서부터 명확히 구별해준다._\n- _코드가 잘 쓰인 문장처럼 자연스럽게 읽히도록 돕는다._\n- _데이터와 행위를 명확히 분리하여 코드 구조를 파악하기 쉽게 만든다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **단일 명사 사용**: `User`, `Product`, `Configuration`처럼 데이터의 실체를\n 나타내는 명사를 사용한다.\n- **명사구 사용**: `customerAddress`, `fileCreationTimestamp`처럼 여러 단어를\n 조합하여 더 구체적으로 설명하는 명사구를 사용한다.\n- **복수 명사 사용**: `users`, `orderItems`처럼 복수형 명사를 사용하여 컬렉션(배열,\n 리스트 등)임을 명확히 표현한다.\n\n### 금지 사항 (Don't)\n\n- **동사 포함 금지**: `processData`, `calculateResult`처럼 동작을 암시하는\n 동사를 데이터 객체 이름에 포함하지 않는다.\n- **일반적인 이름 회피**: `data`, `info`, `object`, `item`처럼 내용을 설명하기에\n 너무 일반적인 이름은 피한다.\n- **함수처럼 이름짓기 금지**: `getUsers`, `isComplete`와 같은 이름은 함수나 불리언\n 변수에 사용해야 하며, 일반 데이터 객체에는 사용하지 않는다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 명사/명사구를 사용한 이름\n\n```plaintext\n// 무엇을 담고 있는지 명확하다.\nclass UserProfile {\n string username\n string email\n}\n\n// 'List' 접미사나 복수형은 컬렉션임을 나타낸다.\nlet customerList = getCustomersFromDatabase()\nlet activeUsers = filterActiveUsers(allUsers)\n\n// 이름만으로 데이터의 구체적인 의미를 알 수 있다.\nconst documentTitle = \"Readable Code Guidelines\"\n```\n\n### 나쁜 예시: 부적절한 이름\n\n```plaintext\n// 'Compute'는 행위를 나타내므로 데이터 객체 이름으로 부적절하다.\nclass Compute {\n number value1\n number value2\n}\n\n// 'Get'은 함수의 역할이지, 데이터를 위한 이름이 아니다.\nlet getCustomers = fetchCustomers()\n\n// 'value'는 너무 일반적이어서 어떤 종류의 값인지 알 수 없다.\nlet value = \"Readable Code Guidelines\"\n```\n\n```\n\n#### 2. 파일 생성: `principles/naming/name-active-objects-as-verb-er.md`\n\n이 작업은 동작을 수행하는 활성 객체(클래스)에 대해 `동사-er` 이름짓기 패턴을 명시합니다. `Formatter`나 `Manager`와 같은 이름은 클래스의 책임을 즉시 전달합니다. 이는 관심사 분리를 장려하고 시스템의 아키텍처를 더 투명하게 만들어 좋은 객체 지향 설계를 촉진합니다.\n\n**파일**: `principles/naming/name-active-objects-as-verb-er.md`\n\n```markdown\n# 원칙: 동작을 수행하는 활성 객체(Active Object)는 '동사-er' 형태로 이름 지어 역할을 명확히 드러낸다\n\n**태그**: 이름짓기, 가독성, 객체 지향 설계\n\n---\n\n## 1. 핵심 정의\n\n> 데이터를 입력받아 특정 작업을 처리하고 결과를 반환하는 등, 능동적으로 동작을\n> 처리하는 객체(클래스)는 '그것이 무엇을 하는지'를 명확히 드러내도록 '동사-er'\n> 접미사를 붙여 이름 지어야 한다.\n\n## 2. 근거 (왜?)\n\n객체 지향 프로그래밍에서 객체는 종종 단순한 데이터 컨테이너(수동 객체) 이상의\n역할을 수행한다. 특정 로직을 캡슐화하고 동작을 책임지는 활성 객체가 있다. 이런\n활성 객체를 '동사-er' 형태(예: `Formatter`, `Manager`, `Controller`)로 이름 지으면\n클래스 이름만으로도 그것이 어떤 작업을 수행하고 어떤 책임을 가졌는지 명확해진다.\n이는 데이터와 행위를 분리하는 좋은 설계 관행을 장려하며 시스템의 구조를 이해하는\n데 큰 도움을 준다.\n\n- _클래스의 책임(동작 수행)을 이름에 명확히 드러낸다._\n- _수동적인 데이터 객체와 능동적인 행위 객체를 쉽게 구별할 수 있게 한다._\n- _객체 지향 설계에서 역할, 책임, 협력 관계를 파악하는 데 도움을 준다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **'동사-er' 패턴 사용**: `Formatter`, `Parser`, `Validator`, `Manager`,\n `Controller`처럼 동작 동사에 '-er'이나 '-or' 접미사를 붙여 클래스 이름을\n 짓는다.\n- **책임에 맞는 동사 선택**: 클래스가 수행하는 가장 핵심적인 책임을 나타내는\n 동사를 선택한다(예: 데이터를 관리하면 `Manager`, 형식을 바꾸면\n `Formatter`).\n- **단일 책임 원칙 준수**: '동사-er' 이름은 클래스가 하나의 명확한 책임을 가져야\n 함을 암시한다. 클래스에는 이름에 맞는 책임만 포함시킨다.\n\n### 금지 사항 (Don't)\n\n- **수동 객체에 적용 금지**: `User-er`처럼 단지 데이터를 담고 있는 객체에 '동사-er'\n 패턴을 적용하지 않는다.\n- **모호한 동사 사용 금지**: `Doer`, `Handler`, `Processor`처럼 구체적인 행위를\n 알 수 없는 너무 일반적인 동사는 피한다 (예: `DataHandler`보다 `JsonParser`가\n 더 명확하다).\n- **한 이름에 여러 책임 넣기 금지**: `ValidatorAndFormatter`처럼 한 이름에 여러\n 책임을 섞지 않는다. 이는 클래스가 여러 책임을 가지고 있어 분리해야 한다는\n 신호다.\n\n## 4. 코드 예시\n\n### 좋은 예시: '동사-er' 패턴을 사용한 이름\n\n```plaintext\n// JSON 문자열을 객체로 파싱하는 역할을 명확히 보여준다.\nclass JsonParser {\n function parse(jsonString)\n // ... 파싱 로직 ...\n return dataObject\n end function\n}\n\n// 사용자 인증을 관리하는 책임을 가진 클래스임을 보여준다.\nclass AuthenticationManager {\n function login(username, password)\n // ... 인증 로직 ...\n end function\n}\n```\n\n### 나쁜 예시: 역할이 불분명한 이름\n\n```plaintext\n// 'Util'이나 'Helper'는 구체적인 책임을 설명하지 않는 대표적인 나쁜 이름이다.\n// 어떤 유틸리티 함수가 제공되는지 알 수 없다.\nclass StringUtil {\n function format(template, data) { ... }\n function parse(string) { ... }\n}\n// -> 이는 StringFormatter와 StringParser로 분리하는 것이 좋다.\n\n// 'Data'는 너무 일반적이어서 어떤 데이터가 어떻게 처리되는지 알 수 없다.\nclass Data {\n function process(rawData)\n // ...\n end function\n}\n```\n\n```\n\n#### 3. 파일 생성: `principles/naming/name-functions-as-verbs.md`\n\n이 작업은 함수와 메서드가 동사구로 이름 지어져야 함을 의무화합니다. 이 컨벤션은 함수가 동작을 수행한다는 것을 명확하게 합니다. 이는 코드가 일련의 명령(예: `deleteUser(id)`)처럼 읽히게 하여, 로직 흐름을 더 쉽게 따라갈 수 있게 하고 잠재적인 부작용에 대한 예측 가능성을 향상시킵니다.\n\n**파일**: `principles/naming/name-functions-as-verbs.md`\n\n```markdown\n# 원칙: 함수와 메서드는 그 동작을 설명하는 동사구로 이름 짓는다\n\n**태그**: 이름짓기, 가독성, 함수 설계\n\n---\n\n## 1. 핵심 정의\n\n> 함수나 메서드의 이름은 '그것이 무엇을 하는지'를 명확하게 설명하는 동사나\n> 동사구로 시작해야 한다.\n\n## 2. 근거 (왜?)\n\n함수와 메서드의 본질은 '동작'을 수행하는 것이다. 이름이 동사구일 때, 코드를 읽는\n사람은 함수 호출만 보고도 어떤 연산이 일어날지 즉시 예측할 수 있다. `user.save()`라는\n코드는 `user` 객체의 상태를 저장하는 행위를 수행함을 명확히 나타낸다. 만약 함수\n이름이 `user.state`와 같은 명사였다면, 단순히 상태 값을 반환하는지 아니면 어떤\n내부 연산을 수행하는지 알려면 구현을 들여다봐야 했을 것이다. 동사로 시작하는\n이름은 코드 가독성을 높이고 부작용에 대한 예측 가능성을 제공한다.\n\n- _함수 호출이 어떤 동작을 수행하는지 명확하게 전달한다._\n- _코드가 자연스러운 명령어처럼 읽히게 하여 가독성을 향상시킨다._\n- _이름만으로 부작용의 유무를 유추할 수 있게 한다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **'동사-객체' 형태 사용**: `getUser()`, `calculateTotalPrice()`, `validateInput()`처럼\n '무엇으로 무엇을 하다' 형태의 이름을 사용한다.\n- **명령형 동사 사용**: `save(data)`, `deleteUser(userId)`처럼 객체에게 특정\n 동작을 수행하도록 명령하는 동사를 사용한다.\n- **상태 조회 접두사 사용**: `isEnabled()`, `hasPermission()`처럼 `is`, `has`,\n `can`과 같은 접두사를 사용하여 불리언 값을 반환하는 함수임을 명확히 한다.\n\n### 금지 사항 (Don't)\n\n- **명사만으로 이름짓기 금지**: `user()`나 `totalPrice()`처럼 명사만으로 함수\n 이름을 짓지 않는다. 이는 변수와 혼동을 일으킨다.\n- **모호한 동사 사용 금지**: `handleData()`나 `processItems()`처럼 구체적인\n 동작을 드러내지 않는 모호한 동사는 피한다. (예: `handleData` 대신\n `parseAndStoreData` 사용)\n- **무의미한 접미사 사용 금지**: `performCalculation()`에서 `perform`이라는 단어는\n 불필요하다. `calculate()`로 충분하다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 동작을 명확히 설명하는 동사구 이름\n\n```plaintext\n// 데이터베이스에서 사용자를 삭제하는 동작을 명확히 설명한다.\nfunction deleteUser(userId)\n // ...\nend function\n\n// 사용자의 이메일 주소를 반환(get)하는 것이 목적임이 명확하다.\nfunction getUserEmail(user)\n return user.email\nend function\n\n// 이 함수가 사용자가 관리자 권한을 가졌는지 확인한다는 것을 명확히 보여준다.\nfunction hasAdminPrivileges(user)\n return user.role == 'admin'\nend function\n```\n\n### 나쁜 예시: 역할이 불분명한 이름\n\n```plaintext\n// 'user'가 함수인지 변수인지 혼란스럽다.\n// 사용자를 생성하는지, 조회하는지, 수정하는지 불분명하다.\nfunction user(data)\n // ...\nend function\n\n// 'data'는 너무 일반적이어서 어떤 데이터를 어떻게 처리하는지 드러내지 않는다.\nfunction data(items)\n // ...\nend function\n\n// 'check'는 무엇을 확인하는지 명확하지 않다.\n// 'checkPassword'나 'validateEmail'처럼 더 구체적이어야 한다.\nfunction check(input)\n // ...\nend function\n```\n\n```\n\n---\n\n### 3단계: 무의미하거나, 주관적이거나, 모호한 이름에 대한 금지 규칙\n\n#### 1. 파일 생성: `principles/naming/no-meaningless-names.md`\n\n이 원칙은 `temp`나 `x`와 같은 일반적이고 임시적인 변수 이름의 사용을 금지합니다. 이러한 이름은 변수의 목적을 모호하게 하여, 개발자가 그 역할을 이해하기 위해 코드를 추적하게 만듭니다. 수명이 짧은 변수에 대해서도 의미 있고 역할 기반의 이름을 요구함으로써, 이 규칙은 지역적인 가독성을 향상시키고 상태에 대한 오해로 인한 버그 위험을 줄입니다.\n\n**파일**: `principles/naming/no-meaningless-names.md`\n\n```markdown\n# 원칙: temp나 tmp와 같이 의미 없는 임시 변수 이름을 사용하지 않는다\n\n**태그**: 이름짓기, 가독성, 명확성\n\n---\n\n## 1. 핵심 정의\n\n> 임시로 값을 저장하는 변수라 할지라도 `temp`, `tmp`, `x`, `i`와 같이 의도를\n> 전혀 설명하지 않는 이름 대신, 변수의 목적과 역할을 명확히 설명하는 이름을\n> 사용해야 한다.\n\n## 2. 근거 (왜?)\n\n'임시 변수'는 존재가 임시적일 뿐, '중요하지 않은 변수'가 아니다. `temp`나 `tmp`\n같은 이름은 변수가 어떤 값을, 왜, 얼마 동안 담고 있는지에 대한 정보를 전혀\n제공하지 않는다. 코드를 읽는 사람은 이 변수의 정체를 파악하기 위해 코드의 흐름\n전체를 거슬러 올라가야 한다. 이는 상당한 인지적 부담을 유발하며 버그의 원인이\n될 수 있다. 변수의 생명주기가 짧더라도 그 역할에 맞는 명확한 이름을 붙여주는\n것은 코드 가독성을 극적으로 향상시키고 로직을 이해하기 쉽게 만든다.\n\n- _변수의 역할을 즉시 이해할 수 있게 하여 코드 분석 시간을 줄여준다._\n- _이름 없는 '마법 변수'가 코드 속에 숨는 것을 방지한다._\n- _코드를 처음 보는 사람도 로직의 흐름을 쉽게 따라갈 수 있게 한다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **역할 기반 이름 사용**: 변수가 수행하는 역할에 기반하여 이름을 짓는다. (예:\n 값을 교환할 때 `temp` 대신 `oldValue`, `swappedValue` 사용)\n- **구체적인 이름 사용**: 임시로 저장되는 데이터의 의미를 구체적으로 설명하는\n 이름을 사용한다. (예: `tmpUser` 대신 `userBeforeUpdate`)\n- **루프 변수 이름**: 단순 배열 인덱스가 아닌 경우, `i`, `j`, `k` 대신\n `userIndex`, `rowIndex`와 같이 의미 있는 이름을 사용한다.\n\n### 금지 사항 (Don't)\n\n- **한 글자 변수명 남용 금지**: 루프 카운터를 제외하고 `a`, `b`, `x`와 같은\n 한 글자 변수명을 사용하지 않는다.\n- **`temp`, `tmp` 사용 금지**: 어떤 상황에서도 `temp`나 `tmp`는 좋은 이름이\n 될 수 없다. 더 나은 이름은 항상 존재한다.\n- **데이터 타입으로 이름짓기 금지**: `str`이나 `num`처럼 데이터 타입만으로\n 이름을 짓는 것은 변수의 역할을 설명하지 않는다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 역할이 명확한 임시 변수 이름\n\n```plaintext\n// 두 변수의 값을 교환하는 로직\nfunction swap(a, b)\n // 'temp' 대신 'originalA'라는 이름을 사용하여\n // a의 원래 값을 저장하는 역할임을 명확히 한다.\n let originalA = a\n a = b\n b = originalA\nend function\n\n// 첫 번째 사용자를 임시로 저장\nlet firstUser = userList[0]\nif firstUser is not null then\n // ...\nend if\n```\n\n### 나쁜 예시: 의미 없는 임시 변수 이름\n\n```plaintext\n// 'temp' 변수가 무엇을 위한 것인지, 왜 필요한지 불분명하다.\nfunction swap(a, b)\n let temp = a\n a = b\n b = temp\nend function\n\n// 'x'가 무엇을 의미하는지 전혀 알 수 없다.\n// 이 변수가 왜 필요한지 알려면 전체 코드를 읽어야 한다.\nlet x = userList[0]\nif x is not null then\n // ...\nend if\n```\n\n```\n\n#### 2. 파일 생성: `principles/naming/no-ambiguous-abbreviations.md`\n\n이 원칙은 모호한 약어의 사용을 금지합니다. 한 사람에게는 명확한 약어가 다른 사람에게는 암호처럼 보일 수 있어 혼란과 오해의 가능성을 만듭니다. 전체 단어 사용을 강제함으로써, 우리는 단기적인 타이핑 편의성보다 장기적인 명확성과 유지보수성을 우선시하여, 현재와 미래의 모든 팀원이 코드베이스에 접근할 수 있도록 합니다.\n\n**파일**: `principles/naming/no-ambiguous-abbreviations.md`\n\n```markdown\n# 원칙: 의미가 모호해지는 약어는 사용하지 않는다 (팀 공유 사전에 등록된 경우 예외)\n\n**태그**: 이름짓기, 가독성, 팀워크\n\n---\n\n## 1. 핵심 정의\n\n> 약어는 코드의 의미를 파악하는 데 추가적인 인지 부하를 유발하므로, 팀 전체가\n> 동의하고 공유하는 사전에 등록된 경우를 제외하고는 사용하지 않아야 한다.\n\n## 2. 근거 (왜?)\n\n코드를 작성한 개발자에게는 명확해 보이는 약어가 다른 팀원이나 미래의 자신에게는\n해독해야 할 암호처럼 느껴질 수 있다. `proc`, `auth`, `svc`와 같이 여러 의미로\n해석될 수 있는 약어는 심각한 오해를 불러일으킬 수 있다. 약어를 사용하여 타이핑\n몇 초를 아끼는 것보다, 전체 단어를 사용하여 코드의 의도를 명확하게 전달하는\n것이 훨씬 더 큰 장기적 가치를 제공한다. 명시적인 이름은 코드를 자체 문서화하여,\n다른 사람이 코드를 이해하고 협업하는 데 걸리는 시간을 크게 줄여준다.\n\n- _새로운 팀원이나 다른 팀의 개발자가 코드를 이해하는 시간을 단축시킨다._\n- _여러 의미로 해석될 수 있는 모호함을 제거하여 버그 발생 가능성을 줄인다._\n- _코드 가독성을 향상시켜 유지보수를 용이하게 만든다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **전체 단어 사용**: 기본 원칙으로 항상 약어를 쓰지 않고 완전한 단어를\n 사용한다. (예: `destinationAddress`)\n- **팀 공유 사전 활용**: 프로젝트 도메인에 특화되어 자주 사용되는 용어의 경우,\n 팀 공유 사전에 약어와 전체 단어를 명시하고 합의된 약어만 사용한다. (예:\n Authentication은 `AuthN`, Authorization은 `AuthZ`)\n\n### 금지 사항 (Don't)\n\n- **개인적인 약어 금지**: 자신만 아는 임의의 약어를 만들지 않는다. (예:\n `calculate`를 `calc`로 줄이지 않는다.)\n- **문맥 의존적 약어 금지**: 특정 문맥에서만 이해할 수 있는 약어는 피한다.\n 이름은 그 자체로 완전해야 한다.\n- **모음 제거 약어 금지**: `message`를 `msg`로, `service`를 `svc`로 줄이는\n 것처럼 단순히 모음을 제거하는 방식의 약어는 피한다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 전체 단어 또는 합의된 약어 사용\n\n```plaintext\n// 전체 단어를 사용하여 이름의 의미가 명확하다.\nlet destinationAddress = \"123 Main St\"\n\nfunction getAuthenticatedUser(sessionToken)\n // ...\nend function\n\n// 'ID'는 'Identifier'로 보편적으로 이해되므로 허용된다.\nconst userId = 12345\n```\n\n### 나쁜 예시: 모호한 약어 사용\n\n```plaintext\n// 'dest'가 destination인지 destruction인지 명확하지 않다.\n// 'addr' 역시 address의 표준 약어가 아니다.\nlet destAddr = \"123 Main St\"\n\n// 'auth'가 authentication인지 authorization인지 명확하지 않다.\n// 'usr' 역시 user의 일반적인 약어가 아니다.\nfunction getAuthUsr(token)\n // ...\nend function\n\n// 'proc'이 process인지, procedure인지, processor인지 명확하지 않다.\nfunction proc(data)\n // ...\nend function\n```\n\n```\n\n#### 3. 파일 생성: `principles/naming/no-subjective-names.md`\n\n이 작업은 이름에 `good`이나 `important`와 같은 주관적인 단어를 금지하는 원칙을 만듭니다. 이러한 이름은 사실이 아닌 의견에 기반하며 객관적인 정보를 전달하지 못합니다. 코드는 논리와 측정 가능한 사실에 기반해야 합니다. 이 규칙은 이름이 저자의 감정이 아닌 심볼의 역할이나 목적을 설명하도록 보장하여, 더 명확하고 전문적인 코드를 만듭니다.\n\n**파일**: `principles/naming/no-subjective-names.md`\n\n```markdown\n# 원칙: 이름에 주관적인 형용사나 부사를 사용하지 않는다\n\n**태그**: 이름짓기, 명확성, 객관성\n\n---\n\n## 1. 핵심 정의\n\n> `good`, `fast`, `important`, `beautiful` 등 사람마다 다르게 해석될 수 있는\n> 주관적인 단어를 변수, 함수, 클래스 등의 이름에 사용해서는 안 된다.\n\n## 2. 근거 (왜?)\n\n주관적인 이름은 코드의 의미를 명확하게 전달하지 못하고 오히려 혼란을 가중시킨다.\n한 개발자가 '중요하다'고 생각하는 데이터가 다른 개발자에게는 그렇지 않을 수\n있다. '빠른' 처리기는 무엇과 비교해서 얼마나 빠른지에 대한 객관적인 기준이\n없다. 이러한 이름은 코드의 목적을 설명하는 것이 아니라 저자의 개인적인 감정이나\n의견을 담고 있다. 코드는 감정을 배제하고 사실과 논리에 기반해야 한다. 객관적이고\n측정 가능한 용어를 사용하면 모든 사람이 코드의 역할을 동일하게 이해하고 예측할\n수 있다.\n\n- _이름의 자의적인 해석을 막고 모든 팀원이 동일하게 이해하도록 보장한다._\n- _감정이 아닌 사실에 기반하여 코드의 목적을 명확히 전달한다._\n- _객체의 구체적인 역할과 특성을 이름만으로 파악할 수 있게 한다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **역할과 목적 서술**: 주관적인 평가 대신, 객체의 역할이나 목적을 구체적으로\n 서술해야 한다. (예: `importantData` 대신 `userPermissionData`)\n- **측정 가능한 용어 사용**: 단순히 빠르다, 크다, 중요하다가 아니라 어떻게\n 빠른지, 얼마나 큰지, 왜 중요한지를 이름에 명시해야 한다. (예: `fastLoop` 대신\n `loopWithMicrosecondTimeout`)\n- **객관적인 상태 명시**: 객체의 상태를 객관적인 단어로 표현한다. (예: `goodUser`\n 대신 `verifiedUser`)\n\n### 금지 사항 (Don't)\n\n- **감정적인 단어 금지**: `awesome`, `cool`, `magic`처럼 코드의 기능을\n 과장하거나 감정을 표현하는 단어를 사용하지 않는다.\n- **모호한 평가 단어 금지**: `performance`, `quality` 같은 단어는 본질적으로\n 모호하다. `averageResponseTimeInMs`처럼 구체적으로 표현한다.\n- **불필요한 수식어 금지**: `reallyFastProcessor`처럼 주관성을 강조하는 부사를\n 사용하지 않는다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 객관적이고 사실 기반의 이름\n\n```plaintext\n// 'optimized'라는 주관적 표현 대신 'cached'라는 객관적 사실을 명시했다.\nlet cachedUserProfile = getUserProfileFromCache(userId)\n\n// 'dangerous'라는 주관적 표현 대신 '경고 없이'라는 구체적인 동작을 서술했다.\nfunction deleteUserWithoutWarning(userId)\n // ...\nend function\n\n// 'high priority'라는 모호한 표현 대신 구체적인 레벨을 명시했다.\nconst HIGH_PRIORITY_LEVEL = 3\n```\n\n### 나쁜 예시: 주관적인 표현을 사용한 이름\n\n```plaintext\n// 'best'가 어떤 기준인지 불분명하다.\nlet bestUserProfile = findUserProfile(userId)\n\n// 'dangerous'는 주관적이며 어떤 위험이 있는지 설명하지 않는다.\nfunction dangerousOperation(data)\n // ...\nend function\n\n// 'important'는 사람마다 기준이 다르다.\n// 이름만으로는 이 변수가 왜 중요한지 알 수 없다.\nconst IMPORTANT_VALUE = 100\n```\n\n```\n\n---\n\n### 4단계: 일반적인 형식화 원칙 (취향이 아닌 규칙, 자동화)\n\n#### 1. 파일 생성: `principles/formatting/formatting-is-a-rule.md`\n\n이 문서는 코드 형식화가 개인적인 선호의 문제가 아니라 의무적인 프로젝트 규칙임을 확립합니다. 이는 코드 리뷰 중 비생산적인 논쟁을 없애고 전체 코드베이스가 단일하고 일관된 시각적 스타일을 갖도록 보장하는 데 중요합니다. 통일된 형식은 가독성을 향상시키고 코드가 마치 한 명의 저자에 의해 작성된 것처럼 보이게 하여 전문성을 높입니다.\n\n**파일**: `principles/formatting/formatting-is-a-rule.md`\n\n```markdown\n# 원칙: 코드 형식화는 개인의 취향이 아닌 규칙이다\n\n**태그**: 형식화, 일관성, 팀워크\n\n---\n\n## 1. 핵심 정의\n\n> 들여쓰기, 줄 바꿈, 공백, 중괄호 배치 등 시각적 스타일에 대한 규칙은 개인의\n> 취향에 따른 선택 사항이 아니라, 프로젝트 전체에 일관되게 적용되어야 하는\n> 강제적인 규칙이다.\n\n## 2. 근거 (왜?)\n\n코드 형식화는 코드 가독성과 직결된다. 일관된 형식화 스타일은 개발자가 코드의\n구조를 시각적으로 더 빠르고 쉽게 파악하도록 돕는다. 만약 팀원 각자가 다른\n형식화 스타일을 사용한다면, 코드를 읽을 때마다 다른 형식에 적응해야 하는\n불필요한 인지 부하가 발생한다. 특히 코드 리뷰 시, 형식화와 관련된 주관적인\n논쟁(예: \"중괄호는 다음 줄에 있어야 해\", \"여기는 공백이 더 필요해\")은 시간을\n낭비하게 만들고, 중요한 로직 검토에 집중하지 못하게 막는다. 형식화를 모두가\n따르는 '규칙'으로 정립함으로써 이러한 비생산적인 논쟁을 없애고, 모든 코드가\n마치 한 사람이 작성한 것처럼 보이게 만든다.\n\n- _형식화에 대한 불필요한 논쟁을 없애고 코드 리뷰의 효율성을 높인다._\n- _일관된 시각적 구조를 제공하여 코드 가독성을 향상시킨다._\n- _팀 전체의 코드 스타일을 통일하여 소스 코드의 전문성과 품질을 높인다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **프로젝트 형식화 규칙 정의**: 프로젝트 시작 시 사용할 형식화 규칙(예: Google\n Style, LLVM Style)을 명확히 정의하고 문서화한다.\n- **자동화 도구 도입**: `clang-format`이나 `Prettier`와 같은 자동 형식화 도구를\n 채택하여 형식화 과정을 강제한다.\n- **CI/CD와 통합**: 커밋이나 푸시 시점에 자동으로 형식화를 검사하거나 적용하는\n 훅을 설정하여 규칙 준수를 보장한다.\n\n### 금지 사항 (Don't)\n\n- **수동 형식화 금지**: 손으로 형식화를 맞추는 것을 피하고 항상 자동화된 도구에\n 의존한다.\n- **규칙에 예외 두지 않기**: \"이번 한 부분만...\"과 같은 예외를 허용하면 규칙의\n 일관성이 깨진다.\n- **형식화로 코드 변경 숨기지 않기**: 로직 변경과 형식화 변경을 하나의 커밋에\n 섞지 않는다. 형식화는 별도의 커밋으로 분리하여 리뷰어가 로직 변경에만 집중할\n 수 있게 한다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 일관된 형식화 규칙이 적용된 코드\n\n```pseudocode\n// 일관된 형식화: 들여쓰기, 공백, 중괄호 스타일이 통일되어 있다.\nfunction calculateSum(numbers) {\n total = 0\n for each number in numbers {\n total = total + number\n }\n return total\n}\n```\n\n### 나쁜 예시: 여러 형식화 스타일이 혼재된 코드\n\n```pseudocode\n// 일관되지 않은 형식화: 들여쓰기, 공백, 중괄호 스타일이 혼재되어 있다.\nfunction calculateSum(numbers)\n{\n total = 0\n for each number in numbers {\n total=total+number // 일관되지 않은 공백\n }\n return total // 과도한 들여쓰기\n}\n```\n\n```\n\n#### 2. 파일 생성: `principles/formatting/use-auto-formatters.md`\n\n이 원칙은 모든 코드 형식화를 자동화된 도구에 위임해야 한다고 규정합니다. 수동 형식화는 오류가 발생하기 쉽고 개발자의 노력을 낭비합니다. `clang-format`이나 `Prettier`와 같은 도구에 의존함으로써 우리는 100% 일관된 결과를 보장하고 개발자들이 로직에 집중할 수 있도록 합니다. 이것은 \"형식화는 규칙이다\" 원칙의 실질적인 강제 메커니즘입니다.\n\n**파일**: `principles/formatting/use-auto-formatters.md`\n\n```markdown\n# 원칙: 코드 형식화는 자동 형식화 도구에 완전히 위임하고 수동으로 편집하지 않는다\n\n**태그**: 형식화, 자동화, 생산성\n\n---\n\n## 1. 핵심 정의\n\n> 코드의 시각적 스타일을 맞추는 작업은 개발자가 직접 수행하는 것이 아니라,\n> `clang-format`이나 `Prettier`와 같은 자동화된 형식화 도구에 전적으로 위임해야\n> 한다.\n\n## 2. 근거 (왜?)\n\n수동으로 코드 형식을 맞추는 것은 개발자의 귀중한 시간을 낭비하는 지루하고,\n오류가 발생하기 쉬우며, 비생산적인 활동이다. 개발자는 로직을 구현하는 본질적인\n문제 해결에 집중해야 한다. 자동 형식화 도구를 도입하면, 미리 정의된 규칙에 따라\n버튼 한 번 클릭하거나 파일을 저장하는 순간 모든 코드가 즉시 일관된 스타일로\n정리된다. 이는 개발자를 형식화에 대한 고민에서 완전히 해방시킬 뿐만 아니라,\n모든 팀원이 100% 동일한 형식화 결과를 얻도록 보장한다. '형식화는 규칙'이라는\n원칙을 지키는 가장 확실한 방법은 사람의 개입을 최소화하고 기계의 절대적인\n일관성을 활용하는 것이다.\n\n- _개발자가 형식화에 쏟는 시간과 노력을 없애, 핵심 로직 개발에 집중할 수 있게\n 한다._\n- _인간의 실수를 배제하여 100% 일관된 형식화 결과를 보장한다._\n- _새로운 팀원이 프로젝트에 합류했을 때 형식화 스타일을 배울 필요 없이, 도구를\n 사용하여 즉시 규칙을 따를 수 있게 한다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **프로젝트에 맞는 형식화 도구 선택**: C++에는 `clang-format`, 웹 프로젝트에는\n `Prettier`, Python에는 `Black`과 같이 언어와 생태계에 맞는 표준 형식화\n 도구를 선택하고 도입한다.\n- **IDE와 통합**: 개발자가 사용하는 IDE(예: VSCode, CLion)에 형식화 도구 플러그인을\n 설치하고, '저장 시 자동 형식화'와 같은 옵션을 활성화한다.\n- **CI에서 형식화 검증**: CI(Continuous Integration) 파이프라인에 형식화 검사\n 단계를 추가하여 규칙에 맞지 않는 코드가 병합되는 것을 방지한다.\n\n### 금지 사항 (Don't)\n\n- **형식화 도구 출력물 수동 수정 금지**: 자동 형식화 도구가 만들어낸 결과가 마음에\n 들지 않더라도 수동으로 수정해서는 안 된다. 규칙을 바꾸고 싶다면 반드시\n 형식화 도구의 설정 파일을 수정하여 프로젝트 전체에 일관되게 적용해야 한다.\n- **여러 형식화 도구 혼용 금지**: 하나의 프로젝트에서는 단 하나의 형식화 도구와\n 설정만을 사용해야 한다.\n- **형식화 예외 주석 남용 금지**: 대부분의 형식화 도구는 특정 구간의 형식화를\n 비활성화하는 주석(예: `// clang-format off`)을 지원하지만, 이는 정말\n 불가피한 경우에만 최소한으로 사용해야 한다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 자동 형식화 도구 설정 파일을 통한 관리\n\n```yaml\n# .clang-format 파일 예시\n# 이 설정 파일이 프로젝트 전체의 형식화 규칙을 중앙에서 관리한다.\nBasedOnStyle: Google\nIndentWidth: 4\nTabWidth: 4\nUseTab: Never\nColumnLimit: 120\nAllowShortFunctionsOnASingleLine: None\n```\n\n### 나쁜 예시: 수동으로 형식화를 시도하는 경우\n\n```cpp\n// 개발자가 자신의 스타일에 맞춰 수동으로 형식화한 코드.\n// 다른 개발자가 자동 형식화 도구를 실행하면 이 코드는 즉시 변경될 것이다.\n// 이는 불필요한 코드 변경 이력을 만들고 혼란을 야기한다.\nint calculate_sum(const std::vector& numbers){int total = 0;for (int number : numbers) {total += number;}return total;}\n```\n\n```\n\n---\n\n### 5단계: 공백 및 파일 끝에 대한 구체적인 형식화 규칙\n\n#### 1. 파일 생성: `principles/formatting/no-unnecessary-alignment.md`\n\n이 원칙은 공백을 사용하여 코드를 수동으로 정렬하는 것을 금지합니다. 미학적으로 보기 좋을 수 있지만, 이 관행은 깨지기 쉽고 상당한 유지보수 오버헤드와 시끄러운 버전 관리 diff를 만듭니다. 이 규칙은 모든 정렬이 지정된 형식화 도구에 의해 일관되고 자동으로 처리되도록 보장하여, 더 깨끗하고 유지보수하기 쉬운 코드베이스를 만듭니다.\n\n**파일**: `principles/formatting/no-unnecessary-alignment.md`\n\n```markdown\n# 원칙: 정렬을 위해 공백을 사용하지 않는다\n\n**태그**: 형식화, 가독성, 일관성\n\n---\n\n## 1. 핵심 정의\n\n> 인접한 줄에 있는 토큰(예: 변수명, 값, 주석)을 수직으로 정렬하기 위해 추가적인\n> 공백이나 탭을 사용하지 않는다.\n\n## 2. 근거 (왜?)\n\n공백을 사용하여 코드를 수동으로 정렬하는 것은 깨지기 쉽고 상당한 유지보수\n오버헤드를 발생시킨다. 한 줄이 수정되면 인접한 모든 줄의 정렬을 수동으로 다시\n조정해야 하는 경우가 많으며, 이는 지루하고 오류가 발생하기 쉽다. 또한 이 관행은\n버전 관리에서 불필요하게 크고 시끄러운 diff를 만들어 실제 로직 변경을 가린다.\n\n모든 정렬과 들여쓰기 작업은 일관된 자동 형식화 도구에 위임해야 한다. 이를 통해\n수동적인 노력 없이 코드베이스 전체에 통일된 스타일을 보장하고 버전 기록을\n깨끗하게 유지할 수 있다.\n\n- _변경 사항이 주변 코드의 수동 재정렬을 요구하지 않으므로 유지보수 노력이\n 줄어든다._\n- _공백 변경을 최소화하여 버전 관리에서 diff의 명확성을 향상시킨다._\n- _자동화된 도구에 의존하여 프로젝트 전반에 걸쳐 일관된 형식화를 보장한다._\n- _주관적인 정렬 스타일에 대한 논쟁을 방지한다._\n\n## 3. 실천 방법\n\n### 금지 사항 (Don't)\n\n- **변수명이나 값을 수동으로 정렬하지 않기**: 변수 선언이나 할당이 수직으로\n 정렬되도록 추가 공백을 넣는 것을 피한다.\n- **줄 끝에 있는 주석을 정렬하지 않기**: 인접한 줄의 주석을 정렬하기 위해 공백을\n 추가하지 않는다.\n- **매크로 정의나 다른 전처리기 지시문을 정렬하지 않기.**\n\n## 4. 코드 예시\n\n### 좋은 예시: 원칙을 준수하는 코드 (자동 형식화됨)\n\n```pseudocode\n// 좋음: 형식화 도구가 공백을 처리하도록 한다. 수동 정렬 없음.\ncount = 0\nname = \"John Doe\"\nisActive = true\n\nlongVariableName = someFunctionCall()\nanotherVar = anotherCall()\n```\n\n### 나쁜 예시: 원칙을 위반하는 코드\n\n```pseudocode\n// 나쁨: 수동으로 정렬된 코드는 유지보수가 어렵다.\ncount = 0 // 정렬됨\nname = \"John Doe\" // 정렬됨\nisActive = true // 정렬됨\n\nlongVariableName = someFunctionCall()\nanotherVar = anotherCall() // 수동으로 정렬됨\n```\n\n```\n\n#### 2. 파일 생성: `principles/formatting/no-unnecessary-whitespace.md`\n\n이 문서는 후행 공백이나 여러 개의 빈 줄과 같은 불필요한 공백에 대한 규칙을 정의합니다. 이러한 공백은 의미론적 가치를 더하지 않고 시각적 노이즈를 만듭니다. 이 규칙을 시행하면 더 깨끗하고 전문적인 코드베이스가 되며, 버전 관리에서 사소하고 기능과 무관한 변경을 방지합니다. 이는 편집기와 형식화 도구에 의해 자동으로 처리되어야 합니다.\n\n**파일**: `principles/formatting/no-unnecessary-whitespace.md`\n\n```markdown\n# 원칙: 불필요한 공백을 사용하지 않는다\n\n**태그**: 형식화, 가독성, 일관성\n\n---\n\n## 1. 핵심 정의\n\n> 코드에는 불필요한 공백이 없어야 한다. 이는 줄 끝의 후행 공백과 연속된 여러\n> 개의 빈 줄을 포함한다.\n\n## 2. 근거 (왜?)\n\n불필요한 공백은 의미론적 가치를 더하지 않고 시각적 노이즈를 만들어 코드를 읽기\n어렵게 한다. 후행 공백은 보이지 않지만 일부 도구에서 문제를 일으킬 수 있으며\n버전 관리 diff에서 노이즈를 발생시킨다. 여러 개의 빈 줄은 코드의 흐름을 방해하고\n코드 블록 간의 논리적 관계를 파악하기 어렵게 만들 수 있다.\n\n불필요한 공백을 제거하여 깨끗하고 간결한 스타일을 강제하면 더 전문적이고\n유지보수하기 쉬운 코드베이스를 만들 수 있다. 이 작업은 수동적인 노력 없이\n일관성을 보장하기 위해 형식화 도구와 편집기 설정에 의해 자동으로 처리되어야\n한다.\n\n- _시각적 혼란을 제거하여 코드의 명확성을 향상시킨다._\n- _버전 관리에서 사소하고 기능과 무관한 변경을 방지한다._\n- _코드베이스 전반에 걸쳐 일관되고 전문적인 외관을 보장한다._\n\n## 3. 실천 방법\n\n### 금지 사항 (Don't)\n\n- **후행 공백 남기지 않기**: 어떤 줄도 공백이나 탭으로 끝나지 않도록 한다.\n 대부분의 편집기는 저장 시 이를 자동으로 제거하도록 설정할 수 있다.\n- **여러 개의 빈 줄 사용하지 않기**: 적절한 경우 논리적인 코드 블록을 분리하기\n 위해 단일 빈 줄을 사용한다. 절대로 하나 이상 사용하지 않는다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 깨끗하고 간결한 코드\n\n```pseudocode\n// 좋음: 단일 빈 줄이 논리적 블록을 구분한다. 후행 공백 없음.\nfunction doSomething() {\n // ...\n}\n\nfunction doSomethingElse() {\n // ...\n}\n```\n\n### 나쁜 예시: 불필요한 공백이 있는 코드\n\n```pseudocode\nfunction doSomething() // 나쁨: 후행 공백.\n{\n // ...\n}\n\n\n\n// 나쁨: 여러 개의 빈 줄.\nfunction doSomethingElse()\n{\n // ...\n}\n```\n\n```\n\n#### 3. 파일 생성: `principles/formatting/newline-at-eof.md`\n\n이 작업은 비어있지 않은 모든 파일이 단일 개행 문자로 끝나야 한다는 원칙을 만듭니다. 이것은 POSIX 기반 도구(`cat`이나 `git`과 같은)와의 호환성을 보장하고 버전 관리에서 시끄러운 diff를 방지하는 표준 관례입니다. 이 규칙을 준수하면 도구 체인의 무결성과 전문적인 표준을 유지합니다.\n\n**파일**: `principles/formatting/newline-at-eof.md`\n\n```markdown\n# 원칙: 파일 끝은 단일 개행 문자로 마친다\n\n**태그**: 형식화, 일관성, 도구 호환성\n\n---\n\n## 1. 핵심 정의\n\n> 비어있지 않은 모든 소스 파일은 반드시 단일 개행 문자로 끝나야 한다.\n\n## 2. 근거 (왜?)\n\n파일을 단일 개행 문자로 끝내는 것은 소프트웨어 개발, 특히 유닉스 계열 환경에서\n오래된 관례이다. 이 규칙에는 몇 가지 실용적인 이유가 있다:\n\n- **POSIX 호환성**: 많은 커맨드 라인 도구(예: `cat`, `wc`, `git`)는 개행 문자로\n 끝나는 문자 시퀀스로 정의된 텍스트 줄 단위로 작동하도록 설계되었다. 최종\n 개행 문자가 없는 파일은 두 파일을 `cat`으로 합칠 때 마지막 줄과 첫 줄이\n 합쳐지는 등 예기치 않은 동작을 유발할 수 있다.\n- **버전 관리 명확성**: Git 및 다른 버전 관리 시스템은 diff에서 최종 개행 문자의\n 부재를 강조하여 불필요한 노이즈를 추가하는 경우가 많다. 일관되게 이를 포함하면\n diff가 깨끗하게 유지되고 의미 있는 변경에 집중할 수 있다.\n- **\"수정됨\" 상태 방지**: 일부 편집기나 도구는 누락된 개행 문자를 자동으로\n 추가하여, 논리적인 변경이 없었음에도 파일이 수정된 것처럼 보이게 할 수 있다.\n\n이 규칙을 편집기나 형식화 도구 설정을 통해 자동화하는 것이 수동적인 노력 없이\n준수를 보장하는 가장 좋은 방법이다.\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **편집기/IDE 설정**: 대부분의 최신 편집기(예: VS Code, CLion, Vim)에는 저장\n 시 자동으로 최종 개행 문자를 삽입하는 설정이 있다. 이 기능을 활성화한다.\n- **자동 형식화 도구 사용**: Clang-Format과 같은 도구는 이 규칙을 강제하도록\n 설정할 수 있다.\n\n### 금지 사항 (Don't)\n\n- **최종 개행 문자 없이 파일 저장 금지**: 수동으로 개행 문자를 제거하거나 이를\n 추가하는 편집기 설정을 비활성화하는 것을 피한다.\n\n## 4. 예시\n\n마크다운에서 최종 개행 문자를 시각적으로 표현할 수는 없지만, 원칙은 간단하다.\n파일의 마지막 문자는 `\\n`이어야 한다.\n\n**좋음**: 파일 내용이 끝나고, 마지막 코드 줄 뒤에 하나의 최종 개행 문자가 있다.\n\n**나쁨**: 파일 내용이 끝나고, 마지막 줄의 마지막 문자 바로 뒤에 커서가 있으며,\n뒤따르는 개행 문자가 없다.\n```\n\n---\n\n## 4. 검증 절차\n\n### 4.1. 검증 단계\n\n개발자는 구현이 올바른지 확인하기 위해 다음 단계를 수행해야 합니다.\n\n```bash\n# 1. 올바른 기능 브랜치에 최신 변경 사항이 적용되었는지 확인합니다.\ngit status\n\n# 2. 새로 생성된 모든 파일을 나열하여 존재 여부와 위치를 확인합니다.\n# 이 명령은 13개의 파일을 나열해야 합니다.\nfind principles/naming principles/formatting -type f -name \"*.md\"\n\n# 3. 몇몇 핵심 파일의 내용을 수동으로 검사하여 명세와 일치하는지 확인합니다.\n# 예를 들어, 이름짓기 원칙과 형식화 원칙 하나를 확인합니다.\ncat principles/naming/name-active-objects-as-verb-er.md\ncat principles/formatting/use-auto-formatters.md\n\n# 4. (선택 사항이지만 권장) 사용 가능한 마크다운 린터를 실행하여 기본적인 구문 문제를 확인합니다.\n# 'markdownlint'와 같은 린터가 설치되어 있다고 가정합니다.\nmarkdownlint principles/**/*.md\n```\n\n### 4.2. 예상 결과\n\n- `git status` 명령은 올바른 브랜치에 있으며 작업 디렉토리가 깨끗하다는 것을 보여주어야 합니다.\n- `find` 명령은 **결과 파일 구조** 및 **영향받는 파일** 섹션에 명시된 13개의 마크다운 파일을 모두 나열해야 합니다. 파일 경로는 정확히 일치해야 합니다.\n- `cat` 명령은 **구현 명세**에 정의된 각 원칙의 전체 마크다운 내용을 표시해야 합니다.\n- 마크다운 린터를 실행할 경우, 오류 없이 통과하여 문서가 올바른 형식임을 확인해야 합니다.","모호하지 않은 이름을 만들고 일관된 코드 서식을 유지하기 위한 명확한 규칙 세트",[123,125,127,129,131],{"_24":124,"_83":39,"_84":91,"_85":61},"명확성과 객관성을 위한 일반 이름 지정 원칙 문서",{"_24":126,"_83":39,"_84":91,"_85":88},"수동적 객체, 능동적 객체, 함수에 대한 특정 이름 지정 규칙",{"_24":128,"_83":39,"_84":91,"_85":91},"무의미하거나, 주관적이거나, 모호한 이름에 대한 금지 규칙",{"_24":130,"_83":39,"_84":91,"_85":94},"일반 서식 원칙 (선호가 아닌 규칙, 자동화)",{"_24":132,"_83":39,"_84":91,"_85":97},"공백 및 파일 끝에 대한 특정 서식 규칙","이름 지정 및 서식에 대한 언어 독립적인 원칙을 정의",{"_22":135,"_24":136,"_75":137,"_77":138,"_79":139,"_51":150,"_42":99},"task-1751363127063","설계 원칙 문서","# 작업: 설계 원칙 문서\n\n> **에픽**: 개발의 기초가 되는 원칙 수립\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 견고하고 유지보수하기 쉬운 소프트웨어 설계를 위한 문서 작성.\n- **근거**: 이 작업은 프로젝트 전체의 핵심 설계 철학을 수립합니다. 단일 책임 원칙, 불변성, 명시적인 리소스 관리(RAII)와 같은 기본 원칙들을 성문화함으로써, 우리는 공유되고 명확한 기반을 만듭니다. 이를 통해 모든 후속 언어별 가이드라인과 코드 예제가 일관되고 견고한 아키텍처 가치 위에 구축되도록 보장하며, 이는 가독성 높고 안정적이며 유지보수하기 쉬운 코드를 생산하기 위해 소프트웨어 엔지니어링 원칙을 공식화하려는 프로젝트의 목표를 직접적으로 지원합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: SRP와 불변성부터 리소스 관리에 이르는 주제를 다루는 모범 사례 모음.\n- **명세**: `principles/design-principles/` 디렉터리에 새로운 마크다운 파일 모음이 생성됩니다. 각 파일은 단일 설계 원칙을 정의하며, 표준적인 네 부분 구조를 따라야 합니다.\n 1. 핵심 정의\n 2. 근거 (왜 필요한가?)\n 3. 실천 방법 (권장/비권장)\n 4. 코드 예시 (좋은 예/나쁜 예)\n- **결과 파일 구조**\n\n```bash\n./\n└── principles/\n └── design-principles/\n ├── clear-object-lifecycle.md <-- 신규\n ├── code-over-comments.md <-- 신규\n ├── narrow-scope.md <-- 신규\n ├── no-global-variables.md <-- 신규\n ├── no-implicit-conversions.md <-- 신규\n ├── no-magic-numbers.md <-- 신규\n ├── prefer-immutability.md <-- 신규\n ├── raii.md <-- 신규\n ├── simple-constructors.md <-- 신규\n ├── single-action-per-function.md <-- 신규\n ├── single-responsibility-principle.md <-- 신규\n └── use-operator-overloading.md <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 문서들은 프로젝트 내 모든 개발 활동의 기초적인 참고 자료 역할을 합니다. 다음 다이어그램은 개발 생명주기 초반에 이 문서들의 역할을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"개발 생명주기\"\n Dev[\"개발자\"]\n Principles[\"설계
원칙 문서 참조\"]\n Authoring[\"코드 또는
언어별 가이드라인 작성\"]\n Automation[\"로컬 및 CI
자동화 도구 실행\"]\n\n Dev --> Principles\n Principles --> Authoring\n Authoring --> Automation\n end\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완수해야 합니다. 이것은 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] 책임과 범위에 대한 원칙 (SRP, 좁은 범위).\n- [ ] 상태 관리에 대한 원칙 (전역 변수 금지, 불변성 선호).\n- [ ] 객체 생성 및 생명주기에 대한 원칙 (단순한 생성자, 명확한 생명주기, RAII).\n- [ ] 코드 명확성에 대한 원칙 (주석보다 코드, 매직 넘버 금지).\n- [ ] 타입 안전성 및 표현식에 대한 원칙 (암묵적 변환 금지, 연산자 오버로딩).\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 리포지토리\n- **관련 주요 구성요소**:\n - **엔지니어링 원칙**: 이 작업은 `엔지니어링 원칙` 구성요소를 직접 채웁니다. 이 구성요소는 전체 지식 기반의 개념적 토대입니다. 이는 다른 모든 `언어 가이드라인` 및 `자동화 도구` 구성을 안내하는 언어에 구애받지 않는 규칙과 철학을 정의합니다. 이 작업에서 생성된 문서들은 이 구성요소의 주요 산출물입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `principles/design-principles/single-responsibility-principle.md`\n- `principles/design-principles/no-global-variables.md`\n- `principles/design-principles/narrow-scope.md`\n- `principles/design-principles/code-over-comments.md`\n- `principles/design-principles/simple-constructors.md`\n- `principles/design-principles/clear-object-lifecycle.md`\n- `principles/design-principles/no-implicit-conversions.md`\n- `principles/design-principles/raii.md`\n- `principles/design-principles/prefer-immutability.md`\n- `principles/design-principles/no-magic-numbers.md`\n- `principles/design-principles/single-action-per-function.md`\n- `principles/design-principles/use-operator-overloading.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공할 것입니다.\n\n---\n\n### 단계 1: 책임과 범위에 대한 원칙 (SRP, 좁은 범위)\n\n#### 1. 단일 책임 원칙 문서 생성\n\n이 액션은 클래스나 함수는 변경되어야 할 이유가 단 하나여야 한다는 근본적인 원칙을 수립합니다. 이는 모듈성을 향상시키고, 테스트를 단순화하며, 변경의 영향을 최소화하여 시스템의 유지보수성에 직접적으로 기여합니다. 이 규칙을 문서화하기 위해 다음 파일을 생성합니다.\n\n**파일**: `principles/design-principles/single-responsibility-principle.md`\n\n```markdown\n# 원칙: 모든 함수와 클래스는 단일 책임을 가져야 한다\n\n**태그**: 설계 원칙, SRP, 응집도\n\n---\n\n## 1. 핵심 정의\n\n> 함수나 클래스는 변경되어야 할 이유가 단 하나여야 한다. 즉, 하나의 모듈은\n> 하나의 기능적 책임만을 가져야 한다.\n\n## 2. 근거 (왜 필요한가?)\n\n단일 책임 원칙(SRP)은 소프트웨어 설계에서 가장 근본적이고 중요한 원칙 중\n하나입니다. 하나의 클래스나 함수가 여러 책임을 가지면, 관련 없는 기능들이 서로\n강하게 결합됩니다. 이는 한 기능의 수정이 전혀 관계없는 다른 기능에서 예기치 않은\n버그를 유발하는 상황으로 이어질 수 있습니다. 또한 코드는 비대하고 복잡해져\n이해하고 테스트하기 어려워집니다. 책임을 명확하게 분리함으로써 각 컴포넌트는\n독립적이 되고 재사용하기 쉬워지며, 수정의 영향 범위가 제한되어 전체 시스템의\n유지보수성과 안정성이 크게 향상됩니다.\n\n- _변경이 필요할 때 코드의 어느 부분을 수정해야 할지 명확히 하고, 변경의 영향\n 범위를 최소화합니다._\n- _각 컴포넌트가 독립적이므로 테스트가 쉬워집니다._\n- _잘 정의된 모듈식 기능을 통해 코드 재사용성을 향상시킵니다._\n- _클래스와 함수의 목적을 명확히 하여 전체 코드베이스의 가독성과 이해도를\n 높입니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **클래스 분리**: 클래스가 여러 다른 이유로 변경되어야 한다면, 각 책임별로\n 클래스를 분리하세요. (예: `User` 클래스에서 인증 로직을 `Authenticator`\n 클래스로 분리)\n- **함수 작게 유지**: 함수가 여러 작업을 수행한다면, 각 작업을 별도의 작은\n 함수로 나누고 원래 함수가 이들을 호출하도록 하세요.\n- **'그리고'라는 단어 의심하기**: 클래스나 함수의 역할에 대한 설명에 '그리고'라는\n 단어가 포함된다면, 여러 책임을 가지고 있을 가능성이 높습니다. (예: \"사용자\n 데이터를 가져오고 그 데이터를 파싱한다.\" -> 두 개의 다른 책임)\n\n### 금지 사항 (Don't)\n\n- **갓 클래스(God Class) 만들지 않기**: 너무 많은 역할을 수행하는 거대한\n 클래스를 만들지 마세요.\n- **관심사 섞지 않기**: 데이터베이스 로직, 비즈니스 로직, UI 로직을 단일\n 클래스나 함수에 섞지 마세요. 각 관심사는 명확히 분리되어야 합니다.\n- **편의를 위해 책임 결합하지 않기**: 단지 편리하다는 이유로 관련 없는 기능들을\n 한곳에 묶지 마세요.\n\n## 4. 코드 예시\n\n### 좋은 예: 책임이 분리된 클래스들\n\n```pseudocode\n// User 클래스는 사용자 데이터를 관리하는 단일 책임을 가진다.\nclass User {\n variable name: String\n variable email: String\n // ... getters and setters ...\n}\n\n// UserRepository 클래스는 DB에서 사용자 데이터를 저장하고 조회하는 단일 책임을 가진다.\nclass UserRepository {\n function save(user: User) {\n /* DB 저장 로직 */\n }\n\n function findById(userId: Integer) returns User {\n /* DB 조회 로직 */\n }\n}\n\n// UserValidator 클래스는 사용자 데이터의 유효성을 검사하는 단일 책임을 가진다.\nclass UserValidator {\n function isValid(user: User) returns Boolean {\n /* 유효성 검사 로직 */\n }\n}\n```\n\n### 나쁜 예: 여러 책임을 가진 클래스\n\n```pseudocode\n// User 클래스는 데이터 관리, DB 저장, 유효성 검사라는 세 가지 책임을 가진다.\n// 이 클래스는 DB 스키마가 변경될 때, 유효성 검사 규칙이 변경될 때,\n// 또는 사용자 속성이 변경될 때마다 수정되어야 한다. (변경되어야 할 이유가 3가지)\nclass User {\n variable name: String\n variable email: String\n // ... getters and setters ...\n\n // 책임 1: DB 저장\n function saveToDatabase() {\n // ... DB 연결 및 저장 로직 ...\n }\n\n // 책임 2: 유효성 검사\n function isValidEmail() returns Boolean {\n // ... 이메일 형식 유효성 검사 로직 ...\n }\n}\n```\n\n```\n\n#### 2. 좁은 범위 원칙 문서 생성\n\n이 액션은 변수는 가능한 가장 좁은 범위에서 선언하고 즉시 초기화해야 한다는 규칙을 문서화합니다. 이 관행은 선언과 사용을 같은 위치에 두어 가독성을 향상시키고, 우발적인 수정과 초기화되지 않은 변수 버그를 방지하여 안정성을 높입니다. 이 가이드라인을 공식화하기 위해 다음 파일을 생성합니다.\n\n**파일**: `principles/design-principles/narrow-scope.md`\n\n```markdown\n# 원칙: 변수는 가장 좁은 범위에서 선언하고 즉시 초기화하라\n\n**Tags**: 설계 원칙, 범위, 가독성, 안정성\n\n---\n\n## 1. 핵심 정의\n\n> 변수는 그것이 사용되는 가장 안쪽 블록에서, 처음 사용되기 직전에 선언되어야\n> 하며, 선언과 동시에 유효한 값으로 초기화되어야 한다.\n\n## 2. 근거 (왜 필요한가?)\n\n변수의 생존 기간과 가시성을 최소화하는 것은 코드의 명확성과 안정성을 크게\n향상시킵니다. 함수나 클래스의 상단에 모든 변수를 모아두면, 각 변수가 언제, 어디서,\n어떻게 사용되는지 이해하기 위해 전체 코드를 훑어봐야 합니다. 반면, 변수를 사용\n지점 바로 앞에서 선언하면 선언과 사용을 한눈에 볼 수 있어 가독성이 높아집니다.\n더욱이, 변수의 범위가 좁으면 본질적으로 코드의 다른 부분에서 우발적으로 접근하거나\n수정하는 것을 막아 버그를 예방합니다. 선언 시 초기화하는 습관은 초기화되지 않은\n변수로 인해 발생하는 정의되지 않은 동작을 막는 가장 확실한 방법입니다.\n\n- _변수의 역할과 사용처를 쉽게 파악할 수 있게 하여 코드 가독성을 향상시킵니다._\n- _변수의 생존 기간을 줄여 의도치 않은 값 변경 가능성을 낮춥니다._\n- _초기화되지 않은 변수 사용으로 인한 버그를 근본적으로 방지합니다._\n- _이름 충돌 가능성을 줄이고 컴파일러의 최적화에 도움을 줄 수 있습니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **사용 직전에 선언**: 변수를 실제로 사용하기 직전에 선언하세요(예: 루프\n 안에서만 사용된다면 루프 안에 선언).\n- **선언 시 초기화**: 변수를 선언할 때는 항상 유효한 값으로 초기화하세요.\n `int value; value = 10;`보다 `int value = 10;`을 선호하세요.\n- **`for` 루프 초기화 구문 활용**: `for (int i = 0; i < 10; ++i)`와 같이\n 루프 제어 변수는 `for` 문의 초기화 구문에서 선언하여 범위를 루프 본문으로\n 제한하세요.\n- **불변성 지향**: 값이 변경될 필요가 없는 변수는 불변(예: `const`)으로\n 선언하여 의도치 않은 수정을 막고 안정성을 높이세요.\n\n### 금지 사항 (Don't)\n\n- **함수 상단에 변수 모아두지 않기**: 오래된 C 스타일 관행인, 함수의 시작 부분에\n 모든 변수를 선언하는 것을 피하세요.\n- **더 넓은 범위에 변수 선언하지 않기**: 몇 줄 아래의 `if` 블록 안에서만 필요한\n 변수를 `if` 블록 밖에 선언하지 마세요.\n- **하나의 변수를 여러 다른 목적으로 재사용하지 않기**: 변수의 목적이 달성되면\n 스코프 밖으로 벗어나게 두세요. 새로운 목적을 위해서는 새로운 변수를 선언하세요.\n\n## 4. 코드 예시\n\n### 좋은 예: 필요한 가장 좁은 범위에 변수 선언하기\n\n```pseudocode\nfunction processUsers(users: List) {\n // userCount는 함수 전체에 필요하므로 시작 부분에 선언한다.\n constant userCount = users.length;\n print(\"Total users: \" + userCount);\n\n for (i from 0 to userCount - 1) {\n // currentUser는 for 루프 내에서만 필요하므로 내부에 선언한다.\n constant currentUser = users[i];\n\n if (currentUser.isActive()) {\n // activeUserName은 if 블록 내에서만 필요하므로 내부에 선언한다.\n constant activeUserName = currentUser.getName();\n sendNotification(activeUserName);\n }\n }\n // 여기서 activeUserName이나 currentUser에 접근하면 오류가 발생해야 한다.\n}\n```\n\n### 나쁜 예: 너무 넓은 범위에 변수 선언하기\n\n```pseudocode\nfunction processUsers(users: List) {\n // 모든 변수를 상단에 선언하면 그 역할과 사용 시점을 알기 어렵다.\n variable userCount;\n variable i;\n variable currentUser;\n variable activeUserName;\n\n userCount = users.length;\n print(\"Total users: \" + userCount);\n\n for (i from 0 to userCount - 1) {\n currentUser = users[i];\n\n if (currentUser.isActive()) {\n activeUserName = currentUser.getName();\n sendNotification(activeUserName);\n }\n }\n // 변수 i, currentUser, activeUserName이 루프 후에도 살아있어\n // 의도치 않은 문제를 일으킬 수 있다.\n}\n```\n\n```\n\n#### 3. 함수당 단일 행동 원칙 문서 생성\n\n이 액션은 SRP를 함수에 적용한, 더 세분화된 버전을 문서화합니다. 각 함수는 이름에서 그 목적이 명확히 드러나도록 단 하나의 고유한 행동만 수행해야 함을 규정합니다. 이는 더 작고, 재사용 가능하며, 테스트하기 쉬운 함수로 이어집니다. 이를 강제하기 위해 다음 파일을 생성합니다.\n\n**파일**: `principles/design-principles/single-action-per-function.md`\n\n```markdown\n# 원칙: 함수는 단 하나의 행동만 수행해야 한다\n\n**Tags**: 설계 원칙, 가독성, 응집도, 단일 책임 원칙\n\n---\n\n## 1. 핵심 정의\n\n> 함수는 이름이 설명하는 단 하나의 명확한 행동만 수행하도록 작성되어야 한다.\n> 여러 가지 일을 하는 함수는 반드시 분리되어야 한다.\n\n## 2. 근거 (왜 필요한가?)\n\n함수가 여러 책임을 가지면 그 의도를 파악하기 어렵고, 변경 시 예기치 않은 부작용을\n만들기 쉽습니다. 이는 단일 책임 원칙의 전형적인 위반입니다. 함수가 단 하나의\n일에만 집중하면, 이름만으로도 역할이 명확해지고 재사용성이 높아지며, 테스트와\n디버깅이 매우 간단해집니다. 코드의 각 부분을 독립적으로 이해하고 수정할 수 있게\n되어, 전체 시스템의 유지보수성을 극대화합니다.\n\n- _함수의 역할을 명확하게 하여 코드 가독성을 향상시킵니다._\n- _각 함수가 독립적인 책임을 가지므로 코드 응집도를 높입니다._\n- _테스트해야 할 범위를 명확히 하여 유닛 테스트를 더 쉽게 만듭니다._\n- _변경의 영향을 최소화하여 유지보수 비용을 줄입니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **'동사+목적어' 형식으로 함수 이름 명확히 짓기**: 함수의 이름이 그 역할을\n 완벽하게 설명하는지 확인하세요. 이름에 '그리고'와 같은 접속사가 필요하다면,\n 함수가 여러 가지 일을 하고 있다는 신호입니다.\n- **로직의 각 단계를 별도 함수로 추출하기**: 복잡한 알고리즘이나 다단계 작업의\n 경우, 각 단계를 설명적인 이름을 가진 헬퍼 함수로 분리하세요.\n- **들여쓰기 깊이 관찰하기**: 들여쓰기 깊이가 2단계를 초과하는 코드 블록은\n 별도의 함수로 추출하기 좋은 후보입니다.\n- **매개변수 개수 적게 유지하기**: 매개변수가 너무 많다면(예: 3-4개 이상),\n 함수가 너무 많은 컨텍스트를 요구하거나 여러 작업을 수행하고 있을 가능성이\n 높습니다.\n\n### 금지 사항 (Don't)\n\n- **여러 책임을 가진 만능 함수 만들지 않기**: 데이터 검색, 처리, 저장, 로깅과\n 같은 관련 없는 작업들을 단일 함수에 결합해서는 안 됩니다.\n- **함수 분할을 주저하지 않기**: 함수를 더 작게 나누는 것은 코드의 양을 늘리는\n 것이 아니라, 코드의 구조를 명확히 하는 것입니다.\n- **출력 파라미터(out-parameter) 남용하지 않기**: 이상적으로 함수는 결과를\n 반환 값으로 돌려주어야 합니다. 여러 값을 수정해야 한다면, 그 함수는 너무 많은\n 일을 하고 있을 수 있습니다.\n\n## 4. 코드 예시\n\n### 좋은 예: 원칙을 준수하는 코드\n\n```plaintext\n// 각 함수가 단일하고 명확한 행동을 수행하도록 분리됨\nfunction findUser(database, email) {\n // ... 데이터베이스에서 사용자를 찾는 로직 ...\n return user;\n}\n\nfunction validatePassword(user, password) {\n // ... 비밀번호 유효성을 검사하는 로직 ...\n return isValid;\n}\n\nfunction createSession(user) {\n // ... 세션을 생성하는 로직 ...\n return session;\n}\n\nfunction login(email, password) {\n const user = findUser(database, email);\n if (user && validatePassword(user, password)) {\n return createSession(user);\n }\n return null;\n}\n```\n\n### 나쁜 예: 원칙을 위반하는 코드\n\n```plaintext\n// 단일 함수가 사용자 찾기, 비밀번호 검증, 세션 생성을 모두 처리함\nfunction login(email, password) {\n // 1. 사용자 찾기\n const user = database.find(u => u.email === email);\n if (!user) {\n return null;\n }\n\n // 2. 비밀번호 검증\n const hashedPassword = hash(password, user.salt);\n if (hashedPassword !== user.passwordHash) {\n return null;\n }\n\n // 3. 세션 생성\n const session = createNewSessionFor(user);\n return session;\n}\n```\n\n```\n\n---\n\n### 단계 2: 상태 관리에 대한 원칙 (전역 변수 금지, 불변성 선호).\n\n#### 1. 전역 변수 금지 원칙 문서 생성\n\n이 액션은 상태 관리를 위해 전역 변수를 사용하는 것을 금지하는 규칙을 수립합니다. 전역 변수는 숨겨진 의존성을 만들고 데이터 흐름을 예측 불가능하게 하여, 강하게 결합되고 디버깅하기 어려운 코드를 초래합니다. 이 원칙은 향상된 모듈성과 테스트 용이성을 위해 명시적인 데이터 전달과 캡슐화를 장려합니다. 그 사용을 금지하기 위해 다음 파일을 생성합니다.\n\n**파일**: `principles/design-principles/no-global-variables.md`\n\n```markdown\n# 원칙: 전역 변수를 사용하지 마라\n\n**Tags**: 설계 원칙, 전역 변수, 상태 관리, 예측 가능성\n\n---\n\n## 1. 핵심 정의\n\n> 상태를 예측 불가능하게 만드는 전역 변수 사용을 피하라. 대신, 필요한 곳에\n> 데이터를 명시적으로 전달하여 코드의 제어 흐름을 명확히 하라.\n\n## 2. 근거 (왜 필요한가?)\n\n전역 변수는 프로그램 어디에서든 접근하고 수정할 수 있기 때문에 데이터의 흐름을\n추적하기 극도로 어렵게 만듭니다. 이는 특정 시점의 시스템 상태를 예측하기 어렵게\n하고, 전혀 예상치 못한 곳에서 버그가 발생하는 원인이 될 수 있습니다. 코드는 강하게\n결합되고, 숨겨진 부작용이 나타나며, 디버깅은 극도로 어려워집니다. 더욱이, 전역\n상태는 다중 스레드 환경에서 데이터 경합(data race)을 일으켜 프로그램을 불안정하게\n만들 수 있습니다. 필요한 데이터와 의존성을 함수 인자나 클래스 멤버로 명시적으로\n전달함으로써, 코드는 더 모듈화되고, 테스트하기 쉬우며, 이해하고 추론하기 훨씬\n간단해집니다.\n\n- _데이터 흐름을 명확하게 하여 코드의 예측 가능성을 높입니다._\n- _숨겨진 의존성을 제거하여 모듈성을 향상시키고 결합도를 낮춥니다._\n- _유닛 테스트를 용이하게 하여 코드의 신뢰성을 향상시킵니다._\n- _다중 스레드 환경에서 발생할 수 있는 동시성 문제를 근본적으로 방지합니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **데이터를 인자로 전달**: 함수가 특정 데이터에 의존한다면, 전역 변수를\n 참조하는 대신 해당 데이터를 인자로 받도록 설계하세요.\n- **클래스 내부에 상태 캡슐화**: 관련된 상태와 그 상태를 조작하는 연산들을\n 하나의 클래스 안에 그룹화하세요. 외부에서 상태에 대한 접근은 오직 클래스가\n 제공하는 인터페이스를 통해서만 가능해야 합니다.\n- **의존성 주입(Dependency Injection) 사용**: 객체가 다른 객체에 의존할 때,\n 내부에서 생성하거나 전역 인스턴스를 사용하는 대신, 생성자나 초기화 메서드를 통해\n 외부에서 주입받으세요.\n- **상수는 적절한 범위에 선언**: 프로그램 전반에 걸쳐 변하지 않는 상수 값은\n 불변으로 선언하고, 필요한 가장 좁은 범위(예: 네임스페이스나 클래스)에\n 배치하세요.\n\n### 금지 사항 (Don't)\n\n- **가변 상태를 전역 변수에 저장하지 않기**: 프로그램 실행 흐름 동안 변경되는\n 데이터를 전역 변수로 선언하는 것을 피하세요.\n- **싱글턴(Singleton) 남용하지 않기**: 싱글턴 패턴은 사실상 전역 상태를\n 감싸는 것일 뿐이며 전역 변수와 거의 동일한 문제점(예: 강한 결합, 테스트의\n 어려움)을 공유합니다. 절대적으로 필요한 경우가 아니면 사용을 피하세요.\n- **설정 값을 전역 변수로 관리하지 않기**: 설정 값들은 명시적인 구조체나\n 클래스로 그룹화하여 필요한 곳에 전달하는 것이 더 좋습니다.\n\n## 4. 코드 예시\n\n### 좋은 예: 상태를 명시적으로 전달하는 코드\n\n```pseudocode\n// 설정 값을 관리하기 위한 데이터 구조.\nclass GameConfig {\n property screenWidth: Integer\n property screenHeight: Integer\n}\n\n// Renderer는 GameConfig에 의존하며 생성자를 통해 이를 받는다.\nclass Renderer {\n private config: GameConfig\n\n constructor(config: GameConfig) {\n this.config = config\n }\n\n function render(scene: Scene) {\n // ... config와 scene 데이터를 사용하여 렌더링 ...\n }\n}\n\n// Game 클래스는 자신의 상태(mainScene)와 설정(config)을 관리하며\n// 필요에 따라 Renderer에 전달한다.\nclass Game {\n private config: GameConfig\n private mainScene: Scene\n private renderer: Renderer\n\n constructor() {\n this.config = new GameConfig(screenWidth: 1920, screenHeight: 1080)\n this.mainScene = new Scene()\n this.renderer = new Renderer(this.config)\n }\n\n function loop() {\n // ... 게임 로직이 mainScene을 수정 ...\n this.renderer.render(this.mainScene)\n }\n}\n```\n\n### 나쁜 예: 전역 변수를 사용하는 코드\n\n```pseudocode\n// 나쁜 예: 전역 변수는 코드의 흐름을 예측하기 어렵게 만든다.\nglobal_variable config = new GameConfig(screenWidth: 1920, screenHeight: 1080) // 전역 설정\nglobal_variable mainScene = new Scene() // 전역 씬\n\nclass Renderer {\n function render() {\n // 전역 변수 config와 mainScene을 암묵적으로 사용한다.\n // 이 함수가 올바르게 작동하려면 외부의 전역 상태가 미리 준비되어 있어야 한다.\n // 사용 예: draw(mainScene, config.screenWidth, config.screenHeight)\n }\n}\n\nclass Game {\n private renderer: Renderer\n\n constructor() {\n this.renderer = new Renderer()\n }\n\n function loop() {\n // 게임 로직이 전역 변수 mainScene을 수정한다.\n // 어떤 함수가 언제, 어떻게 mainScene을 바꾸는지 추적하기 어렵다.\n mainScene.update()\n this.renderer.render()\n }\n}\n```\n\n```\n\n#### 2. 불변성 선호 원칙 문서 생성\n\n이 액션은 상태가 생성 시 고정되는 불변 객체를 선호하는 원칙을 문서화합니다. 불변성은 코드에 대한 추론을 극적으로 단순화하고, 예기치 않은 상태 변경과 관련된 많은 종류의 버그를 제거하며, 본질적으로 스레드에 안전합니다. 이 원칙은 예측 가능하고 안정적인 시스템을 구축하는 데 핵심적입니다. 그 사용을 장려하기 위해 다음 파일을 생성합니다.\n\n**파일**: `principles/design-principles/prefer-immutability.md`\n\n```markdown\n# 원칙: 불변성을 선호하라\n\n**Tags**: 설계 원칙, 불변성, 안정성\n\n---\n\n## 1. 핵심 정의\n\n> 객체와 데이터를 생성 후에 그 상태가 변하지 않도록 설계하는 것을 우선시하라.\n> 즉, 변경이 필요할 때는 기존 객체를 수정하는 대신 새로운 객체를 반환하라.\n\n## 2. 근거 (왜 필요한가?)\n\n가변 상태는 프로그램 복잡성의 주된 원인입니다. 프로그램 실행 중 여러 곳에서\n객체의 상태가 변경될 수 있다면, 특정 시점의 상태를 추론하고 예측하기가 매우\n어려워집니다. 이는 특히 동시성 환경에서 문제가 됩니다. 여러 스레드가 공유된 가변\n객체에 동시에 접근하고 수정하려 할 때, 데이터 경합이 발생하여 프로그램 상태를\n손상시키고 예측 불가능한 동작을 일으킬 수 있습니다. 불변 객체는 생성 후 상태가 절대\n변하지 않으므로, 어떠한 동기화 메커니즘 없이도 여러 스레드 간에 안전하게 공유될 수\n있습니다. 더욱이, 객체의 상태가 고정되어 있기 때문에 코드의 동작을 이해하고\n디버깅하기가 훨씬 쉬워져, 시스템의 전반적인 안정성과 예측 가능성을 크게\n향상시킵니다.\n\n- _객체의 상태가 예측 가능하기 때문에 코드를 이해하고 추론하기 쉽게 만듭니다._\n- _별도의 잠금(lock)이 필요 없이 스레드에 안전하므로 동시성 프로그래밍을\n 단순화합니다._\n- _불변 객체는 상태가 고정되어 있어 캐싱에 매우 적합합니다._\n- _상태 변경으로 인한 예기치 않은 부작용을 방지하여 시스템 안정성을 높입니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **언어가 제공하는 불변성 키워드 사용**: 많은 언어가 데이터가 변경되지 않아야\n 함을 명시하는 키워드(예: `const`, `final`, `readonly`)를 제공합니다. 이를\n 적극적으로 사용하는 것이 의도치 않은 수정을 막는 가장 기본적인 방법입니다.\n- **생성 시점에 객체 상태 결정**: 객체의 모든 상태를 생성자를 통해 초기화하고,\n 이후에는 변경될 수 없도록 설계하세요. 세터(setter) 메서드를 제공하지 않는 것이\n 가장 좋습니다.\n- **상태 변경 시 새로운 객체 반환**: 상태를 수정해야 한다면, 기존 객체의 상태를\n 변경하는 대신 변경된 상태를 가진 새로운 객체를 생성하여 반환하세요(예:\n `user.withNewAge(31)`).\n- **수정할 필요 없는 데이터를 읽기 전용으로 취급**: 외부 소스로부터 수정할 필요\n 없는 데이터를 받았다면, 불필요한 복사본을 만들지 않고 읽기 전용 타입이나\n 인터페이스를 사용하여 다루세요.\n\n### 금지 사항 (Don't)\n\n- **우회적인 방법으로 불변성 제약 위반하지 않기**: 강제 타입 캐스팅과 같은\n 기능을 사용하여 불변 객체를 수정하는 것은 매우 위험하며, 전체 시스템의 신뢰성을\n 훼손합니다.\n- **내부의 가변 상태를 외부로 직접 노출하지 않기**: 게터(getter)가 내부의\n 리스트나 다른 객체에 대한 직접적인 참조를 반환하면, 그 참조를 통해 외부에서 내부\n 상태를 수정할 수 있습니다. 이는 캡슐화와 불변성을 모두 깨뜨립니다. 반환해야\n 한다면, 방어적 복사본이나 불변 뷰(view)를 제공하세요.\n\n## 4. 코드 예시\n\n### 좋은 예: 새로운 객체를 반환하여 불변성 유지하기\n\n```pseudocode\nclass UserProfile {\n // 모든 속성은 생성 시에만 할당되고 이후 변경될 수 없다\n constant name: String\n constant age: Integer\n\n constructor(name: String, age: Integer) {\n this.name = name\n this.age = age\n }\n\n // 객체의 상태를 바꾸는 대신, 새로운 상태를 가진 새 객체를 반환한다\n function withNewAge(newAge: Integer) {\n return new UserProfile(this.name, newAge)\n }\n\n function print() {\n output \"Name: \" + this.name + \", Age: \" + this.age\n }\n}\n\nfunction main() {\n constant p1 = new UserProfile(\"Alice\", 30)\n\n // p1을 직접 바꾸는 대신, p1을 기반으로 새로운 객체 p2를 생성한다\n constant p2 = p1.withNewAge(31)\n\n p1.print() // 출력: Name: Alice, Age: 30\n p2.print() // 출력: Name: Alice, Age: 31\n}\n```\n\n### 나쁜 예: 가변 상태와 외부 노출\n\n```pseudocode\nclass UserProfile {\n // 속성들이 외부에서 변경될 수 있다\n variable name: String\n variable age: Integer\n variable tags: List\n\n constructor(name: String, age: Integer) {\n this.name = name\n this.age = age\n this.tags = [\"new\", \"active\"]\n }\n\n // 나이를 직접 수정하는 세터\n function setAge(newAge: Integer) {\n this.age = newAge\n }\n\n // 내부의 가변 리스트를 직접 반환한다\n function getTags() {\n return this.tags\n }\n}\n\nfunction main() {\n constant p = new UserProfile(\"Bob\", 40)\n p.setAge(41) // p의 상태가 직접 변경된다\n\n // 게터에서 얻은 리스트를 직접 수정한다\n constant tags = p.getTags()\n tags.add(\"vip\") // UserProfile p의 내부 상태가 외부에서 조작된다\n}\n```\n\n```\n\n---\n\n### 단계 3: 객체 생성 및 생명주기에 대한 원칙 (단순한 생성자, 명확한 생명주기, RAII).\n\n#### 1. 단순한 생성자 원칙 문서 생성\n\n이 액션은 생성자는 멤버 초기화만 수행하는 단순한 작업이어야 한다는 규칙을 성문화합니다. 생성자 내부에 I/O나 네트워크 호출과 같이 복잡하고 실패할 수 있는 로직이 포함되면 오류 처리가 어려워지고, 부분적으로 초기화된 객체가 생길 수 있습니다. 이 원칙은 그러한 로직을 전용 메서드로 분리하여 객체 생성을 예측 가능하고 실패하지 않는 작업으로 만들 것을 장려합니다.\n\n**파일**: `principles/design-principles/simple-constructors.md`\n\n```markdown\n# 원칙: 생성자는 단순하게 유지하라\n\n**Tags**: 설계 원칙, 생성자, 안정성\n\n---\n\n## 1. 핵심 정의\n\n> 객체의 생성자는 실패할 수 있는 복잡한 로직을 포함해서는 안 되며, 멤버 변수를\n> 초기화하는 책임만 져야 한다.\n\n## 2. 근거 (왜 필요한가?)\n\n생성자는 객체가 생성될 때 호출되는 특별한 함수입니다. 만약 생성자가 파일 읽기,\n네트워크 요청, 데이터베이스 연결과 같이 실패할 수 있는 복잡한 작업을 수행하면,\n그 실패를 처리하기가 매우 어려워집니다. 생성자에서의 오류 처리는 까다롭습니다.\n반환 값이 없어 오류 코드를 전달하기 어렵고, 예외를 던지면 부분적으로 초기화된\n객체로 인해 리소스 누수나 불안정한 상태가 발생할 수 있습니다. 생성자가 너무 많은\n일을 하면 객체의 책임이 모호해지고 테스트하기 어려워집니다. 생성자의 역할을 멤버\n변수 할당으로 제한함으로써, 객체 생성은 예측 가능하고 항상 성공하는 작업이\n됩니다. 실패할 수 있는 로직은 별도의 초기화 함수(예: `connect()`)나 팩토리\n패턴을 통해 명시적으로 관리하는 것이 더 좋습니다.\n\n- _객체 생성이 반드시 성공하도록 보장하여 시스템 안정성을 높입니다._\n- _생성 실패 시 리소스 누수와 같은 문제를 방지합니다 (예외 처리가 특히\n 어렵기 때문)._\n- _테스트하기 쉬운, 객체 책임이 명확한 구조로 이어집니다._\n- _복잡한 초기화 로직을 별도의 메서드로 분리하여 코드 가독성과 유지보수성을\n 향상시킵니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **멤버 변수 할당에 집중**: 생성자는 인자를 멤버 변수에 할당하는 단순한\n 작업에만 집중해야 합니다.\n- **실패 가능한 로직은 별도 메서드로 분리**: 파일 I/O, 네트워크 요청, DB 연결\n 등 실패할 수 있는 작업은 생성자 밖의 초기화 메서드(예: `connect()`,\n `load()`)로 분리하세요.\n- **팩토리 패턴(Factory Pattern) 사용**: 객체 생성 과정이 복잡하다면, 정적\n 팩토리 메서드(Static Factory Method)나 팩토리 클래스(Factory Class)를\n 사용하여 생성 로직을 캡슐화하는 것을 고려하세요. 이를 통해 실패 시 `null`이나\n `Optional` 객체를 반환할 수 있어 오류 처리가 명시적이 됩니다.\n\n### 금지 사항 (Don't)\n\n- **생성자에서 복잡한 로직 수행하지 않기**: 생성자에서 예외가 발생하면 객체는\n 완전히 생성되지 않아, 정리 로직이 제대로 실행되지 않아 리소스 누수로 이어지기\n 쉽습니다.\n- **생성자에서 서브클래스가 재정의할 수 있는 메서드 호출하지 않기**: 생성자가\n 실행되는 시점에는 서브클래스가 완전히 초기화되지 않았을 수 있습니다. 이때\n 재정의된 메서드를 호출하면 불완전한 서브클래스의 코드가 실행되어 예기치 않은\n 동작으로 이어질 수 있습니다.\n- **객체를 부분적으로 초기화되지 않은 상태로 두지 않기**: 생성자의 목표는\n 유효하고 일관된 객체를 만드는 것이어야 합니다.\n\n## 4. 코드 예시\n\n### 좋은 예: 별도의 초기화 메서드를 가진 단순한 생성자\n\n```pseudocode\n// DatabaseConfig 클래스는 설정 값만 관리하는 단순한 생성자를 가진다.\nclass DatabaseConfig {\n constant host: String\n constant port: Integer\n\n constructor(host: String, port: Integer) {\n this.host = host\n this.port = port\n }\n}\n\n// DatabaseConnection 클래스는 생성과 연결을 분리한다.\nclass DatabaseConnection {\n constant config: DatabaseConfig\n variable isConnected: Boolean = false\n\n constructor(config: DatabaseConfig) {\n this.config = config\n }\n\n // 실패 가능한 연결 로직은 별도의 메서드로 분리되었다.\n function connect() returns Boolean {\n // ... config를 사용하여 DB에 연결 시도 ...\n if (/* 연결 성공 */) {\n this.isConnected = true\n return true\n } else {\n return false\n }\n }\n}\n```\n\n### 나쁜 예: 생성자에서 복잡한 작업 수행하기\n\n```pseudocode\n// 생성자가 직접적인 DB 연결을 시도하기 때문에 실패 위험이 있다.\nclass DatabaseConnection {\n // ... DB 연결 핸들 ...\n\n // 생성자가 파일 파싱과 DB 연결이라는 복잡하고 실패 가능한 작업을 수행한다.\n constructor(configFile: String) {\n // 1. 설정 파일 읽기 (실패 가능)\n constant config = this.readConfig(configFile)\n if (config == null) {\n throw new Error(\"설정 파일 읽기 실패\")\n }\n\n // 2. DB 연결 (실패 가능)\n constant success = this.establishConnection(config)\n if (!success) {\n throw new Error(\"DB 연결 실패\")\n }\n }\n\n private function readConfig(file: String) { /* ... */ }\n private function establishConnection(config) { /* ... */ }\n}\n\n// 사용 코드\n// 객체 생성이 실패할 수 있어 try-catch 블록이 강제되며,\n// 생성자 어느 부분에서 실패하는지에 따라 리소스 정리가 복잡해진다.\ntry {\n constant db = new DatabaseConnection(\"db.conf\")\n} catch (error) {\n // ... 오류 처리 ...\n}\n```\n\n```\n\n#### 2. 명확한 객체 생명주기 원칙 문서 생성\n\n이 액션은 모든 객체에 대해 명확한 소유권 정책이 중요하다는 점을 문서화합니다. 모호한 소유권은 메모리 누수나 이중 해제와 같은 심각한 런타임 오류로 이어집니다. 이 원칙은 언어 기능(예: 스마트 포인터)을 사용하여 소유권을 명시적으로 만들고 리소스 관리를 자동화하여 프로그램 안정성을 향상시킬 것을 장려합니다.\n\n**파일**: `principles/design-principles/clear-object-lifecycle.md`\n\n```markdown\n# 원칙: 명확한 객체 생명주기를 설계하라\n\n**Tags**: 설계 원칙, 메모리 관리, 소유권, 리소스 관리\n\n---\n\n## 1. 핵심 정의\n\n> 모든 객체는 생성, 소유권, 파괴에 대한 명확한 정책을 가져야 한다. 누가 객체를\n> 생성하고, 누가 소유하며, 누가 최종 해제를 책임지는지가 코드에 명시적으로\n> 드러나야 한다.\n\n## 2. 근거 (왜 필요한가?)\n\n객체의 생명주기가 모호하면 메모리 누수, 이중 해제, 유효하지 않은 메모리 접근과\n같은 심각한 런타임 오류로 이어질 수 있습니다. 특히 동적으로 할당된 객체의 소유권이\n불분명할 때, 코드의 여러 부분이 이를 해제하려 하거나 아무도 해제하지 않는 상황이\n발생합니다. 이는 프로그램의 안정성을 심각하게 훼손하고 디버깅하기 매우 어려운\n버그의 원인이 됩니다. 객체의 생성, 소유권, 파괴에 대한 규칙을 명확히 정의하고,\n언어가 제공하는 리소스 관리 패턴(스마트 포인터, try-with-resources 등)을\n사용하여 코드 수준에서 소유권을 강제함으로써, 리소스 관리가 자동화되고 실수가\n줄어들어 개발자는 비즈니스 로직에 더 집중할 수 있습니다.\n\n- _메모리 누수, 이중 해제와 같은 치명적인 메모리 관련 버그를 예방합니다._\n- _객체 소유권 관계를 명확히 하여 코드 구조를 이해하기 쉽게 만듭니다._\n- _자동화된 리소스 관리를 통해 코드 복잡성을 줄이고 안정성을 향상시킵니다._\n- _누가 객체 해제를 책임져야 하는지에 대한 걱정 없이 더 안전한 코드 개발을\n 가능하게 합니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **언어의 자동 리소스 관리 기능 활용**: C++의 RAII(예: 스마트 포인터),\n Java/C#의 try-with-resources나 `using` 문, Python의 `with` 문과 같이 코드\n 블록을 벗어날 때 리소스가 자동으로 해제되는 패턴을 우선적으로 사용하세요.\n- **소유권을 표현하는 타입 사용**: 동적 할당이 필요할 때, 원시 포인터 대신\n 소유권을 명확히 표현하는 타입(예: 스마트 포인터)을 사용하세요.\n - **유일한 소유권(Unique ownership)**: 소유자가 하나만 있을 수 있음을\n 나타냅니다. 소유자가 파괴될 때 리소스가 해제됩니다.\n - **공유된 소유권(Shared ownership)**: 여러 소유자가 리소스를 공유할 수\n 있음을 나타냅니다. 마지막 소유자가 파괴될 때 리소스가 해제됩니다.\n- **소유권을 명시적으로 이전**: 리소스의 소유권을 한 객체에서 다른 객체로 이전할\n 때, C++의 `move`, Rust의 소유권 이전과 같이 이 이전을 명시적으로 만드는 언어\n 기능을 사용하세요.\n- **팩토리 함수 활용**: 복잡한 객체 생성 로직을 팩토리 함수에 캡슐화하고, 생성된\n 객체의 소유권을 클라이언트에게 명확하게 이전하세요.\n\n### 금지 사항 (Don't)\n\n- **수동으로 리소스 관리하지 않기**: `malloc`/`free`, `new`/`delete`와 같은\n 메모리 할당 및 해제 함수를 수동으로 호출하는 것은 오류가 발생하기 쉬우므로\n 피하세요.\n- **소유권 규칙 위반하지 않기**: 스마트 포인터가 이미 관리하는 리소스를 가져와\n 다른 스마트 포인터로 다시 감싸는 등, 정해진 소유권 규칙을 깨는 행위는 이중 해제와\n 같은 문제를 일으킬 수 있습니다.\n- **소유하지 않은 리소스 해제하지 않기**: 함수가 리소스를 인자로 받지만 소유하지\n 않는다면, 절대 그 리소스를 해제해서는 안 됩니다. 단순히 리소스를 관찰하거나\n 사용하기 위해서는 소유권 없는 참조나 포인터를 사용하세요.\n\n## 4. 코드 예시\n\n### 좋은 예: 자동 리소스 관리 패턴을 사용하는 코드\n\n```pseudocode\n// 팩토리 함수는 생성된 Widget의 소유권을 반환한다.\nfunction createWidget() {\n // UniquePtr는 스코프를 벗어날 때 자동으로 메모리를 해제하는 스마트 포인터이다.\n return new UniquePtr(new Widget());\n}\n\nfunction process() {\n // widgetOwner는 Widget 객체의 유일한 소유자이다.\n // process 함수가 끝나면 widgetOwner가 파괴되고 Widget 객체는 자동으로 해제된다.\n widgetOwner = createWidget();\n widgetOwner.doSomething();\n} // <-- 여기서 widgetOwner가 관리하는 메모리가 자동으로 해제됨\n\n// Manager는 여러 Worker에 대한 공유 소유권을 가진다.\nclass Manager {\n workers: List>;\n\n function addWorker(worker: SharedPtr) {\n this.workers.add(worker);\n }\n}\n```\n\n### 나쁜 예: 수동 리소스 관리를 하는 코드\n\n```pseudocode\n// createWidget은 관리되지 않는 원시 포인터를 반환한다.\n// 이 포인터를 받은 쪽에서 수동으로 해제해야 한다는 것이 암묵적인 약속이다.\nfunction createWidget() {\n return new Widget();\n}\n\nfunction process() {\n pWidget = createWidget();\n pWidget.doSomething();\n // 여기서 메모리 해제를 잊으면 메모리 누수가 발생한다.\n // 만약 pWidget이 다른 곳에서도 사용된다면, 언제 해제해야 할지 모호하다.\n}\n\nfunction anotherProcess() {\n pWidget = createWidget();\n if (pWidget.isInvalid()) {\n // 여기서 반환하면 해제 코드가 실행되지 않아 메모리 누수가 발생한다.\n return;\n }\n // 모든 코드 경로에서 수동으로 해제해야 한다.\n release_resource(pWidget);\n}\n```\n\n```\n\n#### 3. RAII 원칙 문서 생성\n\n이 액션은 C++ 개발의 초석인 RAII(Resource Acquisition Is Initialization) 패턴을 문서화합니다. 이는 리소스 생명주기를 객체 생명주기에 바인딩하여 리소스 관리를 자동화하고 예외 안전성을 보장할 것을 규정합니다. 이 원칙은 리소스 누수를 방지하고 견고하며 유지보수하기 쉬운 코드를 작성하는 데 중요합니다.\n\n**파일**: `principles/design-principles/raii.md`\n\n```markdown\n# 원칙: 리소스 생명주기가 스코프에 따라 자동으로 관리되도록 설계하라\n\n**Tags**: 설계 원칙, 리소스 관리, 안정성, 예외 안전성\n\n---\n\n## 1. 핵심 정의\n\n> 리소스 획득을 객체 생성에, 리소스 해제를 객체 파괴에 바인딩하여, 리소스의\n> 생명주기가 코드의 실행 스코프와 일치하도록 설계하라.\n\n## 2. 근거 (왜 필요한가?)\n\n이 원칙은 메모리, 파일 핸들, 네트워크 소켓과 같은 한정된 리소스의 관리를\n자동화하여, 리소스 누수와 같은 흔한 오류를 근본적으로 방지합니다. 리소스의\n생명주기를 스택에 생성된 객체에 바인딩함으로써, 정상적인 흐름이든 예외 발생이든\n상관없이 객체가 스코프를 벗어날 때 언어의 스코프 규칙에 따라 리소스가 자동으로\n해제됩니다. 이는 코드를 더 안전하고, 깨끗하며, 이해하기 쉽게 만듭니다.\n\n- _리소스 누수를 근본적으로 방지하여 시스템 안정성을 향상시킵니다._\n- _예외가 발생해도 리소스가 해제되도록 보장하여 예외 안전성을 크게\n 향상시킵니다._\n- _정리 코드를 자동으로 호출하여 개발자의 실수를 줄이고, 수동으로\n `close()`, `free()` 등을 호출할 필요가 없게 합니다._\n- _코드를 더 간결하게 만들고 리소스 관리 로직을 한 곳에 캡슐화하여 가독성과\n 유지보수성을 향상시킵니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **언어별 자동 리소스 관리 기능 적극 사용**: C++의 RAII(예: 스마트 포인터),\n Python의 `with` 문, Java의 `try-with-resources`, C#의 `using`, Rust의\n 소유권 시스템, Go의 `defer`와 같이 언어가 제공하는 스코프 기반 리소스 관리\n 메커니즘을 우선적으로 사용하세요.\n- **리소스 관리 로직을 클래스에 캡슐화**: 획득 로직을 생성자에, 해제 로직을\n 소멸자(또는 이에 상응하는 언어 기능)에 배치하여 리소스 관리 책임을 클래스에\n 위임하세요.\n- **리소스 래퍼(wrapper) 생성 및 사용**: 언어에서 직접 지원하지 않는 리소스(예:\n C API가 반환하는 핸들)의 경우, RAII 패턴을 따르는 사용자 정의 래퍼 클래스를\n 만들어 사용하세요.\n\n### 금지 사항 (Don't)\n\n- **수동으로 리소스 해제하지 않기**: `open`/`close`나 메모리 할당/해제 함수를\n 직접 호출하는 등 수동 리소스 관리는 오류가 발생하기 쉽고 예외 안전성을 깨므로\n 피하세요.\n- **관리 객체의 생명주기가 끝난 리소스에 접근하지 않기**: 리소스 관리자 객체가\n 파괴된 후 해당 리소스에 접근하면 댕글링 포인터와 같은 문제로 이어질 수\n 있습니다.\n- **하나의 리소스를 여러 관리자 객체로 관리하지 않기**: 하나의 리소스를 여러 개의\n 독립적인 RAII 객체로 관리하려 하면 이중 해제와 같은 심각한 오류가 발생할 수\n 있습니다.\n\n## 4. 코드 예시\n\n### 좋은 예: 원칙을 준수하는 코드\n\n```pseudocode\n// 스코프 기반 리소스 관리를 사용하는 의사 코드\nfunction processFile(filePath) {\n // 'using_resource'는 'file' 리소스가 블록을 벗어날 때 자동으로\n // 해제되도록 보장하는 언어별 구문이다.\n // (예: Python 'with', C# 'using', Java 'try-with-resources', Go 'defer')\n using_resource (file = open(filePath)) {\n // 파일 사용\n file.write(\"Hello, Scope-Based Resource Management!\")\n }\n // 'using_resource' 블록을 벗어나는 순간 'file'은 자동으로 닫힌다.\n // 블록 내에서 예외가 발생해도 해제는 보장된다.\n}\n```\n\n### 나쁜 예: 원칙을 위반하는 코드\n\n```pseudocode\n// 수동 리소스 관리를 사용하는 의사 코드\nfunction processFile(filePath) {\n File file = open(filePath); // 1. 수동으로 리소스 획득\n\n // 2. 여기서 오류가 발생하면 'close(file)'이 호출되지 않아 리소스 누수가 발생한다.\n if (someConditionFails) {\n return; // 누수 발생!\n }\n\n file.write(\"Hello, manual management!\");\n\n // 3. 수동으로 리소스 해제. 잊기 쉽고 모든 탈출 경로에서 보장하기 어렵다.\n close(file);\n}\n```\n\n```\n\n---\n\n### 단계 4: 코드 명확성에 대한 원칙 (주석보다 코드, 매직 넘버 금지).\n\n#### 1. 주석보다 코드 원칙 문서 생성\n\n이 액션은 코드는 스스로를 문서화해야 한다는 철학을 수립합니다. 이는 복잡한 코드를 주석으로 설명하는 것보다 명확하고 표현력 있는 코드를 작성하는 것을 우선시합니다. 주석은 시대에 뒤떨어지고 오해의 소지가 있을 수 있기 때문입니다. 이 원칙은 주석을 코드가 명확성을 위해 리팩토링이 필요할 수 있다는 신호로 취급합니다.\n\n**파일**: `principles/design-principles/code-over-comments.md`\n\n```markdown\n# 원칙: 주석이 아닌 코드로 설명하라\n\n**Tags**: 설계 원칙, 가독성, 자기 서술적 코드\n\n---\n\n## 1. 핵심 정의\n\n> 코드는 그 자체로 의도를 명확히 설명해야 한다. 주석은 코드가 표현할 수 없는\n> '왜(Why)'를 설명하는 경우나 API 문서화(예: Doxygen) 등 불가피한 경우에만\n> 최소한으로 사용되어야 한다.\n\n## 2. 근거 (왜 필요한가?)\n\n주석은 종종 코드와 동기화되지 않습니다. 코드가 변경될 때 주석 업데이트를 잊기\n쉽고, 오래된 주석은 이해를 방해하고 잘못된 정보를 전달하며 심지어 버그를 유발할\n수도 있습니다. 좋은 코드는 신중하게 선택된 변수 및 함수 이름과 명확한 구조를 통해\n주석 없이도 이해할 수 있어야 합니다. 복잡한 로직을 설명하기 위해 주석을 추가하는\n대신, 그 로직 자체를 더 작고 이해하기 쉬운 함수로 나누는 것이 근본적인 해결책입니다.\n코드는 컴파일러가 검증하는 유일한 진실의 원천이지만, 주석은 그렇지 않습니다.\n따라서 우리의 주된 노력은 코드 자체를 통해 모든 것을 설명하는 데 집중되어야 합니다.\n\n- _주석과 코드의 불일치로 인한 혼란과 버그를 예방합니다._\n- _더 명확하고 표현력 있는 코드 작성을 장려합니다._\n- _리팩토링 필요성의 지표 역할을 합니다. (주석이 필요하다면, 코드가 복잡하다는\n 신호입니다)._\n- _코드 자체가 문서가 되게 하여 유지보수 비용을 줄입니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **설명적인 이름 사용**: 변수, 함수, 클래스에 그 역할과 의도를 명확히 드러내는\n 이름을 선택하세요. `int d;` 대신 `int elapsedTimeInDays;`를 사용하세요.\n- **복잡한 로직을 함수로 추출**: 코드 블록이 너무 복잡해서 긴 주석으로 설명해야\n 한다면, 그 블록을 작은 함수로 추출하고 함수의 이름으로 로직을 설명하세요.\n- **'왜'를 설명하는 주석 작성**: 코드는 '무엇을' 하는지 설명하게 하고, 주석은\n 특정 비즈니스 결정이나 기술적 트레이드오프가 왜 필요했는지와 같은 배경을\n 설명하는 데 사용하세요.\n- **API 문서화를 위해 주석 활용**: API 문서화 도구를 사용하여 외부 API\n 사용자에게 인터페이스의 사용법, 전제 조건, 사후 조건 등을 설명하는 데 주석을\n 적극적으로 사용하세요.\n\n### 금지 사항 (Don't)\n\n- **코드를 그냥 설명하는 주석 작성하지 않기**: `i++; // i를 1 증가시킴`과 같이\n 코드를 단순히 번역하는 주석은 아무런 가치를 제공하지 않습니다.\n- **오래된 주석 남겨두지 않기**: 더 이상 유효하지 않거나 코드와 일치하지 않는\n 주석은 즉시 삭제하거나 업데이트하세요. 주석 처리된 코드도 마찬가지입니다 (버전\n 관리는 Git의 몫입니다).\n- **나쁜 코드를 변명하기 위해 주석 사용하지 않기**: 복잡하고 이해하기 어려운\n 코드를 작성한 뒤 주석으로 땜질하려 하지 말고, 코드 자체를 개선하는 데 시간을\n 투자하세요.\n\n## 4. 코드 예시\n\n### 좋은 예: 코드로 의도 설명하기\n\n```pseudocode\n// 복잡한 조건부 로직을 설명적인 이름을 가진 함수로 추출하여 가독성을 높였다.\nclass UserAccount {\n // ... 멤버 변수 ...\n\n function hasValidCredentials() {\n // ... 유효한 자격 증명을 확인하는 로직 ...\n }\n\n function isWithinGracePeriod() {\n // ... 유예 기간 내에 있는지 확인하는 로직 ...\n }\n\n function hasActiveSubscription() {\n // ... 활성 구독이 있는지 확인하는 로직 ...\n }\n\n function canLogin() {\n // 주석 없이도 함수 이름만으로 '로그인 조건'이 쉽게 이해된다.\n return this.hasValidCredentials() and\n (this.isWithinGracePeriod() or this.hasActiveSubscription());\n }\n}\n```\n\n### 나쁜 예: 복잡한 코드를 주석으로 설명하기\n\n```pseudocode\nclass UserAccount {\n // ... 멤버 변수 ...\n\n function canLogin() {\n // 나쁜 예: 사용자가 로그인할 수 있는지 확인한다.\n // 사용자는 유효한 자격 증명을 가져야 하며,\n // 유예 기간 내에 있거나 활성 구독이 있어야 한다.\n if (/* 자격 증명을 확인하는 복잡한 로직 */) {\n if (/* 유예 기간을 확인하는 복잡한 로직 */ or /* 구독 상태를 확인하는 복잡한 로직 */) {\n return true;\n }\n }\n return false;\n }\n}\n```\n\n```\n\n#### 2. 매직 넘버 금지 원칙 문서 생성\n\n이 액션은 코드에 이름 없는 하드코딩된 값(\"매직 넘버\")을 사용하는 것을 금지하는 규칙을 문서화합니다. 이 관행은 모호한 숫자를 그 목적을 명확히 설명하는 이름 있는 상수로 대체하여 가독성과 유지보수성을 크게 향상시켜 코드의 의도를 자명하게 만듭니다.\n\n**파일**: `principles/design-principles/no-magic-numbers.md`\n\n```markdown\n# 원칙: 매직 넘버를 사용하지 마라\n\n**Tags**: 설계 원칙, 가독성, 유지보수성\n\n---\n\n## 1. 핵심 정의\n\n> 의미를 알 수 없는 숫자나 문자열(매직 넘버)을 코드에 직접 사용하지 마라.\n> 대신, 그 의미를 명확히 설명하는 이름을 가진 상수로 정의하라.\n\n## 2. 근거 (왜 필요한가?)\n\n매직 넘버는 이해하기 어려운 코드의 주된 원인입니다. `if (user.level == 5)`와\n같은 코드에서 숫자 `5`가 무엇을 의미하는지(예: 관리자 레벨? VIP 사용자?) 즉시\n알 수 없습니다. 이는 독자에게 불필요한 추측을 강요하고 버그의 원인이 될 수\n있습니다. 더욱이, 동일한 매직 넘버가 여러 곳에 흩어져 있는 경우 값을 변경하려면\n모든 인스턴스를 찾아 수정해야 하므로 오류가 발생하기 쉽고 유지보수 비용이\n증가합니다.\n\n- _코드의 의도를 명확하게 하여 가독성을 크게 향상시킵니다._\n- _상수 이름에서 값의 의미를 즉시 파악할 수 있어 디버깅을 더 쉽게 만듭니다._\n- _상수의 정의만 수정하면 값을 변경할 수 있어 유지보수성을 향상시킵니다._\n- _잘못된 값을 실수로 사용하는 것을 방지하여 안정성을 높입니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **의미 있는 이름으로 상수 정의**: 코드의 모든 매직 넘버를 그 목적을 설명하는\n 이름을 가진 상수로 대체하세요(예:\n `const int MAX_CONNECTIONS = 100;`).\n- **관련 상수 그룹화**: 열거형(enum)이나 상수 집합을 사용하여 관련 값들을 함께\n 그룹화하고 관리하세요.\n- **상수는 가능한 가장 좁은 범위에 선언**: 상수가 특정 클래스나 함수 내에서만\n 사용된다면, 불필요한 노출을 피하기 위해 해당 스코프 내에 선언하세요.\n\n### 금지 사항 (Don't)\n\n- **의미를 추측해야 하는 숫자를 코드에 직접 사용하지 않기**: 루프 반복 제어와\n 같은 명백한 경우(`for (int i = 0; i < 3; ++i)`)를 제외하고, 특정 의미를 가진\n 모든 숫자는 상수로 만들어야 합니다.\n- **문자열 리터럴 반복하지 않기**: 설정 키나 이벤트 이름과 같은 문자열도 매직\n 넘버가 될 수 있습니다. 이들도 상수로 정의하여 재사용해야 합니다.\n- **매직 넘버를 주석으로 설명하지 않기**: 의미 있는 이름을 가진 상수를\n 사용하는 것이 주석으로 설명하는 것보다 훨씬 더 나은 접근 방식입니다.\n\n## 4. 코드 예시\n\n### 좋은 예: 원칙을 준수하는 코드\n\n```pseudocode\n// 상수를 사용하여 의미를 명확히 함\nconstant MAX_LOGIN_ATTEMPTS = 5\nconstant SESSION_TIMEOUT_SECONDS = 3600\n\nfunction handleLogin(user, password) {\n if (user.loginAttempts >= MAX_LOGIN_ATTEMPTS) {\n // ... 계정 잠금 처리 ...\n }\n // ...\n}\n\nfunction checkSession(session) {\n if (session.elapsedTime > SESSION_TIMEOUT_SECONDS) {\n // ... 세션 만료 처리 ...\n }\n}\n```\n\n### 나쁜 예: 원칙을 위반하는 코드\n\n```pseudocode\n// 매직 넘버를 사용하면 코드의 의미가 불분명해짐\nfunction handleLogin(user, password) {\n if (user.loginAttempts >= 5) { // 5는 무엇인가? 최대 시도 횟수?\n // ... 계정 잠금 처리 ...\n }\n // ...\n}\n\nfunction checkSession(session) {\n if (session.elapsedTime > 3600) { // 3600은 초인가? 밀리초인가? 한 시간인가?\n // ... 세션 만료 처리 ...\n }\n}\n```\n\n```\n\n---\n\n### 단계 5: 타입 안전성 및 표현식에 대한 원칙 (암묵적 변환 금지, 연산자 오버로딩).\n\n#### 1. 암묵적 변환 금지 원칙 문서 생성\n\n이 액션은 모든 타입 변환은 명시적이어야 한다는 규칙을 수립합니다. 암묵적 변환에 의존하면 의도치 않은 함수 호출이나 데이터 손실로 인한 미묘한 버그가 발생할 수 있으며, 이는 추적하기 어렵습니다. 변환을 명시적으로 만들면 개발자 의도가 명확해지고, 타입 시스템이 강화되며, 전반적인 코드 예측 가능성과 안정성이 향상됩니다.\n\n**파일**: `principles/design-principles/no-implicit-conversions.md`\n\n```markdown\n# 원칙: 암묵적 타입 변환을 허용하지 마라\n\n**Tags**: 설계 원칙, 타입 안전성, 명시성\n\n---\n\n## 1. 핵심 정의\n\n> 모든 타입 변환은 컴파일러나 런타임에 의해 암묵적으로 일어나도록 내버려 둬서는\n> 안 된다. 대신, 개발자의 의도가 코드에 명확히 보이도록 명시적인 함수나 구문을\n> 사용해 수행해야 한다.\n\n## 2. 근거 (왜 필요한가?)\n\n암묵적 타입 변환은 때때로 코드를 더 간결하게 보이게 할 수 있지만, 심각한 버그의\n원인이 될 수도 있습니다. 컴파일러는 개발자의 의도와 다르게 타입을 변환할 수 있으며,\n이는 예기치 않은 함수 호출이나 데이터 손실(예: `double`에서 `int`로 변환)로\n이어질 수 있습니다. 이러한 문제는 종종 컴파일 시점에 발견되지 않고 미묘한 런타임\n버그로 나타나 추적하기 매우 어렵습니다. 타입 변환을 명시적으로 만들면 코드\n가독성이 향상되고 타입 관련 실수를 조기에 발견할 수 있어, 시스템 안정성과 예측\n가능성을 크게 향상시킵니다.\n\n- _의도치 않은 함수 오버로드 해결로 인한 버그를 예방합니다._\n- _데이터 손실이나 정밀도 손실과 같은 미묘한 문제를 피합니다._\n- _코드에서 타입 변환 지점을 명확하게 만들어 가독성과 유지보수성을\n 향상시킵니다._\n- _타입 시스템을 강화하여 더 많은 오류를 컴파일 시점에 발견할 수 있게 합니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **명시적 변환 함수 사용**: `int(value)`, `str(value)`, `parseInt(str)`와 같이\n 언어에 내장된 변환 함수나 유틸리티를 사용하여 변환 의도를 코드에 명확히\n 표현하세요.\n- **변환을 위한 정적 팩토리 메서드 제공**: 객체를 다른 타입으로부터 생성해야 할\n 때, 암묵적 변환을 유발하는 생성자 대신 `MyObject.from(otherType)`과 같이\n 의도가 명확한 정적 팩토리 메서드를 제공하는 것을 고려하세요.\n\n### 금지 사항 (Don't)\n\n- **느슨한 타입 변환에 의존하지 않기**: `\"5\" + 1`이 `\"51\"`이 될지 `6`이 될지처럼,\n 연산자의 동작이 문맥에 따라 달라지는 모호한 코드를 작성하지 마세요.\n- **의도가 불분명한 변환을 허용하는 API 만들지 않기**: 단일 숫자를 받아 복잡한\n 객체를 만드는 생성자(예: 그것이 ID인지 개수인지?)와 같이 사용자의 의도와 다르게\n 동작할 수 있는 인터페이스를 설계하지 마세요.\n- **컴파일러의 지능에 의존하지 않기**: 컴파일러가 타입을 알아서 맞춰줄 것이라고\n 기대하지 마세요. 모든 변환을 명시적으로 만들어 의도를 명확히 하세요.\n\n## 4. 코드 예시\n\n### 좋은 예: 명시적 변환을 강제하는 설계\n\n```pseudocode\nclass FileHandle {\n // 생성자는 직접 호출할 수 없도록 설계되었다 (예: private).\n private constructor(path: String) {\n // ... 파일 열기 로직 ...\n }\n\n // 파일을 열기 위한 명시적인 정적 메서드를 제공한다.\n static function open(path: String) {\n return new FileHandle(path)\n }\n}\n\nfunction readFile(handle: FileHandle) {\n // ... 파일 읽기 로직 ...\n}\n\nfunction good_usage() {\n // readFile(\"/path/to/file.txt\") // 오류! 타입 불일치.\n\n // 의도가 명확하다: 파일을 '열고(open)', 그 핸들로 '읽는다(read)'.\n constant handle = FileHandle.open(\"/path/to/file.txt\")\n readFile(handle)\n}\n```\n\n### 나쁜 예: 암묵적 변환으로 인한 모호함\n\n```pseudocode\nclass FileHandle {\n // 생성자가 문자열을 받아 암묵적 변환을 허용한다.\n constructor(path: String) {\n // ... 파일 열기 로직 ...\n print(\"File opened: \" + path)\n }\n}\n\nfunction readFile(handle: FileHandle) {\n // ... 파일 읽기 로직 ...\n}\n\nfunction bad_usage() {\n // 개발자는 파일 경로의 유효성을 검사하는 함수를 호출하려 했을 수 있다.\n // 하지만 비슷한 이름의 readFile 함수에 문자열을 직접 전달했다.\n // 언어는 \"/path/to/file.txt\"를 FileHandle 객체로 암묵적으로 변환하여,\n // 파일을 여는 의도치 않은 부작용을 일으켰다.\n readFile(\"/path/to/file.txt\")\n}\n```\n\n```\n\n#### 2. 연산자 오버로딩 사용 원칙 문서 생성\n\n이 액션은 연산자 오버로딩 사용에 대한 가이드라인을 문서화합니다. 벡터, 행렬과 같이 직관적인 수학적 또는 논리적 의미를 가진 타입에 신중하게 사용될 때, 이는 코드를 더 표현력 있고 가독성 있게 만들어 도메인별 표기법을 반영할 수 있습니다. 이 원칙은 직관적이지 않거나 혼란스러운 오버로드를 피하면서 이 기능을 효과적으로 사용하기 위한 규칙을 제공합니다.\n\n**파일**: `principles/design-principles/use-operator-overloading.md`\n\n```markdown\n# 원칙: 표현식을 명확히 하기 위해 연산자 오버로딩을 사용하라\n\n**Tags**: 설계 원칙, 가독성, 표현력\n\n---\n\n## 1. 핵심 정의\n\n> 타입이 명확하고 직관적인 수학적 또는 논리적 의미를 가질 때, 연산자 오버로딩을\n> 사용하여 코드 표현력을 높이고 도메인 언어와 유사한 자연스러운 구문을\n> 사용하라.\n\n## 2. 근거 (왜 필요한가?)\n\n신중하게 사용될 때, 연산자 오버로딩은 코드를 수학 공식이나 표준 논리 표현식처럼\n읽히게 만들 수 있습니다. 예를 들어, 두 벡터를 더하는 코드를 `c = a.add(b)` 대신\n`c = a + b`로 작성할 수 있다면, 코드의 의도가 훨씬 더 명확하고 간결해집니다. 이는\n도메인 개념을 코드로 직접 번역하는 효과를 가져와, 개발자의 인지 부하를 줄이고 코드\n가독성을 극대화합니다.\n\n- _수학 및 논리 표현식을 더 자연스럽게 만들어 코드 가독성을 향상시킵니다._\n- _복잡한 객체 연산을 간결하게 표현하여 코드의 양을 줄입니다._\n- _도메인 전문가가 코드를 이해하는 장벽을 낮춥니다._\n- _템플릿 기반 제네릭 코드에서 유연하게 작동하는 타입을 만들 수 있게 합니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **연산자의 원래 의미 유지**: `+`는 덧셈, `*`는 곱셈, `==`는 동등성 비교와 같이\n 사람들이 일반적으로 기대하는 의미와 일관되게 연산자를 오버로딩하세요.\n- **수학적 타입에 적극적으로 사용**: 벡터, 행렬, 복소수, 좌표와 같은 수학적\n 개념을 나타내는 클래스에 사용하면 매우 효과적입니다.\n- **언어의 관용적 패턴 따르기**: 반복자나 다른 일반적인 패턴에서 언어의 표준\n 라이브러리가 연산자를 사용하는 방식을 따라 일관성을 유지하세요.\n- **일관된 쌍 제공**: `==`를 오버로딩했다면 `!=`도 제공하세요. `+`를\n 오버로딩했다면 `+=`도 제공하는 것을 고려하세요.\n\n### 금지 사항 (Don't)\n\n- **직관적이지 않은 의미로 오버로딩하지 않기**: `+` 연산자로 두 데이터베이스\n 연결을 결합하는 것과 같이, 연산자의 상식적인 의미와 완전히 다른 동작을\n 할당해서는 안 됩니다.\n- **모든 연산자를 오버로딩하려 하지 않기**: 필요한 연산자만 최소한으로\n 오버로딩하세요. 남용은 코드를 더 혼란스럽게 만들 수 있습니다.\n- **언어의 기본 동작을 예측 불가능하게 바꾸지 않기**: `&&`와 `||`처럼 단락\n 평가(short-circuit evaluation)를 수행하는 연산자를 오버로딩하는 것은\n 사용자의 예측과 다른 동작으로 이어질 수 있으므로 피해야 합니다.\n- **명시적 변환 함수 우선시**: 객체를 문자열로 변환하는 등의 목적을 위해서는\n 연산자 오버로딩보다 `toString()`과 같이 명시적인 이름의 함수를 제공하는 것이\n 더 명확할 수 있습니다.\n\n## 4. 코드 예시\n\n### 좋은 예: 원칙을 준수하는 코드\n\n```pseudocode\n// 연산자 오버로딩을 사용한 Vector2D 클래스의 의사 코드\nclass Vector2D {\n number x, y\n\n // 덧셈 연산자(+) 정의\n define operator + (other) {\n return new Vector2D(this.x + other.x, this.y + other.y)\n }\n\n // 동등성 비교 연산자(==) 정의\n define operator == (other) {\n return this.x == other.x and this.y == other.y\n }\n}\n\n// 사용 예: 코드가 수학 표현식과 유사해짐\nVector2D v1 = new Vector2D(1, 2)\nVector2D v2 = new Vector2D(3, 4)\nVector2D v3 = v1 + v2 // v3는 (4, 6)\n\nif (v3 == new Vector2D(4, 6)) {\n // ...\n}\n```\n\n### 나쁜 예: 원칙을 위반하는 코드\n\n```pseudocode\n// 연산자 오버로딩 없이 메서드를 사용\nclass Vector2D {\n number x, y\n\n function add(other) {\n return new Vector2D(this.x + other.x, this.y + other.y)\n }\n\n function isEqual(other) {\n return this.x == other.x and this.y == other.y\n }\n}\n\n// 사용 예: 코드가 더 장황하고 덜 직관적임\nVector2D v1 = new Vector2D(1, 2)\nVector2D v2 = new Vector2D(3, 4)\nVector2D v3 = v1.add(v2)\n\nif (v3.isEqual(new Vector2D(4, 6))) {\n // ...\n}\n```\n\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n개발자는 작업이 올바르게 완료되었는지 확인하기 위해 다음 작업을 수행해야 합니다.\n\n1. **파일 생성 확인**: 지정된 모든 마크다운 파일이 `principles/design-principles/` 디렉터리에 생성되었는지 확인합니다.\n2. **자동 포매터 실행**: 프로젝트의 포매팅 스크립트를 실행하여 모든 새 문서가 리포지토리의 스타일 가이드라인을 준수하는지 확인합니다.\n\n```bash\n# 1. scripts/executables 디렉터리로 이동합니다\ncd scripts/executables\n\n# 2. 포매터 스크립트를 실행합니다\n./run_formatters.sh\n```\n\n### 4.2. 예상 결과\n\n검증 스크립트는 오류 없이 완료되어야 합니다. 출력은 모든 파일이 확인되었고 올바르게 포맷되었음을 확인해야 합니다.\n\n```\n[INFO] 마크다운 파일 포맷을 위해 Prettier를 실행합니다...\n[SUCCESS] 모든 마크다운 파일이 올바르게 포맷되었습니다.\n\n[INFO] 마크다운 파일을 검사하기 위해 markdownlint를 실행합니다...\n[SUCCESS] 모든 마크다운 파일이 린트 검사를 통과했습니다.\n\n[INFO] 모든 포매터와 린터가 성공적으로 통과했습니다.\n```","SRP, 불변성부터 리소스 관리에 이르기까지 다양한 주제를 다루는 모범 사례 모음",[140,142,144,146,148],{"_24":141,"_83":39,"_84":94,"_85":61},"책임 및 범위 원칙 (SRP, 좁은 범위)",{"_24":143,"_83":39,"_84":94,"_85":88},"상태 관리 원칙 (전역 변수 금지, 불변성 선호)",{"_24":145,"_83":39,"_84":94,"_85":91},"객체 생성 및 생명주기 원칙 (단순한 생성자, 명확한 생명주기, RAII)",{"_24":147,"_83":39,"_84":94,"_85":94},"코드 명확성 원칙 (주석보다 코드, 매직 넘버 금지)",{"_24":149,"_83":39,"_84":94,"_85":97},"타입 안전성 및 표현식 원칙 (암시적 변환 금지, 연산자 오버로딩)","견고하고 유지보수 가능한 소프트웨어를 설계하기 위한 문서를 작성",{"_22":152,"_24":153,"_75":154,"_77":155,"_79":156,"_51":167,"_42":99},"task-1751363181717","의존성 및 구조 원칙 문서","# 작업: 의존성 및 구조 원칙 문서\n\n> **Epic**: 핵심 개발 원칙 수립\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 코드 의존성 및 프로젝트 구조 관리에 대한 가이드라인 공식화.\n- **근거**: 소프트웨어 컴포넌트 간의 상호작용 방식과 파일 시스템 내에서의 구성 방식을 규정하는, 언어에 구애받지 않는 핵심 규칙을 수립하기 위함입니다. 이러한 표준화는 코드 가독성을 높이고, 유지보수성을 향상시키며, 순환 의존성과 같은 흔한 아키텍처 문제를 방지하고, 프로젝트의 장기적인 확장성을 보장하는 데 매우 중요합니다. 이 원칙들은 모든 후속 언어별 가이드라인의 기초가 될 것입니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: 의존성 선언, 정렬 순서, 프로젝트 폴더 구조화에 대한 규칙 모음.\n- **사양**: 의존성 관리 및 프로젝트 구조와 관련된 특정 원칙을 각각 정의하는 5개의 새로운 마크다운 문서 생성.\n - `principles/dependencies-and-structure/explicit-dependencies.md`\n - `principles/dependencies-and-structure/consistent-dependency-order.md`\n - `principles/dependencies-and-structure/logical-folder-structure.md`\n - `principles/dependencies-and-structure/one-component-per-file.md`\n - `principles/dependencies-and-structure/no-circular-dependencies.md`\n- **결과 파일 구조**\n\n```bash\n./\n└── principles/\n └── dependencies-and-structure/\n ├── consistent-dependency-order.md <-- 신규\n ├── explicit-dependencies.md <-- 신규\n ├── logical-folder-structure.md <-- 신규\n ├── no-circular-dependencies.md <-- 신규\n └── one-component-per-file.md <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 이 작업에서 생성된 원칙이 개발 수명 주기에 어떻게 영향을 미치는지 보여줍니다. 이 원칙들은 개발자가 구현에 앞서 참고하는 기초 자료로서 코드의 아키텍처와 구조를 형성합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"개발 워크플로우\"\n Dev[\"개발자\"] --> Consult[\"원칙 참고
(예: 의존성 및 구조 규칙)\"]\n Consult --> Author[\"코드 및 문서 작성/수정\"]\n Author --> Validate[\"결과물 검증
(로컬 스크립트 및 CI)\"]\n Validate --> Commit[\"리포지토리에 커밋\"]\n end\n\n style Consult fill:#f9f,stroke:#333,stroke-width:2px\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] 명시적 의존성 선언 원칙.\n- [ ] 일관된 의존성 순서 규칙.\n- [ ] 논리적 폴더 구조 원칙.\n- [ ] 파일당 컴포넌트 하나 규칙.\n- [ ] 순환 의존성 방지 원칙.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 리포지토리\n- **주요 관련 컴포넌트**:\n - **엔지니어링 원칙**: 이 작업에서 개발되는 핵심 컴포넌트입니다. 전체 프로젝트에 대한 근본적이고 언어에 구애받지 않는 규칙을 정의하는 책임을 가집니다. 이 작업은 이 컴포넌트의 \"의존성 및 구조\" 하위 도메인을 채우며, 개발자를 안내하고 자동화 도구의 설정을 알리는 소스 오브 트루스(source-of-truth) 문서를 생성합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `principles/dependencies-and-structure/explicit-dependencies.md`\n- `principles/dependencies-and-structure/consistent-dependency-order.md`\n- `principles/dependencies-and-structure/logical-folder-structure.md`\n- `principles/dependencies-and-structure/one-component-per-file.md`\n- `principles/dependencies-and-structure/no-circular-dependencies.md`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공할 것입니다.\n\n---\n\n### 1단계: 명시적 의존성 선언 원칙\n\n#### 1. `explicit-dependencies.md` 문서 생성하기\n\n이 액션은 모든 소프트웨어 모듈이 전이 의존성(transitive dependency)에 의존하지 않고 직접 사용하는 의존성을 명시적으로 선언해야 한다는 원칙을 수립합니다. 이 규칙은 하위 라이브러리가 변경될 때 예기치 않은 빌드 실패를 방지하고 모듈의 요구사항을 투명하게 만들어 빌드 안정성과 코드 명확성의 기초가 됩니다. 다음 내용은 이 규칙, 그 근거, 명확한 예시를 성문화합니다.\n\n**파일**: `principles/dependencies-and-structure/explicit-dependencies.md`\n\n```markdown\n# 원칙: 코드 의존성은 명시적으로 선언하라\n\n**태그**: 의존성 관리, 명시성, 빌드 안정성\n\n---\n\n## 1. 핵심 정의\n\n> 모든 모듈은 자신이 직접 사용하는 모든 외부 컴포넌트를 명시적으로 선언해야 하며, 다른 모듈을 통해 간접적으로 따라오는 전이 의존성에 의존해서는 안 된다.\n\n## 2. 근거 (왜?)\n\n전이 의존성에 의존하는 코드는 매우 취약합니다. 예를 들어, 내가 직접 의존하지 않는 라이브러리 A가 내가 사용하는 라이브러리 B에 포함되어 있다고 가정해 봅시다. 만약 라이브러리 B의 다음 버전이 더 이상 A를 사용하지 않게 되면, 내 코드는 아무런 잘못 없이 빌드에 실패하게 됩니다. 의존 관계가 명시적이지 않으면 시스템의 변경을 예측하기 어렵고, 특정 모듈을 독립적으로 이해하고 재사용하기가 힘들어집니다. 모든 의존성을 명시적으로 선언하면 코드의 요구사항이 명확해지고, 빌드 안정성이 높아지며, 예기치 않은 오류를 방지할 수 있습니다.\n\n- _빌드 시스템의 안정성과 예측 가능성을 높입니다._\n- _다른 개발자들이 코드를 이해하고 유지보수하기 쉽게 만듭니다._\n- _의존성 트리에서 불필요한 컴포넌트를 제거하거나 버전을 관리하기 용이해집니다._\n- _모듈의 재사용성을 높입니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **빌드 시스템에 모든 직접 의존성 선언**: `package.json`(Node.js), `build.gradle`(Java/Kotlin), `requirements.txt`(Python) 등 언어와 프레임워크에 맞는 의존성 관리 파일에 직접 사용하는 모든 라이브러리를 명시적으로 나열하세요.\n- **필요한 모듈을 직접 가져오기**: 코드 파일 내에서 사용되는 모든 모듈, 클래스, 함수는 파일 상단에서 직접 `import` 또는 `require` 구문을 통해 가져와야 합니다.\n\n### 금지 사항 (Don't)\n\n- **전이 의존성을 가정하지 않기**: 내가 임포트한 `moduleA`가 내부적으로 `moduleB`를 임포트한다는 사실에 의존하여, `moduleB`를 임포트하지 않고 코드에서 사용하지 마세요.\n- **와일드카드 임포트 사용 금지**: `from utils import *`와 같이 와일드카드를 사용한 임포트는 어떤 이름이 현재 스코프로 들어오는지 불분명하게 만들어 의존성을 파악하기 어렵게 합니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 의존성을 명시적으로 선언\n\n```pseudocode\n// file: user_service.js\n\n// 직접 사용하는 Logger와 HttpClient를 명시적으로 임포트합니다.\nimport { Logger } from 'logging-library';\nimport { HttpClient } from 'http-client-library';\n\nclass UserService {\n constructor() {\n this.logger = new Logger();\n this.httpClient = new HttpClient();\n }\n\n fetchUser(userId) {\n this.logger.log(`Fetching user ${userId}`);\n return this.httpClient.get(`/users/${userId}`);\n }\n}\n```\n\n### 나쁜 예시: 전이 의존성에 의존\n\n```pseudocode\n// file: http_client_wrapper.js\n// 이 파일은 내부적으로 Logger를 사용하고 임포트합니다.\nimport { Logger } from 'logging-library';\n\nclass HttpClientWrapper {\n constructor() {\n this.logger = new Logger();\n }\n // ... HttpClient 로직 ...\n}\n\n// file: user_service.js\n\n// 나쁜 예시: HttpClientWrapper가 Logger를 임포트한다는 사실에 의존하여\n// 직접 임포트하지 않고 Logger를 사용하려고 시도합니다.\nimport { HttpClientWrapper } from 'http_client_wrapper';\n\nclass UserService {\n constructor() {\n // HttpClientWrapper 사용\n this.httpClient = new HttpClientWrapper();\n\n // 이 코드는 Logger가 무엇인지 몰라서 실패합니다.\n // 만약 HttpClientWrapper가 로깅을 중단하면 이 코드는 즉시 깨집니다.\n this.logger = new Logger();\n }\n // ...\n}\n```\n\n```\n\n---\n\n### 2단계: 일관된 의존성 순서 규칙.\n\n#### 1. `consistent-dependency-order.md` 문서 생성하기\n\n이 액션은 모든 의존성 import 구문이 일관된 그룹화 및 정렬 순서를 따라야 한다는 원칙을 수립합니다. 이 규칙을 준수하면 파일의 의존성 종류(표준, 외부, 내부)를 즉시 파악할 수 있게 되어 코드 가독성이 크게 향상됩니다. 또한 새로운 import를 추가할 위치를 표준화하여 유지보수 및 코드 리뷰를 단순화합니다. 아래 내용은 이 규칙을 정의하며, 이는 나중에 자동화된 포맷터에 의해 강제될 것입니다.\n\n**파일**: `principles/dependencies-and-structure/consistent-dependency-order.md`\n\n```markdown\n# 원칙: 의존성은 일관된 규칙에 따라 정렬하라\n\n**태그**: 의존성 관리, 가독성, 스타일 가이드\n\n---\n\n## 1. 핵심 정의\n\n> 코드 파일 상단에 선언되는 의존성(import 구문)은 프로젝트 전반에 걸쳐 일관된 순서와 그룹화 규칙을 따라야 한다.\n\n## 2. 근거 (왜?)\n\n의존성 선언 순서가 제각각이면 코드를 읽는 사람이 현재 모듈이 어떤 종류의 다른 모듈과 상호작용하는지 한눈에 파악하기 어렵습니다. 표준 라이브러리, 외부 라이브러리, 내부 모듈을 명확히 그룹화하고 각 그룹 내에서 알파벳순으로 정렬하는 등 일관된 규칙을 적용하면 가독성이 크게 향상됩니다. 이는 새로운 의존성을 추가하거나 불필요한 의존성을 제거할 때 실수를 줄이고, 코드 리뷰 시 변경 사항을 쉽게 식별하는 데 도움이 됩니다. 잘 정리된 import 구문은 마치 잘 정리된 서랍과 같아서 필요한 것을 빠르고 정확하게 찾을 수 있게 해줍니다.\n\n- _코드의 가독성과 일관성을 향상시킵니다._\n- _새로운 의존성을 어디에 추가/제거해야 할지 명확히 하여 유지보수를 용이하게 합니다._\n- _코드 리뷰 시 의존성 변경 사항을 쉽게 식별할 수 있게 합니다._\n- _자동 포맷팅 도구(린터, 포맷터)와 함께 사용하면 팀 전체의 코드 스타일을 통일하는 데 도움이 됩니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **그룹화 규칙 수립**: 일반적으로 '표준 라이브러리 → 외부 라이브러리 → 내부 (프로젝트) 모듈' 순서로 그룹화합니다. 시각적 구분을 위해 각 그룹 사이에 빈 줄을 넣으세요.\n- **그룹 내 정렬**: 각 그룹 내에서는 모듈 이름을 기준으로 알파벳순으로 정렬합니다.\n- **자동화 도구 활용**: Prettier, ESLint (JavaScript), isort (Python), goimports (Go)와 같은 언어별 코드 포맷터나 린터를 사용하여 의존성 정렬 규칙을 강제하고 자동화하세요.\n\n### 금지 사항 (Don't)\n\n- **무작위 순서로 의존성 추가 금지**: 생각나는 대로 파일의 아무 곳에나 import 구문을 추가하지 마세요.\n- **그룹화 규칙 무시 금지**: 표준 라이브러리와 내부 모듈의 import를 섞어서 사용하지 마세요.\n\n## 4. 코드 예시\n\n### 좋은 예시: 규칙에 따라 정렬된 의존성\n\n```pseudocode\n// 표준 라이브러리 (알파벳 순)\nimport fs from 'fs';\nimport path from 'path';\n\n// 외부 라이브러리 (알파벳 순)\nimport express from 'express';\nimport lodash from 'lodash';\n\n// 내부 모듈 (알파벳 순)\nimport { ApiClient } from '../shared/api_client';\nimport { User } from './models/user';\nimport { UserService } from './user_service';\n\n// ... 코드 시작 ...\n```\n\n### 나쁜 예시: 정렬되지 않은 의존성\n\n```pseudocode\n// 표준, 외부, 내부 모듈이 뒤섞여 있고, 알파벳 순서도 아닙니다.\nimport { UserService } from './user_service';\nimport express from 'express';\nimport path from 'path';\nimport { ApiClient } from '../shared/api_client';\nimport fs from 'fs';\nimport { User } from './models/user';\nimport lodash from 'lodash';\n\n// ... 코드 시작 ...\n```\n\n```\n\n---\n\n### 3단계: 논리적 폴더 구조 원칙.\n\n#### 1. `logical-folder-structure.md` 문서 생성하기\n\n이 액션은 프로젝트의 디렉토리 구조가 논리적 아키텍처를 반영해야 한다는 원칙을 수립합니다. 잘 정리된 폴더 구조는 시스템의 \"지도\" 역할을 하여 개발자가 파일을 신속하게 찾고 컴포넌트 관계를 이해할 수 있게 합니다. 이는 관련된 파일들을 물리적으로 같은 위치에 배치하여 탐색성과 유지보수성을 향상시킵니다. 아래 내용은 이 구조적 가이드라인을 정의합니다.\n\n**파일**: `principles/dependencies-and-structure/logical-folder-structure.md`\n\n```markdown\n# 원칙: 프로젝트의 폴더 구조는 논리적 구조를 반영해야 한다\n\n**태그**: 프로젝트 구조, 가독성, 유지보수성\n\n---\n\n## 1. 핵심 정의\n\n> 파일 시스템의 폴더와 파일 구조는 소스 코드의 논리적 아키텍처(예: 기능별, 레이어별)를 직접적으로 반영하여, 개발자가 코드베이스를 쉽게 탐색하고 이해할 수 있도록 도와야 한다.\n\n## 2. 근거 (왜?)\n\n잘 설계된 폴더 구조는 프로젝트의 지도와 같습니다. 새로운 개발자가 프로젝트에 합류했을 때, 폴더 구조만 보고도 전체 시스템 구성, 각 기능의 위치, 데이터의 흐름을 직관적으로 파악할 수 있어야 합니다. 만약 폴더 구조가 논리적 구조와 맞지 않으면, 관련된 파일들이 여러 곳에 흩어져 있어 코드를 찾고 수정하는 데 많은 시간이 걸립니다. 이는 생산성을 저해하고 유지보수를 어렵게 만듭니다. 기능 기반이나 레이어 기반과 같은 일관된 규칙에 따라 폴더를 구성하면 코드 응집도를 높이고 결합도를 낮추어 더 건강하고 확장 가능한 아키텍처를 유지할 수 있습니다.\n\n- _프로젝트의 전체 아키텍처를 쉽게 파악할 수 있게 합니다._\n- _관련된 파일을 물리적으로 가까이 두어 코드 탐색을 용이하게 합니다._\n- _새로운 기능을 추가하거나 기존 기능을 수정할 때 영향 범위를 명확히 합니다._\n- _팀 전체의 개발 생산성과 유지보수 효율성을 향상시킵니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **기능 또는 레이어별로 그룹화**: 프로젝트의 특성에 맞는 구조화 방법을 선택하세요.\n - **기능 기반**: 각 기능에 필요한 모든 파일(모델, 뷰, 컨트롤러 등)을 `users`, `products`, `orders` 와 같이 하나의 폴더로 묶습니다. (예: `src/features/users/`)\n - **레이어 기반**: `controllers`, `services`, `repositories` 와 같이 아키텍처 레이어별로 폴더를 구성합니다. (예: `src/controllers/`, `src/services/`)\n- **이름으로 역할 표현**: 폴더와 파일의 이름은 그 역할과 책임을 명확히 드러내야 합니다. (예: `utils`, `config`, `models`, `services`)\n- **일관성 유지**: 프로젝트 전체에 걸쳐 동일한 구조화 규칙을 일관되게 적용합니다.\n\n### 금지 사항 (Don't)\n\n- **모든 파일을 한 폴더에 넣기**: `src` 폴더 아래에 수십 개의 파일을 아무런 구조 없이 나열하지 마세요.\n- **역할을 드러내지 않는 이름 사용 금지**: `misc`, `common`, `temp` 와 같이 모호한 이름의 폴더를 피하세요.\n- **여러 구조화 규칙 혼용 금지**: 어떤 부분은 기능별로, 다른 부분은 레이어별로 구성하는 등 일관성 없는 구조는 혼란을 야기합니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 기능 기반 폴더 구조\n\n```text\n/src\n /features\n /users\n - users.controller.js // 사용자 관련 API 엔드포인트\n - users.service.js // 사용자 관련 비즈니스 로직\n - users.repository.js // 사용자 관련 데이터베이스 접근\n - user.model.js // 사용자 데이터 모델\n - users.test.js // 사용자 기능 테스트\n /products\n - products.controller.js\n - products.service.js\n - ...\n /shared\n /middleware\n - auth.js\n /utils\n - date_formatter.js\n - app.js\n - server.js\n```\n\n### 나쁜 예시: 구조가 없거나 모호한 폴더 구조\n\n```text\n/src\n - user_controller.js\n - product_service.js\n - auth.js\n - db_connect.js\n - user_model.js\n - product_controller.js\n - user_service.js\n - string_utils.js\n - ... (수십 개의 파일이 나열됨)\n```\n\n```\n\n---\n\n### 4단계: 파일당 컴포넌트 하나 규칙.\n\n#### 1. `one-component-per-file.md` 문서 생성하기\n\n이 액션은 각 소스 파일이 단일 핵심 논리 단위(예: 클래스, 모듈)를 정의해야 한다는 \"파일당 컴포넌트 하나\" 원칙을 수립합니다. 이 관행은 코드 응집도를 높이고 시스템을 더 쉽게 탐색하고 유지보수할 수 있게 만듭니다. 파일 이름이 내용과 직접적으로 일치하도록 함으로써, 파일의 목적을 명확히 하고 변경 사항을 단일하고 잘 정의된 컴포넌트에 국한시켜 버전 관리를 단순화합니다.\n\n**파일**: `principles/dependencies-and-structure/one-component-per-file.md`\n\n```markdown\n# 원칙: 파일 하나에는 핵심 컴포넌트 하나만 정의하라\n\n**태그**: 프로젝트 구조, 모듈성, 응집도\n\n---\n\n## 1. 핵심 정의\n\n> 하나의 소스 코드 파일은 클래스, 모듈, 함수 등 핵심적인 논리 단위 하나만 정의해야 한다. 관련된 작은 헬퍼 클래스나 유틸리티 함수는 포함될 수 있지만, 관련 없는 여러 주요 컴포넌트를 한 파일에 배치해서는 안 된다.\n\n## 2. 근거 (왜?)\n\n한 파일에 여러 컴포넌트를 정의하면 파일의 목적이 불분명해지고 특정 컴포넌트를 찾기 어려워집니다. 이는 코드 가독성과 탐색성을 해칩니다. 또한 버전 관리 시스템에서 변경 사항을 추적하기 복잡하게 만듭니다. 예를 들어, 한 파일이 수정되었지만 실제로는 여러 관련 없는 컴포넌트 중 하나만 변경되었다면, 커밋 메시지만으로는 무엇이 변경되었는지 알기 어렵습니다. 각 파일이 단일 책임을 갖도록 하면 파일 이름만으로도 그 내용을 유추할 수 있게 되고, 코드 응집도가 높아져 유지보수와 재사용이 용이해집니다.\n\n- _파일의 역할과 책임을 명확히 하여 코드 가독성을 향상시킵니다._\n- _원하는 컴포넌트를 더 쉽게 찾을 수 있게 하여 코드 탐색 시간을 줄입니다._\n- _버전 관리에서 변경 사항을 추적하고 이해하기 쉽게 만듭니다._\n- _컴포넌트의 재사용성과 테스트 용이성을 높입니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **클래스당 하나의 파일 사용**: `User` 클래스는 `user.js`나 `User.java` 파일에 정의합니다.\n- **하나의 모듈을 위해 하나의 파일 생성**: 특정 기능(예: `string-utils`)을 제공하는 관련 함수 집합은 단일 파일로 묶어 모듈을 형성해야 합니다.\n- **파일 이름을 컴포넌트 이름과 일치**: `UserService` 클래스를 `user.service.js`에 두는 것처럼 파일 이름과 클래스 이름을 일관성 있게 유지하여 찾기 쉽게 만듭니다.\n\n### 금지 사항 (Don't)\n\n- **한 파일에 관련 없는 여러 클래스 넣기 금지**: `User`, `Product`, `Order` 클래스를 모두 `models.js`라는 단일 파일에 정의하지 마세요.\n- **유틸리티 파일에 관련 없는 함수 채워 넣기 금지**: 문자열 조작, 날짜 계산, HTTP 요청과 같은 온갖 종류의 관련 없는 유틸리티 함수를 단일 `utils.js` 파일에 넣는 대신, `string-utils.js`, `date-utils.js` 등으로 분리하세요.\n\n## 4. 코드 예시\n\n### 좋은 예시: 컴포넌트당 파일 하나\n\n```text\n// 파일: user.model.js\nclass User {\n // ... User 클래스 정의 ...\n}\nexport default User;\n```\n\n```text\n// 파일: product.model.js\nclass Product {\n // ... Product 클래스 정의 ...\n}\nexport default Product;\n```\n\n### 나쁜 예시: 한 파일에 여러 컴포넌트 정의\n\n```pseudocode\n// 파일: models.js\n\n// User, Product, Order는 서로 다른 핵심 도메인 모델입니다.\n// 이들을 모두 한 파일에 정의하면 파일의 책임이 불분명해집니다.\nclass User {\n // ...\n}\n\nclass Product {\n // ...\n}\n\nclass Order {\n // ...\n}\n\nexport { User, Product, Order };\n```\n\n```\n\n---\n\n### 5단계: 순환 의존성 방지 원칙.\n\n#### 1. `no-circular-dependencies.md` 문서 생성하기\n\n이 액션은 모듈 간 순환 의존성을 반드시 피해야 한다는 중요한 아키텍처 원칙을 수립합니다. 이러한 의존성은 강한 결합(tight coupling)을 만들어 코드베이스를 경직시키고, 테스트하기 어렵고, 유지보수하기 힘들게 만듭니다. 또한 빌드 실패나 런타임 오류로 이어질 수 있습니다. 이 문서는 규칙을 성문화하고, 건강하고 모듈화되었으며 유연한 시스템 아키텍처를 보장하기 위해 의존성 역전과 같은 예방 전략을 제공합니다.\n\n**파일**: `principles/dependencies-and-structure/no-circular-dependencies.md`\n\n```markdown\n# 원칙: 컴포넌트 간 순환 의존성을 방지하도록 설계하라\n\n**태그**: 의존성 관리, 아키텍처, 결합도\n\n---\n\n## 1. 핵심 정의\n\n> 둘 이상의 컴포넌트가 서로를 직간접적으로 의존하여 순환 관계(A → B → A)가 만들어져서는 안 된다.\n\n## 2. 근거 (왜?)\n\n순환 의존성은 코드베이스의 건강을 해치는 심각한 문제입니다. 두 컴포넌트가 서로를 의존하게 되면, 이들은 강하게 결합(tightly coupled)되어 사실상 하나의 거대한 컴포넌트처럼 작동하게 됩니다. 이는 하나를 수정하는 것이 다른 하나에 예기치 않은 영향을 미칠 수 있어 변경을 어렵게 만듭니다. 더욱이, 순환 의존 관계에 있는 컴포넌트들은 독립적으로 재사용하거나 테스트하기가 거의 불가능합니다. 빌드 시스템에서는 빌드 순서를 결정할 수 없어 빌드 실패를 유발하거나, 런타임에 무한 루프나 스택 오버플로로 이어질 수 있습니다. 의존성이 한 방향으로만 흐르는 비순환 방향 그래프(DAG) 구조를 유지하면 코드 결합도를 낮추고 모듈성과 유연성을 높일 수 있습니다.\n\n- _컴포넌트 간 결합도를 낮춰 코드 변경의 파급 효과를 줄입니다._\n- _각 컴포넌트를 독립적으로 이해하고 테스트하기 쉽게 만듭니다._\n- _빌드 실패나 런타임 오류와 같은 심각한 문제를 예방합니다._\n- _코드 재사용성과 전체 아키텍처의 유연성을 향상시킵니다._\n\n## 3. 실천 방법\n\n### 권장 사항 (Do)\n\n- **의존관계 역전 원칙(DIP) 적용**: 상위 수준 모듈이 하위 수준 모듈에 직접 의존하는 대신, 둘 다 공유된 추상화(인터페이스)에 의존하도록 설계하여 의존성의 방향을 제어합니다.\n- **공통 의존성 추출**: 두 모듈이 서로의 기능이 필요한 경우, 둘 다에게 필요한 공통 기능을 별도의 제3의 모듈로 추출하고, 두 모듈 모두 이 새로운 모듈에 의존하도록 합니다.\n- **이벤트 기반 아키텍처 고려**: 컴포넌트들이 서로를 직접 호출하는 대신, 이벤트를 발행하고 구독함으로써 통신하게 하여 직접적인 의존 관계를 제거합니다.\n\n### 금지 사항 (Don't)\n\n- **하위 수준 모듈이 상위 수준 모듈을 임포트하게 두지 않기**: 비즈니스 로직을 다루는 서비스 계층(`UserService`)이 데이터베이스 접근을 다루는 리포지토리 계층(`UserRepository`)에 의존하는 것은 괜찮지만, 그 반대로 `UserRepository`가 `UserService`에 의존하는 것은 허용되어서는 안 됩니다.\n- **편의를 위해 양방향 관계 생성 금지**: `User` 모델이 `Order` 목록을 가지고, `Order` 모델이 `User` 정보를 갖는 등 양쪽이 서로를 직접 참조하는 관계를 피하세요. 대신 필요할 때 ID를 통해 정보를 조회하도록 설계합니다.\n\n## 4. 코드 예시\n\n### 좋은 예시: 의존성 역전으로 순환 의존성 해결\n\n```pseudocode\n// 1. 추상 인터페이스를 정의합니다.\ninterface NotificationService {\n notify(user, message);\n}\n\n// 2. 상위 수준 모듈(UserService)은 구체적인 구현이 아닌 인터페이스에 의존합니다.\nclass UserService {\n constructor(notificationService: NotificationService) {\n this.notificationService = notificationService;\n }\n\n register(user) {\n // ... 사용자 등록 로직 ...\n this.notificationService.notify(user, \"Welcome!\");\n }\n}\n\n// 3. 하위 수준 모듈(EmailService)은 인터페이스를 구현합니다.\n// 이제 EmailService는 UserService에 대해 알 필요가 없습니다.\nclass EmailService implements NotificationService {\n notify(user, message) {\n // ... 이메일 전송 로직 ...\n }\n}\n// 의존성 방향: UserService -> NotificationService <- EmailService\n```\n\n### 나쁜 예시: 모듈 간의 순환 의존성\n\n```pseudocode\n// file: user_service.js\nimport { OrderService } from './order_service'; // OrderService 임포트\n\nclass UserService {\n findUserOrders(userId) {\n // ...\n return OrderService.getOrdersForUser(userId);\n }\n}\n\n// file: order_service.js\nimport { UserService } from './user_service'; // UserService 임포트 (순환 의존성!)\n\nclass OrderService {\n getOrdersForUser(userId) { ... }\n\n cancelOrder(order) {\n // ... 주문 취소 로직 ...\n // 사용자에게 취소를 알리기 위해 UserService를 사용합니다.\n UserService.notifyCancellation(order.userId);\n }\n}\n```\n\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 이 작업의 성공적인 완료를 검증하기 위해, 개발자는 새로운 마크다운 파일들이 생성되었고 프로젝트의 포맷팅 표준을 준수하는지 확인해야 합니다. 다음 명령어는 프로젝트 루트에서 실행되어야 합니다. (참고: `prettier`와 `markdownlint-cli`가 설치되어 있다고 가정합니다).\n\n```bash\n# 1. 5개의 새 파일이 모두 올바른 디렉토리에 존재하는지 확인합니다.\nls -1 principles/dependencies-and-structure/\n\n# 2. 새 디렉토리에 대해 Prettier를 실행하여 포맷팅을 확인합니다.\n# --check 플래그는 변경 없이 포맷팅을 검증합니다.\nnpx prettier --check principles/dependencies-and-structure/\n\n# 3. markdownlint를 실행하여 스타일 가이드 위반 사항이 있는지 확인합니다.\nnpx markdownlint-cli principles/dependencies-and-structure/*.md\n```\n\n### 4.2. 예상 결과\n\n- `ls` 명령어는 5개의 새로운 마크다운 파일을 나열해야 합니다.\n- `prettier` 및 `markdownlint-cli` 명령어는 오류 없이 실행되고 상태 코드 0으로 종료되어야 하며, 이는 모든 파일이 올바르게 포맷되었고 린팅 규칙을 준수함을 나타냅니다.\n\n```\n$ ls -1 principles/dependencies-and-structure/\nconsistent-dependency-order.md\nexplicit-dependencies.md\nlogical-folder-structure.md\nno-circular-dependencies.md\none-component-per-file.md\n\n$ npx prettier --check principles/dependencies-and-structure/\nChecking formatting...\nAll matched files use Prettier code style!\n\n$ npx markdownlint-cli principles/dependencies-and-structure/*.md\n(출력이 없으면 성공을 의미합니다)\n```","의존성 선언, 정렬 순서, 프로젝트 폴더 구조 구성을 위한 규칙 세트",[157,159,161,163,165],{"_24":158,"_83":39,"_84":97,"_85":61},"명시적 의존성 선언 원칙",{"_24":160,"_83":39,"_84":97,"_85":88},"일관된 의존성 정렬 규칙",{"_24":162,"_83":39,"_84":97,"_85":91},"논리적 폴더 구조 원칙",{"_24":164,"_83":39,"_84":97,"_85":94},"파일당 하나의 컴포넌트 규칙",{"_24":166,"_83":39,"_84":97,"_85":97},"순환 의존성 방지 원칙","코드 의존성 및 프로젝트 구조 관리를 위한 가이드라인을 공식화",{"_22":169,"_24":170,"_75":171,"_77":172,"_79":173,"_51":183,"_42":99},"task-1751363234201","원칙 색인 문서","# 작업: 원칙 인덱스 문서\n\n> **에픽**: 핵심 개발 원칙 수립\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 모든 개별 원칙 문서로 연결되는 마스터 README 파일을 생성합니다.\n- **근거**: 언어에 구애받지 않는 모든 엔지니어링 원칙을 한곳에서 쉽게 찾아볼 수 있는 중앙 진입점을 제공하기 위함입니다. 이 인덱스는 원칙들의 발견 가능성을 높이는 데 핵심적이며, 개발자가 프로젝트 개발 수명 주기의 기반이 되는 규칙들을 쉽게 찾고 참조할 수 있도록 합니다. 이는 잘 구조화되고 읽기 쉬운 지식 기반을 구축한다는 핵심 목표를 직접적으로 지원합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: 명확하게 분류되어 탐색하기 쉬운 중앙 개발 원칙 인덱스.\n- **명세**:\n - `principles/README.md`에 위치한 단일 마크다운 파일.\n - 파일에는 목적, 범위, 대상을 상세히 기술하는 \"개요(Overview)\" 섹션이 포함되어야 합니다.\n - 파일에는 모든 주요 제목으로 연결되는 내부 링크가 포함된 \"목차(Table of Contents)\" 섹션이 포함되어야 합니다.\n - 파일에는 원칙을 핵심 철학(Core Philosophy), 개발 프로세스(Development Process), 이름 짓기(Naming), 서식(Formatting), 설계 원칙(Design Principles), 의존성 및 구조(Dependencies & Structure) 카테고리로 그룹화한 \"카테고리별 원칙(Principles by Category)\" 섹션이 포함되어야 합니다.\n - 나열된 각 원칙은 상대 경로를 사용하여 해당 상세 문서로 연결되는 하이퍼링크여야 합니다.\n- **결과 파일 구조**\n 이 작업을 통해 `principles/` 디렉터리에 하나의 파일이 생성되거나 업데이트됩니다.\n\n```bash\n# ./\n# └── principles/\n# └── README.md <-- New/Modified\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 엔지니어링 원칙을 탐색하는 사용자의 의도된 흐름을 보여주며, 인덱스 파일이 중앙 허브 역할을 합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n Dev[\"개발자\"] --> Readme[\"메인 리포지토리 README 참조\"];\n Readme --> PrinciplesIndex[\"'principles/README.md'로 이동\"];\n PrinciplesIndex --> Toc[\"목차를 사용해 카테고리 검색\"];\n Toc --> PrincipleList[\"목록에서 특정 원칙 선택\"];\n PrincipleList --> PrincipleDoc[\"상세 원칙 문서 조회
(예: 'readability-first.md')\"];\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이것은 상위 수준의 체크리스트이며, 각 항목에 대한 상세 구현은 3절에 있습니다.\n\n- [ ] 문서 개요 섹션 작성.\n- [ ] 목차 생성.\n- [ ] 원칙을 논리적 그룹으로 분류.\n- [ ] 모든 개별 원칙 마크다운 파일 링크 연결.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 저장소\n- **관련 주요 구성 요소**:\n - **엔지니어링 원칙**: 이 작업은 \"엔지니어링 원칙\" 구성 요소의 핵심입니다. 이 구성 요소 내에 정의된 모든 원칙에 대한 기본 탐색 및 인덱스 문서를 생성합니다. 프로젝트의 기본 규칙을 접근하기 쉽고 이해하기 쉽게 만드는 책임을 집니다.\n - **언어 가이드라인**: 이 구성 요소는 하위 소비자입니다. 모든 특정 언어 가이드라인은 이 문서에 의해 인덱싱된 기본 규칙을 기반으로 구축되어 여러 기술 간의 일관성을 보장합니다.\n - **문서 템플릿**: 이 인덱스 문서의 구조와 스타일은 템플릿에 의해 설정된 표준을 암묵적으로 참조하며, 고품질 문서 결과물의 예시가 되어야 합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `principles/README.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계(Step)`는 **완료 조건**의 각 항목에 해당합니다. 각 `단계`는 일련의 세부적인 `액션(Action)`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을', '왜' 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 문서 개요 섹션 작성\n\n#### 1. 헤더 및 개요 콘텐츠 추가\n\n이 액션은 문서의 정체성과 목적을 설정합니다. 메인 `H1` 헤더는 페이지의 제목을 명확히 나타냅니다. \"개요\" 섹션은 모든 개발자에게 문서의 목적, 범위, 그리고 대상 독자에 대한 맥락을 제공하며, 의도를 명확히 한다는 원칙과 일치합니다.\n\n**File**: `principles/README.md`\n\n```markdown\n# 개발 원칙\n\n이 문서는 우리 프로젝트의 보편적인 개발 원칙을 설명합니다.\n이 원칙들은 코드 가독성, 유지보수성, 일관성을 보장하고,\n주관적인 논쟁과 인지 부하를 최소화하기 위해 설계되었습니다.\n\n---\n\n## 개요\n\n- **목적**: 모든 개발 원칙에 대한 명확하고 중앙화된 가이드를 제공합니다.\n- **범위**: 언어와 관계없이 이 프로젝트를 위해 작성된 모든 코드에 적용됩니다.\n- **대상**: 프로젝트의 모든 개발자 및 기여자.\n\n---\n```\n\n---\n\n### 단계 2: 목차 생성\n\n#### 1. 목차 만들기\n\n이 액션은 탐색 가능한 목차(TOC)를 추가합니다. 목차는 긴 문서에서 개발자가 문서 구조를 빠르게 훑어보고 관심 있는 섹션으로 바로 이동할 수 있게 하여 사용성과 효율성을 향상시키는 데 필수적입니다. 링크는 이후 단계에서 생성될 `H2` 및 `H3` 헤딩과 일치해야 합니다.\n\n**File**: `principles/README.md`\n\n```markdown\n...\n\n## 목차\n\n- [개발 원칙](#development-principles)\n - [개요](#overview)\n - [목차](#table-of-contents)\n - [카테고리별 원칙](#principles-by-category)\n - [1. 핵심 철학](#1-core-philosophy)\n - [2. 개발 프로세스](#2-development-process)\n - [3. 이름 짓기](#3-naming)\n - [4. 서식](#4-formatting)\n - [5. 설계 원칙](#5-design-principles)\n - [6. 의존성 및 구조](#6-dependencies--structure)\n\n---\n```\n\n---\n\n### 단계 3: 원칙을 논리적 그룹으로 분류\n\n#### 1. 메인 콘텐츠 영역 구조화\n\n이 액션은 주요 콘텐츠 섹션과 그 범주별 부제목을 생성합니다. 원칙을 \"핵심 철학\", \"이름 짓기\"와 같은 논리적 그룹으로 구조화하면 정보를 더 쉽게 처리하고 찾을 수 있습니다. 각 카테고리는 목차 항목과 일치하는 `H3` 헤딩과 카테고리의 주제를 요약하는 인용문으로 시작됩니다.\n\n**File**: `principles/README.md`\n\n```markdown\n...\n\n## 카테고리별 원칙\n\n### 1. 핵심 철학\n\n> 우리의 기술적 결정을 안내하는 근본적인 가치.\n\n### 2. 개발 프로세스\n\n> 우리의 개발 워크플로우와 관행을 지배하는 규칙.\n\n### 3. 이름 짓기\n\n> 명확하고 모호하지 않은 이름을 만들기 위한 가이드라인.\n\n### 4. 서식\n\n> 일관되고 가독성 있는 코드 서식을 유지하기 위한 규칙.\n\n### 5. 설계 원칙\n\n> 견고하고 유지보수 가능한 소프트웨어를 설계하기 위한 모범 사례.\n\n### 6. 의존성 및 구조\n\n> 의존성을 관리하고 코드를 구조화하기 위한 가이드라인.\n```\n\n---\n\n### 단계 4: 모든 개별 원칙 마크다운 파일 링크 연결\n\n#### 1. 모든 카테고리에 원칙 링크 채우기\n\n이 마지막 액션 세트는 각 카테고리에 해당하는 원칙의 글머리 기호 목록을 채웁니다. 각 목록 항목은 원칙에 대한 간결한 설명과 원칙이 상세히 기술될 파일로 연결되는 상대 마크다운 링크를 제공합니다. 이 단계는 문서를 구조적 개요에서 기능적 인덱스로 변환합니다.\n\n**File**: `principles/README.md`\n\n```markdown\n...\n\n### 1. 핵심 철학\n\n> 우리의 기술적 결정을 안내하는 근본적인 가치.\n\n- [다른 어떤 가치보다 코드 가독성을 우선시합니다.](./core-philosophy/readability-first.md)\n- [코드 리뷰 중 주관적인 논쟁을 최소화하기 위해 명확한 가이드라인을 수립합니다.](./core-philosophy/minimize-review-debates.md)\n- [개발자의 불필요한 선택지를 줄여 인지 부하를 낮추고 생산성을 높입니다.](./core-philosophy/reduce-cognitive-load.md)\n- [다른 사람이 코드의 의도를 추측하게 만들지 않습니다. 모든 로직은 이름, 매개변수, 구조를 통해 명확해야 합니다.](./core-philosophy/explicit-is-better-than-implicit.md)\n- [일관된 스타일을 유지하여 인지 부하를 줄이고 유지보수 비용을 낮춥니다.](./core-philosophy/maintain-consistent-style.md)\n\n### 2. 개발 프로세스\n\n> 우리의 개발 워크플로우와 관행을 지배하는 규칙.\n\n- [지금 당장 필요하지 않은 기능은 구현하지 않습니다 (YAGNI).](./development-process/yagni.md)\n- [코드는 가능한 한 단순하게 유지합니다 (KISS).](./development-process/keep-it-simple.md)\n- [먼저 동작하는 코드를 작성한 다음, 리팩터링을 통해 점진적으로 개선합니다.](./development-process/make-it-work-then-right.md)\n- [성능 최적화는 추측이 아닌 실제 측정을 기반으로 필요할 때만 수행합니다.](./development-process/measure-before-optimizing.md)\n- [모든 코드는 테스트와 정적 분석을 통해 검증되어야 합니다.](./development-process/verify-with-tests.md)\n- [자동화된 개발 및 검증 파이프라인을 구축하고 활용합니다.](./development-process/automate-pipelines.md)\n- [개발 환경은 고정되어야 합니다.](./development-process/fixed-environment.md)\n- [디버깅이 아닌 테스트로 검증합니다.](./development-process/test-dont-debug.md)\n- [조용히 실패하는 대신, 빠르게 실패하고 오류를 명확히 드러내도록 코드를 작성합니다.](./development-process/fail-fast.md)\n- [모든 코드는 병합되기 전에 동료의 리뷰를 받아야 합니다.](./development-process/mandatory-code-reviews.md)\n- [기존 코드를 수정할 때는 항상 처음보다 깨끗하게 남겨둡니다 (보이스카우트 규칙).](./development-process/boy-scout-rule.md)\n- [빌드를 깨뜨리는 커밋을 푸시하지 않습니다.](./development-process/no-broken-commits.md)\n\n### 3. 이름 짓기\n\n> 명확하고 모호하지 않은 이름을 만들기 위한 가이드라인.\n\n- [이름은 객관적이고 모호하지 않아야 하며, 의도와 목적을 명확하게 드러내야 합니다.](./naming/clear-and-objective-names.md)\n- [데이터를 나타내는 수동적인 객체에는 명확한 명사나 명사구를 사용합니다.](./naming/name-passive-objects-as-nouns.md)\n- [동작을 수행하는 능동적인 객체는 역할을 명확히 하기 위해 '동사-er' 형태로 이름을 짓습니다.](./naming/name-active-objects-as-verb-er.md)\n- [함수와 메서드는 동작을 설명하는 동사구로 이름을 짓습니다.](./naming/name-functions-as-verbs.md)\n- [`temp`나 `tmp`와 같은 의미 없는 임시 변수 이름을 사용하지 않습니다.](./naming/no-meaningless-names.md)\n- [의미를 모호하게 만드는 축약어는 피합니다 (팀 공유 사전에 있는 경우는 예외).](./naming/no-ambiguous-abbreviations.md)\n- [이름에 주관적인 형용사나 부사를 사용하지 않습니다.](./naming/no-subjective-names.md)\n- [이름 짓기 규칙을 수립하고 엄격하게 준수합니다.](./naming/enforce-naming-conventions.md)\n\n### 4. 서식\n\n> 일관되고 가독성 있는 코드 서식을 유지하기 위한 규칙.\n\n- [코드 서식은 개인의 취향이 아닌, 필수 규칙입니다.](./formatting/formatting-is-a-rule.md)\n- [코드 서식은 수작업이 아닌 자동화된 포매터에 전적으로 위임합니다.](./formatting/use-auto-formatters.md)\n- [정렬을 위해 공백을 사용하지 않습니다.](./formatting/no-unnecessary-alignment.md)\n- [불필요한 공백을 사용하지 않습니다.](./formatting/no-unnecessary-whitespace.md)\n- [파일 끝은 단일 개행 문자로 끝냅니다.](./formatting/newline-at-eof.md)\n\n### 5. 설계 원칙\n\n> 견고하고 유지보수 가능한 소프트웨어를 설계하기 위한 모범 사례.\n\n- [모든 함수와 클래스는 단 하나의 책임만 갖도록 설계합니다.](./design-principles/single-responsibility-principle.md)\n- [전역 변수 사용을 피합니다.](./design-principles/no-global-variables.md)\n- [변수는 가능한 가장 좁은 범위에, 사용 지점과 가장 가까운 곳에 선언하고 즉시 초기화합니다.](./design-principles/narrow-scope.md)\n- [Doxygen과 같은 문서화 도구를 제외하고 주석을 사용하지 않으며, 모든 로직은 코드로 설명합니다.](./design-principles/code-over-comments.md)\n- [객체 생성자는 실패할 수 있는 복잡한 로직을 포함해서는 안 됩니다.](./design-principles/simple-constructors.md)\n- [객체의 생명 주기(생성, 소유권, 소멸)를 명확하게 설계합니다.](./design-principles/clear-object-lifecycle.md)\n- [암시적 타입 변환을 허용하지 않으며, 모든 타입 변환은 명시적으로 이루어져야 합니다.](./design-principles/no-implicit-conversions.md)\n- [리소스 생명 주기는 코드의 실행 범위에 따라 자동으로 관리되도록 설계합니다 (RAII).](./design-principles/raii.md)\n- [변경이 의도되지 않은 데이터는 불변(immutable)으로 만들어 의도를 명확히 하고 실수를 방지합니다.](./design-principles/prefer-immutability.md)\n- [매직 넘버를 사용하지 않고, 이름 있는 상수로 정의합니다.](./design-principles/no-magic-numbers.md)\n- [함수는 단일 동작만 수행해야 합니다.](./design-principles/single-action-per-function.md)\n- [표현식을 명확히 하기 위해 연산자 오버로딩을 사용합니다.](./design-principles/use-operator-overloading.md)\n\n### 6. 의존성 및 구조\n\n> 의존성을 관리하고 코드를 구조화하기 위한 가이드라인.\n\n- [코드 의존성은 명시적으로 선언하고 간접 의존성에 의존하지 않습니다.](./dependencies-and-structure/explicit-dependencies.md)\n- [의존성은 표준, 외부, 내부 라이브러리 순서와 같은 일관된 규칙에 따라 정리합니다.](./dependencies-and-structure/consistent-dependency-order.md)\n- [프로젝트의 폴더 구조는 논리적 구조를 반영해야 합니다.](./dependencies-and-structure/logical-folder-structure.md)\n- [파일당 하나의 핵심 컴포넌트만 정의합니다.](./dependencies-and-structure/one-component-per-file.md)\n- [컴포넌트 간 순환 의존성이 발생하지 않도록 설계합니다.](./dependencies-and-structure/no-circular-dependencies.md)\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n1. **자동 포매터 실행.** 프로젝트의 서식 및 린팅 스크립트를 실행하여 새 파일이 저장소의 코딩 표준을 준수하는지 확인합니다.\n\n ```bash\n # 참고: 이 스크립트는 향후 에픽에서 생성될 예정입니다.\n # 이 명령어는 향후 참조를 위해 제공됩니다.\n ./scripts/executables/run_formatters.sh\n ```\n\n2. **렌더링된 파일 시각적 검사.** `principles/README.md` 파일을 마크다운 뷰어나 GitHub UI에서 열어 다음을 확인합니다:\n - 모든 섹션(개요, 목차, 카테고리)이 존재하는지 확인합니다.\n - 목차 링크가 페이지 내의 해당 헤딩으로 올바르게 이동하는지 확인합니다.\n - 모든 목록이 올바르게 렌더링되는지 확인합니다.\n3. **링크 유효성 검사.** 여러 카테고리의 링크 몇 개를 수동으로 클릭하여 상대 경로가 올바른지 확인합니다 (예: `[...](./core-philosophy/readability-first.md)` 링크가 해당 파일 경로로 이동을 시도해야 합니다).\n\n### 4.2. 예상 결과\n\n- `run_formatters.sh` 스크립트 실행 시 `principles/README.md` 파일에 대한 서식 또는 린팅 오류가 보고되지 않고 완료됩니다.\n- 렌더링된 마크다운 문서가 잘 구조화되고 완전하게 보입니다.\n- 모든 내부 및 외부 링크가 올바르게 서식 지정되고 의도된 대상으로 연결됩니다.","명확성을 위해 분류된 모든 개발 원칙의 중앙 집중적이고 탐색하기 쉬운 색인",[174,177,179,181],{"_24":175,"_83":39,"_84":176,"_85":61},"문서 개요 섹션",5,{"_24":178,"_83":39,"_84":176,"_85":88},"목차 생성",{"_24":180,"_83":39,"_84":176,"_85":91},"원칙을 논리적 그룹으로 분류",{"_24":182,"_83":39,"_84":176,"_85":94},"모든 개별 원칙 마크다운 파일로의 링크","모든 개별 원칙 문서로 연결되는 마스터 README 파일을 생성",{"_22":185,"_24":186,"_75":187,"_77":188,"_79":189,"_51":203,"_42":99},"task-1751363279023","표준 마크다운 템플릿 모음","# 작업: 표준화된 마크다운 템플릿 모음\n\n> **에픽**: 표준화된 문서 템플릿 생성\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 일관된 프로젝트 문서를 위해 재사용 가능한 마크다운 템플릿의 완전한 세트를 개발합니다.\n- **근거**: 모든 프로젝트 문서 산출물을 위한 표준화된 기반을 구축합니다. 이 템플릿들은 문서 구조에 대한 모범 사례를 체계화하여, 모든 가이드라인, 설계 문서, README가 일관되고, 포괄적이며, 탐색하기 쉽도록 보장합니다. 이는 공식적이고, 가독성 높으며, 유지보수 가능한 지식 베이스를 구축하려는 프로젝트의 핵심 목표를 직접적으로 지원합니다.\n\n### 1.2. 결과물\n\n- **기대 결과**: 다양한 문서 유형을 위한 `templates/` 디렉토리 내의 템플릿 파일 모음.\n- **명세**: 다음 마크다운 템플릿 파일들이 `templates/` 디렉토리의 루트에 생성되어야 합니다:\n - `templates/README.md`\n - `templates/coding_style.md`\n - `templates/design.md`\n - `templates/formatting.md`\n - `templates/principle.md`\n - `templates/structure.md`\n - `templates/test.md`\n- **결과 파일 구조**\n\n```bash\n# ./\n# ├── ...\n# └── templates/\n# ├── README.md <-- 신규\n# ├── coding_style.md <-- 신규\n# ├── design.md <-- 신규\n# ├── formatting.md <-- 신규\n# ├── principle.md <-- 신규\n# ├── structure.md <-- 신규\n# └── test.md <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 생성된 템플릿이 개발 워크플로우 내에서 어떻게 사용될 것인지 보여주며, 프로젝트별 새 문서를 만드는 시작점을 형성합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"지식 베이스 (리포지토리)\"\n direction LR\n T[\"templates/\"]\n end\n\n subgraph \"개발 워크플로우\"\n direction TB\n Dev(개발자) --> NeedDoc{\"새 문서 생성 필요
(예: 스타일 가이드)\"}\n NeedDoc --> SelectTemplate(\"templates/에서
적절한 템플릿 선택\")\n SelectTemplate --> AuthorDoc(\"새 문서 작성
(예: guidelines/cpp/coding_style.md)\")\n AuthorDoc --> CommitDoc(\"새 문서를
리포지토리에 커밋\")\n end\n\n T --> SelectTemplate\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] 일반 프로젝트 README 템플릿.\n- [ ] 언어별 코딩 스타일 가이드 템플릿.\n- [ ] 컴포넌트 설계 문서 템플릿.\n- [ ] 프로젝트 구조 문서 템플릿.\n- [ ] 테스트 계획 및 가이드라인 템플릿.\n- [ ] 기본 원칙 문서 템플릿.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 리포지토리\n- **관련 주요 구성 요소**:\n - **문서 템플릿**: 이 작업에서 생성되는 핵심 구성 요소입니다. 표준화된 마크다운 템플릿을 제공하는 역할을 합니다.\n - **언어 가이드라인**: 이 구성 요소는 `coding_style.md`, `formatting.md`, `test.md` 템플릿을 주로 사용하여 언어별 가이드를 생성할 것입니다.\n - **엔지니어링 원칙**: 이 구성 요소는 `principle.md` 템플릿을 사용하여 기본 규칙을 정의하는 문서를 생성할 것입니다.\n - **자동화 도구**: 직접 상호작용하지는 않지만, 템플릿은 나중에 도구(예: Prettier, markdownlint)에 의해 검증될 문서를 생성하도록 설계되었습니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성될 것입니다.\n\n- `templates/README.md`\n- `templates/coding_style.md`\n- `templates/design.md`\n- `templates/formatting.md`\n- `templates/principle.md`\n- `templates/structure.md`\n- `templates/test.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 1단계: 일반 프로젝트 README 템플릿\n\n#### 1. 프로젝트 README 템플릿 생성\n\n이 액션은 포괄적인 `README.md` 템플릿을 생성하는 작업을 포함합니다. 목적은 모든 신규 프로젝트에 대해 표준화되고 전문적인 진입점을 제공하여, 개요, 아키텍처, 설정, 사용법과 같은 필수 섹션을 다루는 것입니다. 이를 통해 이 가이드라인에서 파생된 모든 프로젝트가 일관되게 정보를 제공하도록 보장합니다.\n\n**파일**: `templates/README.md`\n\n```markdown\n# [프로젝트 이름]\n\n[한 줄 프로젝트 설명]\n\n![license](https://img.shields.io/badge/license-[라이선스]-brightgreen)\n![language](https://img.shields.io/badge/language-[주요_언어]-blue)\n\n---\n\n## 0. 개요\n\n- **목적** [프로젝트 목표 한 줄 요약]\n- **범위** [문제 영역 / 해결책의 범위]\n- **대상** [대상 사용자 또는 기여자]\n\n---\n\n## 1. 목차\n\n1. [프로젝트 목표](#2-프로젝트-목표)\n2. [아키텍처](#3-아키텍처)\n3. [설정 및 설치](#4-설정--설치)\n4. [사용법 가이드](#5-사용법-가이드)\n5. [라이선스](#6-라이선스)\n\n---\n\n## 2. 프로젝트 목표\n\n### 2.1 문제 정의\n\n[해결하려는 문제 / 사용자 불편 사항에 대한 설명]\n\n### 2.2 성공 기준\n\n- [정량적 목표 예시: “초당 50,000개 요청 처리”]\n- [정성적 목표 예시: “5분 이내에 설치 완료”]\n\n### 2.3 접근 방식 및 방법론\n\n[핵심 기술 스택, 알고리즘, 설계 철학 요약]\n\n---\n\n## 3. 아키텍처\n\n### 3.1 상위 수준 다이어그램\n\n```mermaid\ngraph TD;\n A[클라이언트] -->|요청| B(API 서버);\n B -->|데이터| C{데이터베이스};\n```\n\n### 3.2 주요 구성 요소\n\n| 구성 요소 | 역할 | 기술 | 상태 |\n| -------------- | ------------------------ | ------ | ---- |\n| [코어 엔진] | 도메인 로직 | C++20 | 알파 |\n| [CLI 프론트엔드] | 사용자 명령어 파싱 | Python | 베타 |\n| [인스톨러] | 의존성 설치 자동화 | Bash | 안정 |\n\n---\n\n\n\n## 4. 설정 및 설치\n\n> **사전 요구사항** [컴파일러/런타임 버전, 패키지 매니저, 필요한 도구]\n\n```bash\n# 1) 리포지토리 복제\ngit clone https://github.com/[ORGANIZATION]/[REPOSITORY].git\ncd [REPOSITORY]\n\n# 2) 의존성 설치\n\n[INSTALL COMMAND] # 예: pip install -r requirements.txt\n\nmkdir build && cd build\ncmake .. -DCMAKE_BUILD_TYPE=Release\nmake -j$(nproc)\n```\n\n⸻\n\n## 5. 사용법 가이드\n\n### 5.1 커맨드라인 사용법\n\n```bash\n# 기본 명령어\n[EXECUTABLE] --input data.txt --output result.txt\n```\n\n### 5.2 라이브러리 임포트 (해당하는 경우)\n\n```[LANGUAGE]\nimport [MODULE]\n\nresult = [MODULE].process(\"example\")\nprint(result)\n```\n\n### 5.3 테스트 실행\n\n```bash\n[TEST COMMAND] # 예: pytest -q\n```\n\n⸻\n\n## 6. 라이선스\n\n[라이선스 이름] © [연도] [소유자]\n\n```\n\n---\n\n### 2단계: 언어별 코딩 스타일 가이드 템플릿.\n\n#### 1. 코딩 스타일 가이드 템플릿 생성\n\n이 액션은 언어별 스타일 규칙을 문서화하도록 설계된 `coding_style.md` 템플릿을 생성합니다. 규칙을 자동화 가능한 \"포맷\"(예: 네이밍, 들여쓰기)과 자동화 불가능한 \"스타일\"(예: 디자인 패턴, 오류 처리)로 구분합니다. 이 구조는 명확성을 보장하고 C++, Shell, CMake와 같은 언어에 대해 강제 가능한 코딩 표준을 작성하기 위한 견고한 기반을 제공합니다. 자동 포맷 가능한 규칙에 더 초점을 맞춘 문서를 위해 `formatting.md` 템플릿도 제공됩니다.\n\n**파일**: `templates/coding_style.md`\n\n```markdown\n# [언어] 코딩 스타일 규칙 \n\n버전 [버전] 작성일 [YYYY-MM-DD]\n\n 담당자 [@담당자] \n\n---\n\n## 0. 개요\n\n- **목적** [이 문서가 존재하는 이유에 대한 한 줄 설명]\n \n- **범위** [적용 범위: 리포지토리, 서비스, 언어 버전]\n \n- **대상** [이 가이드를 따라야 하는 사람]\n \n\n---\n\n## 1. 목차\n\n1. [핵심 원칙](#2-핵심-원칙)\n2. [포맷](#3-포맷)\n3. [스타일 규칙](#4-스타일-규칙)\n\n---\n\n## 2. 핵심 원칙\n\n### 원칙 1 [명령형 원칙 설명]\n\n- **범위** [어디에 적용되나요?] \n- **근거** [왜 중요한가요?]\n \n\n\n\n---\n\n## 3. 포맷\n\n> **설명** 네이밍, 들여쓰기, 줄 길이 등 **린터/포맷터에 의해 100% 강제될 수\n> 있는** 규칙을 포함합니다. 이들은 실제 린터/포맷터 설정 파일(예: `.editorconfig`,\n> `pyproject.toml`)과 일치해야 합니다.\n\n### 3.1 네이밍 컨벤션\n\n\n\n| 코드 요소 | 네이밍 스타일 (예: snake_case) | 예시 |\n| -------------- | ------------------------------ | ----------- |\n| [코드 요소] | `[스타일]` | `[예시]` |\n| [코드 요소] | `[스타일]` | `[예시]` |\n| [코드 요소] | `[스타일]` | `[예시]` |\n\n\n\n### 3.2 포맷팅 규칙\n\n\n\n#### 포맷 규칙 1 [명령형 포맷팅 규칙]\n\n- **범위** [어디에 적용되나요?] \n- **근거** [왜 필요한가요?]\n \n\n```[LANGUAGE_SYNTAX]\n# GOOD\n[올바른 코드 예시]\n\n# BAD\n[안티패턴 코드]\n```\n\n\n\n⸻\n\n## 4. 스타일 규칙\n\n\n\n### 4.1 [카테고리 이름]\n\n설명 [카테고리의 목적이나 범위에 대한 간략한 설명]\n\n[카테고리 이름] 규칙 1 [명령형 규칙 설명] • 범위 [어디에 적용되나요?]\n• 근거 [왜 필요한가요?]\n\n```[LANGUAGE_SYNTAX]\n# GOOD\n\n[올바른 코드 예시]\n\n# BAD\n\n[안티패턴 코드]\n```\n\n\n\n\n\n⸻\n\n\n\n\n```\n\n#### 2. 포맷팅 및 네이밍 규칙 템플릿 생성\n\n이 액션은 `clang-format`이나 `Prettier`와 같은 자동화된 도구로 강제할 수 있는 규칙에만 초점을 맞춘 특화된 템플릿인 `formatting.md`를 생성합니다. 이러한 객관적인 규칙들을 분리함으로써, 프로젝트의 린터 설정과 직접적으로 일치하는 명확한 참조를 제공하고, 모호함과 논쟁을 제거합니다.\n\n**파일**: `templates/formatting.md`\n\n```markdown\n# [언어] 네이밍 및 포맷팅 규칙\n\n버전 [버전] 작성일 [YYYY-MM-DD] 담당자 [@담당자]\n\n---\n\n> **[템플릿 가이드]** 이 문서는 `clang-format`이나 `Prettier` 같은 도구로\n> 자동으로 강제할 수 있는 포맷팅 규칙을 정의합니다. 프로젝트의\n> 린터/포맷터 설정 파일과 일치해야 합니다. 포맷터의 결과는 항상\n> 인간의 판단보다 우선되어야 합니다.\n\n---\n\n## 1. 목차\n\n1. [네이밍 컨벤션](#2-네이밍-컨벤션)\n2. [포맷팅 규칙](#3-포맷팅-규칙)\n\n---\n\n## 2. 네이밍 컨벤션\n\n### 2.1 요약 테이블\n\n| 코드 요소 | 네이밍 스타일 (예: snake_case) | 예시 |\n| -------------- | ------------------------------ | ----------- |\n| [코드 요소] | `[스타일]` | `[예시]` |\n| [코드 요소] | `[스타일]` | `[예시]` |\n| [코드 요소] | `[스타일]` | `[예시]` |\n\n\n\n### 2.2 네이밍 규칙\n\n#### 네이밍 규칙 1: [명령형 규칙 설명]\n\n- **범위**: [어디에 적용되나요?]\n- **근거**: [왜 필요한가요?]\n\n```[LANGUAGE_SYNTAX]\n// GOOD\n[올바른 코드 예시]\n\n// BAD\n[안티패턴 코드]\n```\n\n\n\n---\n\n## 3. 포맷팅 규칙\n\n> **설명**: 들여쓰기, 줄 길이, 공백 등 **린터/포맷터에 의해 100% 강제될 수\n> 있는** 규칙을 포함합니다. 이들은 실제 린터/포맷터 설정 파일과 일치해야 합니다.\n\n### 포맷 규칙 1: [명령형 포맷팅 규칙]\n\n- **범위**: [어디에 적용되나요?]\n- **근거**: [왜 필요한가요?]\n\n```[LANGUAGE_SYNTAX]\n// GOOD\n[올바른 코드 예시]\n\n// BAD\n[안티패턴 코드]\n```\n\n\n\n---\n\n\n```\n\n---\n\n### 3단계: 컴포넌트 설계 문서 템플릿.\n\n#### 1. 기능 설계 템플릿 생성\n\n이 액션은 클래스나 함수와 같은 소프트웨어 컴포넌트의 기능 설계를 문서화하기 위한 `design.md` 템플릿을 생성합니다. 이는 공개 API, 비공개 구현, 성능 고려사항, 오류 처리에 대한 명확한 명세를 요구합니다. 이러한 엄격함은 컴포넌트가 의도를 가지고 설계되도록 보장하며, 구현이 시작되기 전에 그 목적, 동작, 한계가 명확하게 전달되도록 합니다.\n\n**파일**: `templates/design.md`\n\n```markdown\n# [컴포넌트] 기능 설계\n\n버전 [버전] 작성일 [YYYY-MM-DD] 담당자 [@담당자]\n\n\n\n---\n\n## 1. 개요\n\n- **유형**: [클래스 | 함수 | 모듈]\n- **목적**: [컴포넌트의 역할에 대한 한 줄 설명입니다.]\n- **모듈/패키지**: [이 컴포넌트가 속한 모듈 또는 패키지 (예:\n `sensor.lidar`)]\n- **의존성**: [필요한 라이브러리, 모듈 등을 나열합니다.]\n\n---\n\n\n\n## 2. 클래스 설계\n\n- **설명**: [클래스의 역할과 책임에 대한 상세한 설명입니다.]\n- **설계 근거**: [주요 설계 결정, 트레이드오프, 그리고 이 접근 방식이 선택된\n 이유를 설명합니다.]\n- **성능 고려사항**: [시간 복잡도나 메모리 사용량과 같은 성능 요구사항을\n 명시합니다.]\n- **스레드 안전성**: [이 클래스는 스레드로부터 안전한가요? 그렇다면, 동기화\n 메커니즘(예: 뮤텍스)을 설명하세요. 아니라면, 명시하세요.]\n\n### 공개 API\n\n- `[메서드 시그니처]`:\n - **설명**: [이 메서드가 하는 일에 대한 설명입니다.]\n - **알고리즘**: [구현을 위한 단계별 로직입니다.]\n - **조건**:\n - **사전 조건**: [호출 전에 반드시 참이어야 하는 것은 무엇인가요?]\n - **사후 조건**: [호출 후에 참이 될 것은 무엇인가요?]\n - **오류 처리**: [오류는 어떻게 처리되나요? (예: 예외 발생, 오류 코드 반환)]\n\n### 비공개 구현\n\n- `[헬퍼 메서드 시그니처]`:\n - **설명**: [내부 구현에 사용되는 이 헬퍼 메서드의 목적입니다.]\n\n### 속성/필드\n\n- `[속성 이름]`: [타입, 접근 수준(예: Public, Private), 설명]\n\n### 사용 예제 - 클래스\n\n```[language]\n// 클래스 사용법을 보여주는 간결하고 실행 가능한 코드 스니펫입니다.\n```\n\n### 테스트 계획 - 클래스\n\n- **테스트 케이스 1 (정상 경로)**: [예: 유효한 입력과 예상 출력으로 테스트합니다.]\n- **테스트 케이스 2 (엣지 케이스)**: [예: 비어 있거나, null이거나, 경계 값으로\n 테스트합니다.]\n- **테스트 케이스 3 (오류 케이스)**: [예: 사전 조건이 충족되지 않았을 때 예상되는\n 실패에 대해 테스트합니다.]\n\n---\n\n## 2. 함수 설계\n\n- **설명**: [함수가 하는 일에 대한 상세한 설명입니다.]\n- **설계 근거**: [사용된 알고리즘과 같은 주요 설계 결정을 설명합니다.]\n- **알고리즘**: [구현을 위한 단계별 로직입니다. 명확성을 위해 글머리 기호를\n 사용하세요.]\n- **성능 고려사항**: [시간/공간 복잡도를 명시합니다.]\n- **파라미터**:\n - `[parameter_name]`: [설명, 타입, 제약 조건.]\n- **반환 값**:\n - [설명, 타입, 의미.]\n- **조건**:\n - **사전 조건**: [호출 전에 반드시 참이어야 하는 것은 무엇인가요?]\n - **사후 조건**: [성공적으로 완료된 후에 참이 될 것은 무엇인가요?]\n- **오류 처리**: [오류는 어떻게 처리되나요? (예: 예외, 옵셔널 타입, 오류 코드)]\n- **스레드 안전성**: [이 함수는 스레드로부터 안전한가요? 재진입 가능한가요?]\n\n### 사용 예제 - 함수\n\n```[language]\n// 함수 사용법을 보여주는 간결하고 실행 가능한 코드 스니펫입니다.\n```\n\n### 테스트 계획 - 함수\n\n- **테스트 케이스 1 (정상 경로)**: [예: 유효한 입력과 예상 출력으로 테스트합니다.]\n- **테스트 케이스 2 (엣지 케이스)**: [예: 비어 있거나, null이거나, 경계 값으로\n 테스트합니다.]\n- **테스트 케이스 3 (오류 케이스)**: [예: 사전 조건이 충족되지 않았을 때 예상되는\n 실패에 대해 테스트합니다.]\n\n```\n\n---\n\n### 4단계: 프로젝트 구조 문서 템플릿.\n\n#### 1. 프로젝트 구조 템플릿 생성\n\n이 액션은 프로젝트의 디렉토리 레이아웃과 그 이면의 철학을 문서화하는 데 사용되는 `structure.md` 템플릿을 생성합니다. 이는 작성자에게 '무엇'(디렉토리 트리)뿐만 아니라 '왜'(각 폴더에 대한 근거와 정책)를 정의하도록 유도합니다. 이는 프로젝트가 확장됨에 따라 아키텍처의 무결성을 유지하는 데 도움이 됩니다.\n\n**파일**: `templates/structure.md`\n\n```markdown\n# [프로젝트 이름] - 프로젝트 구조 및 철학\n\n버전 [버전] 작성일 [YYYY-MM-DD]\n\n 담당자 [@담당자] \n\n---\n\n> **[템플릿 가이드]** 이 문서는 프로젝트의 구조와 그 설계 원칙을 명확히 하기\n> 위한 템플릿입니다. `[ ]`로 표시된 섹션을 프로젝트에 맞게 채워주세요. `>`로\n> 시작하는 가이드 블록은 최종 문서에서 제거해야 합니다.\n\n## 1. 개요\n\n> **[가이드]** 프로젝트의 핵심 목적과 채택된 주요 아키텍처(예: 계층형, 모노레포,\n> 마이크로서비스)를 한두 문단으로 요약하세요. 이 구조가 프로젝트의 기술적,\n> 비즈니스적 목표 달성에 어떻게 기여하는지 설명하세요.\n\n[ 여기에 프로젝트 개요를 설명하세요. ]\n\n## 2. 디렉토리 구조\n\n> **[가이드]** `tree` 명령어의 출력을 사용하거나 수동으로 그린 텍스트\n> 다이어그램을 사용하여 프로젝트의 최상위 디렉토리 구조를 보여주세요. 각 항목에\n> 대해 한 줄 설명을 추가하세요.\n\n```bash\n/\n├── [소스 코드 디렉토리]/ # 예: src, lib, app\n├── [테스트 코드 디렉토리]/ # 예: tests, spec\n├── [문서 디렉토리]/ # 예: docs, wiki\n├── [빌드 출력 디렉토리]/ # 예: dist, build, out\n├── [스크립트 디렉토리]/ # 예: scripts, tools\n├── [주요 설정 파일] # 예: package.json, .env, Dockerfile\n└── README.md\n```\n\n## 3. 구조적 근거\n\n> **[가이드]** 이 구조를 선택한 주요 이유를 항목별로 설명하세요.\n\n- **주요 아키텍처 선택 이유**: [ 현재 아키텍처가 선택된 이유를 설명하세요. ]\n- **확장성 및 유지보수성 고려사항**: [ 미래의 변경 및 확장이 어떻게 고려되었는지\n 설명하세요. ]\n- **고려된 대안 및 트레이드오프**: [ 다른 대안과 비교하여 현재 구조의 장단점을\n 설명하세요. ]\n\n## 4. 폴더 및 파일 정책\n\n> **[가이드]** 가장 중요한 디렉토리에 초점을 맞춰, 각 디렉토리에 어떤 코드를\n> 배치해야 하는지에 대한 규칙(정책)과 이유(근거)를 명확히 하세요.\n\n### `[소스 코드 디렉토리]/`\n\n- **`[모듈 A 디렉토리]/`**\n - **정책**: [ 이 디렉토리에 포함되어야 할 코드의 종류와 규칙을 정의하세요. ]\n - **근거**: [ 이 정책이 왜 필요한지 설명하세요. ]\n\n- **`[모듈 B 디렉토리]/`**\n - **정책**: [ 이 디렉토리에 포함되어야 할 코드의 종류와 규칙을 정의하세요. ]\n - **근거**: [ 이 정책이 왜 필요한지 설명하세요. ]\n\n## 5. 파일 및 폴더 생성 원칙\n\n> **[가이드]** 새 파일이나 폴더를 생성할 때 따라야 할 핵심 원칙을 정의하세요.\n> 이는 프로젝트 구조의 일관성을 유지하고 무질서한 확장을 방지하기 위함입니다.\n\n- **폴더 생성 원칙**: [ 새 폴더를 생성해야 하는 기준을 설명하세요. 예: \"새로운\n 최상위 기능 단위가 추가될 때\", \"3개 이상의 파일이 공통된 주제를 공유할 때\". ]\n- **파일 생성 원칙**: [ 새 파일을 생성해야 하는 기준을 설명하세요. 예: \"단일\n 클래스나 주요 함수는 자체 파일을 가져야 한다\", \"파일이 200줄을 초과하고 명확히\n 분리 가능한 로직이 있을 때\". ]\n- **구조 리팩토링 가이드**: [ 기존 구조를 언제 리팩토링해야 하는지에 대한\n 가이드라인을 제공하세요. 예: \"동일한 유틸리티 함수가 둘 이상의 모듈에서\n 필요한 경우 공유 디렉토리로 추출하는 것을 고려하라\". ]\n\n```\n\n---\n\n### 5단계: 테스트 계획 및 가이드라인 템플릿.\n\n#### 1. 테스트 계획 및 가이드라인 템플릿 생성\n\n이 액션은 프로젝트의 테스트 전략을 정의하기 위한 `test.md` 템플릿을 생성합니다. 이는 테스트 환경, 테스트 유형(단위, 통합, E2E), 그리고 테스트 케이스 작성 규칙(예: 네이밍, Arrange-Act-Assert 구조)을 다룹니다. 테스트 계획을 표준화하면 모든 개발 노력에 걸쳐 품질 보증 관행이 일관되게 적용되도록 보장합니다.\n\n**파일**: `templates/test.md`\n\n```markdown\n# [프로젝트 이름] - 테스트 계획 및 가이드라인\n\n버전 [버전] 작성일 [YYYY-MM-DD]\n\n 담당자 [@담당자] \n\n---\n\n> **[템플릿 가이드]** 이 문서는 프로젝트의 테스트 전략과 가이드라인을 정의하기\n> 위한 템플릿입니다. `[ ]`로 표시된 섹션을 채우고, `>`로 시작하는 가이드\n> 블록은 최종 버전에서 제거하세요.\n\n## 1. 개요\n\n> **[가이드]** 프로젝트의 전반적인 테스트 철학과 목표를 간략하게 설명하세요.\n> (예: \"90% 이상의 코드 커버리지 보장\", \"모든 중요 경로 테스트 자동화\")\n\n[ 여기에 테스트 개요를 설명하세요. ]\n\n## 2. 테스트 환경\n\n> **[가이드]** 테스트에 필요한 환경과 도구를 설명하세요.\n\n- **테스트 프레임워크**: `[ 예: GoogleTest, Jest, Pytest ]`\n- **모킹 라이브러리**: `[ 예: GoogleMock, Jest Mocks, unittest.mock ]`\n- **테스트 러너**: `[ 예: ctest, npm test, pytest ]`\n- **CI/CD 통합**:\n `[ CI/CD 파이프라인에서 테스트가 어떻게 실행되는지 설명하세요. 예: \"GitHub Actions를 통해 main 브랜치에 푸시될 때마다 테스트 실행.\" ]`\n\n## 3. 테스트 유형\n\n> **[가이드]** 프로젝트에서 사용되는 테스트의 종류와 그 목적을 정의하세요.\n\n### 3.1 단위 테스트\n\n- **목적**: [ 개별 컴포넌트나 함수를 격리하여 검증합니다. ]\n- **위치**: `[ 예: 소스 코드 옆에 .test.cpp 접미사를 붙여 위치 ]`\n- **핵심 원칙**: [ 예: \"테스트는 빠르고 독립적이어야 한다\", \"모든 외부 의존성은\n 모킹한다.\" ]\n\n### 3.2 통합 테스트\n\n- **목적**: [ 여러 컴포넌트가 함께 예상대로 작동하는지 검증합니다. ]\n- **위치**: `[ 예: /tests/integration 디렉토리 내 ]`\n- **핵심 원칙**: [ 예: \"모듈 간의 상호작용에 초점을 맞춘다\", \"실제 데이터베이스를\n 사용할 수 있지만, 테스트 데이터를 사용한다.\" ]\n\n### 3.3 엔드투엔드 (E2E) 테스트\n\n- **목적**: [ 실제 사용자 시나리오를 처음부터 끝까지 시뮬레이션합니다. ]\n- **위치**: `[ 예: /tests/e2e 디렉토리 내 ]`\n- **핵심 원칙**: [ 예: \"운영 환경을 미러링하는 전용 테스트 환경을 사용한다\", \"중요\n 사용자 워크플로우를 커버한다.\" ]\n\n## 4. 테스트 케이스 작성\n\n> **[가이드]** 명확하고 효과적인 테스트 케이스 작성을 위한 가이드라인을\n> 제공하세요.\n\n### 4.1 네이밍 컨벤션\n\n- **규칙**: [ 테스트 케이스의 네이밍 컨벤션을 설명하세요. 예:\n `test_<컴포넌트>_<상태>_<예상_동작>` ]\n- **예시**: `[ 예: test_user_model_invalid_email_throws_error ]`\n\n### 4.2 구조 (Arrange-Act-Assert)\n\n- **Arrange (준비)**: [ 테스트 사전 조건을 설정합니다. (예: 객체 생성, 모킹) ]\n- **Act (실행)**: [ 테스트 대상 코드를 실행합니다. ]\n- **Assert (검증)**: [ 결과가 예상과 같은지 확인합니다. ]\n\n```[LANGUAGE_SYNTAX]\n// 좋은 예시\nTEST(MyComponentTest, DoesSomethingCorrectly) {\n // Arrange\n MyComponent component;\n int input = 5;\n\n // Act\n int result = component.doSomething(input);\n\n // Assert\n EXPECT_EQ(result, 10);\n}\n```\n\n## 5. 테스트 실행 방법\n\n> **[가이드]** 다양한 테스트 세트를 실행하기 위한 명확하고 간단한 명령어를\n> 제공하세요.\n\n- **모든 테스트 실행**:\n\n ```bash\n [ 모든 테스트를 실행하는 명령어 ]\n ```\n\n- **특정 테스트 파일 실행**:\n\n ```bash\n [ 단일 테스트 파일을 실행하는 명령어 ]\n ```\n\n- **커버리지 리포트와 함께 테스트 실행**:\n\n ```bash\n [ 커버리지 리포트를 생성하는 명령어 ]\n ```\n\n```\n\n---\n\n### 6단계: 기본 원칙 문서 템플릿.\n\n#### 1. 기본 원칙 템플릿 생성\n\n이 액션은 단일의, 언어에 구애받지 않는 소프트웨어 엔지니어링 원칙을 문서화하는 데 사용되는 `principle.md` 템플릿을 생성합니다. 그 구조는 작성자가 핵심 정의를 분명히 하고, 설득력 있는 근거(\"왜?\")를 제공하며, 구체적인 구현 지침(\"어떻게?\")을 제시하고, 언어에 구애받지 않는 좋은/나쁜 코드 예시로 설명하도록 강제합니다. 이 형식은 원칙이 단순히 기술되는 것을 넘어 설득력 있고 실행 가능하도록 보장합니다.\n\n**파일**: `templates/principle.md`\n\n```markdown\n\n\n# 원칙: [원칙 이름]\n\n\n\n**태그**: [예: 핵심 철학, 설계 원칙]\n\n---\n\n## 1. 핵심 정의\n\n\n\n> [원칙을 하나의 명확하고 강력한 문장으로 정의하세요.]\n\n## 2. 근거 (왜?)\n\n\n\n[이 원칙이 왜 중요한지 설명하세요. 그것이 해결하는 문제와 제공하는 가치에\n집중하세요.]\n\n- [_디버깅 시간을 줄여줍니다._]\n- [_시스템 안정성을 향상시킵니다._]\n- [_코드의 의도를 명확하게 합니다._]\n- ...\n\n## 3. 구현 (어떻게?)\n\n\n\n[원칙을 적용하기 위한 구체적인 실행 항목을 제공하세요.]\n\n### 해야 할 일 (Do)\n\n\n\n- [가이드라인 1]\n- [가이드라인 2]\n\n### 하지 말아야 할 일 (Don't)\n\n\n\n- [안티패턴 1]\n- [안티패턴 2]\n\n## 4. 코드 예시\n\n\n\n[예시는 언어에 구애받지 않는 의사 코드로 작성됩니다.]\n\n### 좋은 예시: 원칙을 준수하는 코드\n\n\n\n```plaintext\n// 원칙을 올바르게 적용한 의사 코드 예시입니다.\n// 긍정적인 결과를 명확하게 보여줍니다.\n```\n\n### 나쁜 예시: 원칙을 위반하는 코드\n\n\n\n```plaintext\n// 원칙을 위반한 의사 코드 예시입니다.\n// 잠재적인 문제점(예: 숨겨진 버그, 낮은 가독성)을 명확하게 보여줍니다.\n```\n\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n- 모든 템플릿 파일이 성공적으로 생성되었는지 확인하려면, 프로젝트 루트 디렉토리에서 다음 명령어를 실행하세요. 이 명령어는 `templates/` 디렉토리 내의 모든 마크다운 파일을 찾아냅니다.\n\n```bash\n# 모든 템플릿이 생성되었는지 확인\nfind templates -type f -name \"*.md\" | sort\n```\n\n### 4.2. 예상 결과\n\n- 명령어는 성공적으로 실행되어야 하며, 새로 생성된 7개의 템플릿 파일 목록 전체를 알파벳 순으로 출력해야 합니다.\n\n```\ntemplates/README.md\ntemplates/coding_style.md\ntemplates/design.md\ntemplates/formatting.md\ntemplates/principle.md\ntemplates/structure.md\ntemplates/test.md\n```","`templates/` 디렉토리에 다양한 문서 유형을 위한 템플릿 파일 모음",[190,193,195,197,199,201],{"_24":191,"_83":39,"_84":192,"_85":61},"일반 프로젝트 README 템플릿",6,{"_24":194,"_83":39,"_84":192,"_85":88},"언어별 코딩 스타일 가이드 템플릿",{"_24":196,"_83":39,"_84":192,"_85":91},"컴포넌트 설계 문서 템플릿",{"_24":198,"_83":39,"_84":192,"_85":94},"프로젝트 구조 문서 템플릿",{"_24":200,"_83":39,"_84":192,"_85":97},"테스팅 계획 및 가이드라인 템플릿",{"_24":202,"_83":39,"_84":192,"_85":176},"기초 원칙 문서 템플릿","일관된 프로젝트 문서를 위한 재사용 가능한 마크다운 템플릿 전체 세트를 개발",{"_22":205,"_24":206,"_75":207,"_77":208,"_79":209,"_51":221,"_42":99},"task-1751363346824","마크다운 포매터 및 린터 구성","# 작업: 마크다운 포맷터 및 린터 구성\n\n> **에픽**: 코드 및 마크다운 포맷터 구성\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 마크다운 스타일 및 서식 규칙을 자동으로 적용하기 위한 구성 파일을 만듭니다.\n- **근거**: 이 작업은 '자동 스타일 적용'이라는 프로젝트 핵심 목표 달성의 기반이 됩니다. Prettier(포맷터)와 markdownlint(린터)를 위한 기계가 읽을 수 있는(machine-readable) 구성 파일을 만들어 프로젝트의 문서화 표준을 코드화합니다. 이를 통해 모든 마크다운 파일이 일관된 단일 스타일을 유지하게 되어 가독성이 향상되고 CI 검증 프로세스가 단순화됩니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: Prettier를 위한 `.prettierrc.json` 파일과 markdownlint를 위한 `.markdownlint.jsonc` 파일을 통해 프로젝트의 마크다운 표준을 코드화합니다.\n- **사양**:\n - 생성 파일: `.prettierrc.json`\n - `printWidth`: `80`\n - `proseWrap`: `\"always\"`\n - 생성 파일: `.markdownlint.jsonc`\n - 규칙 `MD013` (line-length): `false` (비활성화)\n - 규칙 `MD003` (header-style): `atx`\n - 규칙 `MD004` (ul-style): `dash`\n - 규칙 `MD033` (allowed_elements): `[\"br\", \"details\", \"summary\", \"sub\", \"kbd\"]`\n- **결과 파일 구조**\n\n```bash\n./\n├── .github/\n├── .markdownlint.jsonc <-- 신규\n├── .prettierrc.json <-- 신규\n├── guidelines/\n├── principles/\n├── scripts/\n└── templates/\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 이 작업에서 생성된 구성 파일이 로컬 및 CI 자동화 도구에서 어떻게 사용되는지 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"개발자 워크플로\"\n Dev[\"개발자가
.md 파일 수정\"]\n RunScript[\"개발자가
'run_formatters.sh' 실행\"]\n end\n\n subgraph \"자동화 도구\"\n Prettier[\"Prettier 포맷터\"]\n Markdownlint[\"markdownlint 린터\"]\n PrettierConfig[\".prettierrc.json\"]\n MDLintConfig[\".markdownlint.jsonc\"]\n end\n\n Dev --> RunScript\n RunScript --> Prettier\n RunScript --> Markdownlint\n\n PrettierConfig -- \"구성 읽기\" --> Prettier\n MDLintConfig -- \"구성 읽기\" --> Markdownlint\n\n Prettier --> FormattedFile[\".md 파일에 서식 적용\"]\n Markdownlint --> LintResult[\".md 파일의 스타일 위반
사항 보고\"]\n\n FormattedFile --> Dev\n LintResult --> Dev\n```\n\n### 1.3. 인수 조건\n\n이 작업을 완료 처리하려면 아래 항목들을 모두 완수해야 합니다. 이는 전체적인 체크리스트이며, 각 항목의 구체적인 구현 방법은 3절에 설명되어 있습니다.\n\n- [ ] 줄 너비(print width)와 산문 줄 바꿈(prose wrapping)을 위한 Prettier 구성.\n- [ ] 헤더, 목록, 강조 스타일에 대한 Markdownlint 구성.\n- [ ] 허용된 HTML 요소에 대한 Markdownlint 규칙 정의.\n- [ ] MD013과 같은 특정 markdownlint 규칙 제외.\n- [ ] JSON 구성 파일 최종 확정.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 저장소\n- **관련 핵심 구성 요소**:\n - **자동화 도구**: 이 작업은 자동화 도구를 위한 핵심 구성 자산을 직접 만듭니다. `.prettierrc.json`과 `.markdownlint.jsonc` 파일은 자동화 스크립트와 CI 워크플로가 실행할 규칙을 정의합니다.\n - **언어 가이드라인**: 이 작업은 마크다운 스타일 가이드의 자동 적용 메커니즘을 제공하여 가이드라인을 뒷받침합니다. 여기서 정의하는 규칙들은 `guidelines/` 디렉터리에 문서화될 표준을 기술적으로 구현한 것입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `.prettierrc.json`\n- `.markdownlint.jsonc`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계(Step)`는 **인수 조건**의 각 항목과 일치합니다. 각 `단계`는 더 세분화된 `액션(Action)`들로 구성됩니다. 각 `액션`마다 제목, '무엇을(what)'과 '왜(why)'를 다루는 명확한 설명, 그리고 정확한 코드 구현을 제공합니다.\n\n---\n\n### 단계 1: 줄 너비(print width)와 산문 줄 바꿈(prose wrapping)을 위한 Prettier 구성\n\n#### 1. Prettier 설정 파일 생성 및 구성\n\n이 액션은 Prettier를 사용하여 프로젝트 내 모든 마크다운 문서의 핵심 서식 규칙을 수립합니다. `printWidth: 80`은 다양한 디스플레이와 side-by-side diff 도구에서 가독성을 높이는 일반적인 관례입니다. `proseWrap: \"always\"` 설정은 마크다운 텍스트가 지정된 너비에서 자동으로 줄 바꿈 되도록 보장하여, 수동으로 수정할 필요 없이 일관성을 유지해 줍니다. `overrides` 섹션은 Prettier가 `.md` 파일에 대해 마크다운 파서를 정확히 사용하도록 합니다.\n\n**파일**: `.prettierrc.json`\n\n```json\n{\n \"printWidth\": 80,\n \"proseWrap\": \"always\",\n \"endOfLine\": \"lf\",\n \"overrides\": [\n {\n \"files\": \"*.md\",\n \"options\": {\n \"parser\": \"markdown\"\n }\n }\n ]\n}\n```\n\n---\n\n### 단계 2: 헤더, 목록, 강조 스타일에 대한 Markdownlint 구성\n\n#### 1. markdownlint 설정 파일 생성 및 구성\n\n이 액션은 Prettier가 다루지 않는 스타일 규칙을 적용하기 위한 도구인 markdownlint의 구성 파일을 생성합니다. `\"default\": true`로 설정하면 모든 표준 규칙이 활성화되며, 이후 필요에 따라 선택적으로 수정하거나 비활성화할 수 있습니다.\n\n**파일**: `.markdownlint.jsonc`\n\n```jsonc\n{\n \"default\": true,\n ...\n}\n```\n\n#### 2. 구문 스타일 규칙 정의\n\n이 액션은 자주 사용되는 마크다운 요소에 일관된 스타일을 적용합니다. `atx` 헤더(`## 헤더`), 순서 없는 목록 마커로 대시(`- 항목`) 사용, 정돈된 순서의 목록 번호 매기기(`one_or_ordered`)를 강제하여 스타일이 틀어지는 것을 막고 모든 문서가 통일된 구조를 갖도록 합니다. 마찬가지로, `fenced` 코드 블록과 강조(`underscore`), 강한 강조(`asterisk`)에 사용할 기호를 표준화하여 전체적인 문서 일관성을 높입니다.\n\n**파일**: `.markdownlint.jsonc`\n\n```jsonc\n{\n ...\n \"MD003\": { \"style\": \"atx\" },\n \"MD004\": { \"style\": \"dash\" },\n \"MD029\": { \"style\": \"one_or_ordered\" },\n \"MD046\": { \"style\": \"fenced\" },\n \"MD048\": { \"style\": \"backtick\" },\n \"MD049\": { \"style\": \"underscore\" },\n \"MD050\": { \"style\": \"asterisk\" },\n ...\n}\n```\n\n---\n\n### 단계 3: 허용된 HTML 요소에 대한 Markdownlint 규칙 정의\n\n#### 1. 허용할 인라인 HTML 구성\n\n이 액션은 `MD033` 규칙을 구성하여 안전하고 유용한 특정 HTML 요소 목록을 허용합니다. 마크다운에서 원시 HTML(raw HTML) 사용은 일반적으로 권장되지 않지만, `
`(줄 바꿈), `

`/`

`(접을 수 있는 섹션), `_{`(아래 첨자), ``(키보드 입력) 같은 요소들은 표준 마크다운에서는 사용할 수 없는 유용한 서식 기능을 제공합니다. 이 규칙은 이러한 요소들을 명시적으로 허용하는 동시에 다른 요소들은 금지하여 기능성과 문서 이식성 사이의 균형을 맞춥니다.\n\n**파일**: `.markdownlint.jsonc`\n\n```jsonc\n{\n ...\n \"MD033\": {\n \"allowed_elements\": [\"br\", \"details\", \"summary\", \"sub\", \"kbd\"]\n },\n ...\n}\n```\n\n---\n\n### 단계 4: MD013과 같은 특정 markdownlint 규칙 제외\n\n#### 1. 충돌하거나 불필요한 규칙 비활성화\n\n이 액션은 중복되거나 다른 도구와 충돌하는 markdownlint 규칙을 비활성화합니다. `MD013`(줄 길이) 규칙은 Prettier가 이미 줄 바꿈을 처리하도록 구성되어 있으므로 명시적으로 비활성화합니다. 두 도구가 동일한 규칙을 관리하면 충돌이 발생할 수 있습니다. `MD041`(파일의 첫 줄은 최상위 헤딩이어야 함) 규칙은 메타데이터 블록이나 헤딩 없는 소개로 시작하는 등 더 유연한 문서 구조를 허용하기 위해 비활성화합니다.\n\n**파일**: `.markdownlint.jsonc`\n\n```jsonc\n{\n ...\n \"MD013\": false,\n \"MD041\": false,\n ...\n}\n```\n\n---\n\n### 단계 5: JSON 구성 파일 최종본\n\n#### 1. `.prettierrc.json` 최종 확정\n\n이 액션으로 Prettier 구성 파일이 완성되었음을 확인합니다. 이 파일은 프로젝트 전체에서 마크다운 파일의 서식을 자동으로 지정하는 유일한 기준(single source of truth)이 됩니다.\n\n**파일**: `.prettierrc.json`\n\n```json\n{\n \"printWidth\": 80,\n \"proseWrap\": \"always\",\n \"endOfLine\": \"lf\",\n \"overrides\": [\n {\n \"files\": \"*.md\",\n \"options\": {\n \"parser\": \"markdown\"\n }\n }\n ]\n}\n```\n\n#### 2. `.markdownlint.jsonc` 최종 확정\n\n이 액션으로 markdownlint 구성 파일이 완성되었음을 확인합니다. 이 파일은 로컬 스크립트와 CI 파이프라인에서 프로젝트의 스타일 규칙에 맞춰 마크다운 파일의 유효성을 검사하는 데 사용될 것입니다.\n\n**파일**: `.markdownlint.jsonc`\n\n```jsonc\n{\n \"default\": true,\n \"MD013\": false,\n \"MD041\": false,\n \"MD003\": { \"style\": \"atx\" },\n \"MD004\": { \"style\": \"dash\" },\n \"MD029\": { \"style\": \"one_or_ordered\" },\n \"MD046\": { \"style\": \"fenced\" },\n \"MD048\": { \"style\": \"backtick\" },\n \"MD049\": { \"style\": \"underscore\" },\n \"MD050\": { \"style\": \"asterisk\" },\n \"MD025\": { \"front_matter_title\": \"\" },\n \"MD040\": true,\n \"MD033\": {\n \"allowed_elements\": [\"br\", \"details\", \"summary\", \"sub\", \"kbd\"]\n }\n}\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n1. `prettier`와 `markdownlint-cli2`가 설치되어 있는지 확인합니다(예: `npm install -g prettier markdownlint-cli2` 사용).\n2. 규칙을 위반하는 내용으로 임시 파일 `test.md`를 생성합니다.\n\n ```markdown\n #최상위 헤더#\n\n 이 줄은 구성 파일에 명시된 80자 제한보다 훨씬 길기 때문에 포맷터에 의해 반드시 줄 바꿈되어야 하는 매우 긴 텍스트 줄입니다.\n\n * 항목 1\n * 항목 2\n\n **굵은 텍스트**\n\n 밑줄은 허용되지 않습니다\n ```\n\n3. 포맷터를 실행하고 파일 변경 사항을 관찰합니다.\n\n ```bash\n # 이 명령어는 파일을 바로 수정합니다\n prettier --write test.md\n ```\n\n4. 린터를 실행하고 보고된 오류를 관찰합니다.\n\n ```bash\n # 이 명령어는 표준 출력으로 위반 사항을 보고합니다\n markdownlint-cli2 test.md\n ```\n\n5. 임시 파일을 정리합니다.\n\n ```bash\n rm test.md\n ```\n\n### 4.2. 예상 결과\n\n1. `prettier --write test.md`를 실행하면, `test.md`의 내용은 자동으로 다음과 같이 재포맷되어야 합니다:\n\n ```markdown\n # 최상위 헤더\n\n 이 줄은 구성 파일에 명시된 80자 제한보다 훨씬 길기 때문에 포맷터에 의해 반드시 줄 바꿈되어야 하는 매우 긴 텍스트\n 줄입니다.\n\n - 항목 1\n - 항목 2\n\n ***굵은 텍스트***\n\n 밑줄은 허용되지 않습니다\n ```\n\n2. `markdownlint-cli2 test.md` 명령어의 출력은 줄 길이는 무시하면서 잘못된 헤더 스타일, 허용되지 않는 HTML, 잘못된 강조 스타일에 대한 위반 사항을 보고해야 합니다:\n\n ```\n test.md:1 MD003/header-style 헤더 스타일 [예상: atx; 실제: atx_closed]\n test.md:8 MD050/strong-style 강조 스타일 [예상: asterisk; 실제: underscore]\n test.md:10 MD033/no-inline-html 인라인 HTML [요소: u]\n ```","프로젝트의 마크다운 표준을 코드화한 Prettier용 `.prettierrc.json` 파일과 markdownlint용 `.markdownlint.jsonc` 파일",[210,213,215,217,219],{"_24":211,"_83":39,"_84":212,"_85":61},"줄 너비 및 산문 줄 바꿈을 위한 Prettier 구성",7,{"_24":214,"_83":39,"_84":212,"_85":88},"헤더, 목록, 강조 스타일에 대한 Markdownlint 구성",{"_24":216,"_83":39,"_84":212,"_85":91},"허용된 HTML 요소에 대한 Markdownlint 규칙 정의",{"_24":218,"_83":39,"_84":212,"_85":94},"MD013과 같은 특정 markdownlint 규칙 제외",{"_24":220,"_83":39,"_84":212,"_85":97},"완료된 JSON 구성 파일","마크다운 스타일과 서식 규칙을 자동으로 적용하기 위한 구성 파일을 생성",{"_22":223,"_24":224,"_75":225,"_77":226,"_79":227,"_51":239,"_42":99},"task-1751363406571","C++ 포매터 구성","# 작업: C++ 포맷터 설정\n\n> **Epic**: 코드 및 마크다운 포맷터 설정\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: `.clang-format` 파일을 설정하여 C++ 코딩 스타일을 자동으로 적용합니다.\n- **근거**: 이 작업은 프로젝트의 C++ 서식 규칙을 기계가 읽을 수 있는 단일 설정 파일로 정의하는 데 필수적입니다. 이 파일은 개발자가 로컬에서, 그리고 자동화된 CI 파이프라인 내에서 `clang-format` 도구를 통해 사용됩니다. 스타일 관련 논쟁을 없애고, 모든 C++ 코드가 일관된 표준을 따르도록 보장하는 것이 이 설정의 목적입니다. 이를 통해 코드 가독성과 유지보수성을 높이려는 프로젝트의 핵심 목표를 달성할 수 있습니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: C++ 코드 서식을 위한 상세 규칙이 포함된 `.clang-format` 파일이 `assets/` 디렉터리에 위치합니다.\n- **명세**: 파일에는 다음과 같은 서식 규칙이 설정됩니다 (이에 국한되지 않음):\n - `BasedOnStyle: Google`\n - `Language: Cpp`\n - `ColumnLimit: 80`\n - `IndentWidth: 2`\n - `UseTab: Never`\n - `BreakBeforeBraces: Attach`\n - `PointerAlignment: Left`\n - `SortIncludes: true`\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── assets/\n# └── .clang-format <-- 수정됨\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 일관된 코드 스타일을 적용하기 위해 개발 워크플로 내에서 `.clang-format` 설정 파일이 어떻게 사용되는지 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"개발 워크플로\"\n Dev[개발자] -- \"1\\. C++ 코드 작성/수정\" --> CppFile([C++ 소스 파일]);\n Dev -- \"2\\. 포맷터 실행\" --> FormatterTool[\"clang-format 도구\"];\n end\n \n subgraph \"자동 포맷팅\"\n ClangFormatConfig(\"assets/.clang-format\") -- \"3\\. 설정 읽기\" --> FormatterTool;\n FormatterTool -- \"4\\. 규칙 적용\" --> CppFile;\n CppFile --> FormattedCppFile([포맷팅된 C++ 코드]);\n end\n\n FormattedCppFile -- \"5\\. 리포지터리에 커밋\" --> Dev;\n```\n\n### 1.3. 완료 조건\n\n이 작업을 완료하려면 아래 항목들을 모두 마쳐야 합니다. 이 체크리스트는 개요이며, 각 항목의 구체적인 구현 방법은 3절에 설명되어 있습니다.\n\n- [ ] 기본 스타일 선택 (예: Google).\n- [ ] 들여쓰기, 줄 길이, 중괄호 줄 바꿈 설정.\n- [ ] 포인터 정렬 및 공백 규칙.\n- [ ] include 블록 정렬 및 분류 설정.\n- [ ] 최종 YAML 설정 파일.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 저장소\n- **관련 주요 구성요소**:\n - **자동화 도구**: 이 작업을 통해 자동화 도구의 핵심 자산이 만들어집니다. `.clang-format` 파일은 코딩 표준을 자동으로 적용하는 설정 파일로, 자동화 도구의 핵심 기능 중 하나를 담당합니다.\n - **언어 가이드라인**: `.clang-format` 설정은 C++ 서식 규칙을 정의하는 실행 가능한 표준 명세입니다. 사람이 읽는 C++ 가이드라인 문서에서는 이 파일을 서식에 대한 유일한 기준(Single Source of Truth)으로 삼습니다.\n - **엔지니어링 원칙**: 설정 파일에 정의된 규칙들(예: 줄 길이, 중괄호 스타일)은 가독성, 일관성, 유지보수성이라는 프로젝트의 상위 원칙을 직접적으로 구현한 것입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `assets/.clang-format`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 단계(`Step`)는 **완료 조건**의 각 항목과 일치합니다. 각 단계는 여러 세부 실행(`Action`)으로 구성됩니다. 각 실행에 대해서는 제목, 명확한 설명('무엇을', '왜'를 포함), 그리고 정확한 코드 구현을 제시합니다.\n\n---\n\n### 단계 1: 기본 스타일 선택 (예: Google)\n\n#### 1. 기반 스타일 설정\n\n`BasedOnStyle` 매개변수는 널리 사용되는 스타일 가이드의 규칙들을 기본값으로 제공합니다. 여기서 `Google` 스타일을 기반으로 선택하면, C++ 커뮤니티에서 널리 인정받는 합리적인 코드 스타일에서 시작할 수 있습니다. 덕분에 세세한 규칙들을 일일이 설정할 필요가 줄어듭니다. 이 작업은 커뮤니티에서 검증된 강력한 기준 위에서 설정을 시작하도록 보장합니다. 현재 이 매개변수는 주석 처리되어 있으므로 활성화해야 합니다.\n\n**파일**: `assets/.clang-format`\n\n```yaml\n---\nLanguage: Cpp\nBasedOnStyle: Google\nAccessModifierOffset: -1\n...\n```\n\n---\n\n### 단계 2: 들여쓰기, 줄 길이, 중괄호 줄 바꿈 설정\n\n#### 1. 들여쓰기 및 줄 길이 제한 설정\n\n이 작업으로 프로젝트의 핵심적인 공백 및 줄 바꿈 규칙을 정합니다. `IndentWidth: 2`와 `UseTab: Never` 설정은 공백 문자 2개를 사용해 들여쓰기를 통일합니다. 이는 에디터마다 다른 탭 너비 설정으로 인한 문제를 방지하는 일반적인 방법입니다. `ColumnLimit: 80`은 한 줄의 최대 길이를 80자로 제한하여 가로 스크롤 없이도 코드를 편하게 읽을 수 있도록 합니다. 이는 우리 프로젝트의 핵심 원칙이기도 합니다.\n\n**파일**: `assets/.clang-format`\n\n```yaml\n...\nBreakStringLiterals: true\nColumnLimit: 80\nCommentPragmas: \"^ IWYU pragma:\"\n...\nIndentCaseLabels: true\nIndentGotoLabels: true\nIndentPPDirectives: None\nIndentWidth: 2\nIndentWrappedFunctionNames: false\n...\nTabWidth: 8\nUseCRLF: false\nUseTab: Never\n---\n```\n\n#### 2. 중괄호 줄 바꿈 스타일 설정\n\n이 작업은 제어문, 함수, 클래스에 대한 중괄호의 위치를 정의합니다. `BreakBeforeBraces: Attach`로 설정하면 여는 중괄호(`{`)가 해당 구문과 같은 줄에 위치해야 합니다 (예: `if (condition) {`). 이러한 '붙이는' 스타일은 Google 스타일의 핵심 특징이며, 코드를 세로로 더 간결하게 만듭니다.\n\n**파일**: `assets/.clang-format`\n\n```yaml\n...\n SplitEmptyRecord: true\n SplitEmptyNamespace: true\nBreakBeforeBinaryOperators: None\nBreakBeforeBraces: Attach\nBreakBeforeInheritanceComma: false\nBreakInheritanceList: BeforeColon\n...\n```\n\n---\n\n### 단계 3: 포인터 정렬 및 공백 규칙\n\n#### 1. 포인터 및 참조 정렬 정의\n\n이 작업은 포인터(`*`)와 참조(`&`)의 정렬 스타일을 일관되게 적용합니다. `PointerAlignment: Left`로 설정하면 심볼이 변수명(`const std::string &str`)이 아닌 타입(`const std::string& str`)에 맞춰 정렬됩니다. 이는 C++ 코드의 명확성을 위해 매우 중요한 스타일 결정입니다. `DerivePointerAlignment: true` 설정은 `clang-format`이 예외적인 경우를 지능적으로 처리하도록 유지하되, 명시적인 `Left` 정렬이 주된 규칙으로 사용됩니다.\n\n**파일**: `assets/.clang-format`\n\n```yaml\n...\nCpp11BracedListStyle: true\nDeriveLineEnding: true\nDerivePointerAlignment: true\nDisableFormat: false\n...\nPenaltyReturnTypeOnItsOwnLine: 200\nPointerAlignment: Left\nRawStringFormats:\n...\n```\n\n---\n\n### 단계 4: include 블록 정렬 및 분류 설정\n\n#### 1. include 자동 정렬 및 그룹화 설정\n\n이 작업은 `#include` 지시문을 구성하기 위한 엄격한 규칙을 설정합니다. `SortIncludes: true`는 알파벳순 정렬을 활성화하고, `IncludeBlocks: Regroup`은 `IncludeCategories` 규칙에 따라 전체 include 블록의 순서를 재정렬하도록 `clang-format`에 지시합니다. 카테고리는 정규 표현식을 사용하여 헤더를 논리적 그룹(예: 시스템 헤더, 라이브러리 헤더, 프로젝트 헤더)으로 분리하며, 이를 통해 파일 의존성을 명확하게 하고 관리하기 쉽게 만듭니다.\n\n**파일**: `assets/.clang-format`\n\n```yaml\n...\nForEachMacros:\n - foreach\n - Q_FOREACH\n - BOOST_FOREACH\nIncludeBlocks: Regroup\nIncludeCategories:\n - Regex: '^'\n Priority: 2\n SortPriority: 0\n - Regex: '^<.*\\\\.hpp>'\n Priority: 1\n SortPriority: 0\n - Regex: \"^<.*\"\n Priority: 2\n SortPriority: 0\n - Regex: \".*\"\n Priority: 3\n SortPriority: 0\nIncludeIsMainRegex: \"([-_](test|unittest))?$\"\n...\nReflowComments: true\nSortIncludes: true\nSortUsingDeclarations: true\nSpaceAfterCStyleCast: false\n...\n```\n\n---\n\n### 단계 5: 최종 YAML 설정 파일\n\n#### 1. 최종 설정 상태 확인\n\n이 작업은 모든 개별 규칙이 올바르게 설정되었는지, 그리고 파일 전체가 프로젝트의 완전하고 최종적인 서식 명세를 나타내는지 확인합니다. 최종 검토를 통해 충돌하거나 의도하지 않은 설정이 없는지 확인합니다. `Language: Cpp` 지정자와 `---` YAML 문서 구분자가 있으면 파일이 완전하고 유효한 `clang-format` 설정임을 나타냅니다.\n\n**파일**: `assets/.clang-format`\n\n```yaml\n---\nLanguage: Cpp\nBasedOnStyle: Google\n...\nUseCRLF: false\nUseTab: Never\n---\n```\n\n---\n\n## 4. 검증 절차\n\n### 4.1. 검증 단계\n\n`.clang-format` 파일이 명시된 규칙에 따라 C++ 코드를 올바르게 포맷하는지 확인하려면 다음 단계를 실행해야 합니다. 이를 위해서는 로컬 시스템에 `clang-format`이 설치되어 있어야 합니다.\n\n```bash\n# 1. 프로젝트 루트에 포맷되지 않은 임시 C++ 파일 'test.cpp'를 생성합니다.\n# 내용은 다음과 같습니다:\ncat << EOF > test.cpp\n#include \n#include \"my_header.h\"\n#include \n\nint main()\n{\n int* p = nullptr;\n const std::string & my_str = \"hello\";\n if(true){\n std::cout << my_str << std::endl;\n }\n return 0;\n}\nEOF\n\n# 2. 테스트 파일에 clang-format을 실행합니다. '-style=file' 플래그는\n# 도구가 상위 디렉터리에서 .clang-format 설정을 찾아 사용하도록 지시합니다.\n# '-i' 플래그는 변경 사항을 파일에 바로 적용합니다.\n# 참고: 이 명령어는 'assets/.clang-format'이 './.clang-format'으로 이동되었거나\n# 'assets' 디렉터리에서 clang-format이 실행된다고 가정합니다. 프로젝트 전체에\n# 사용하려면 파일이 루트에 있어야 합니다. 이 테스트에서는 루트에 있다고 가정합니다.\n# (개발자는 먼저 assets/.clang-format을 ./.clang-format으로 이동해야 합니다)\nmv assets/.clang-format ./.clang-format\nclang-format -style=file -i test.cpp\n\n# 3. 포맷된 파일의 내용을 표시하여 변경 사항을 확인합니다.\ncat test.cpp\n\n# 4. 임시 파일을 정리합니다.\nrm test.cpp\nrm ./.clang-format\n```\n\n### 4.2. 예상 결과\n\n3단계 실행 후, 표준 출력에는 `test.cpp`의 내용이 아래와 같이 정확하게 포맷되어 표시되어야 합니다. 정렬된 include, 붙여진 중괄호, 왼쪽으로 정렬된 포인터, 일관된 들여쓰기를 확인하세요.\n\n```cpp\n#include \n#include \n\n#include \"my_header.h\"\n\nint main() {\n int* p = nullptr;\n const std::string& my_str = \"hello\";\n if (true) {\n std::cout << my_str << std::endl;\n }\n return 0;\n}\n```","`assets/` 디렉토리에 C++ 코드 서식에 대한 상세 규칙을 담은 `.clang-format` 파일",[228,231,233,235,237],{"_24":229,"_83":39,"_84":230,"_85":61},"기본 스타일 선택 (예: Google)",8,{"_24":232,"_83":39,"_84":230,"_85":88},"들여쓰기, 줄 길이, 중괄호 줄 바꿈 구성",{"_24":234,"_83":39,"_84":230,"_85":91},"포인터 정렬 및 공백 규칙",{"_24":236,"_83":39,"_84":230,"_85":94},"include 블록 정렬 및 분류 구성",{"_24":238,"_83":39,"_84":230,"_85":97},"완료된 YAML 구성 파일","C++ 코딩 스타일을 자동으로 적용하기 위한 .clang-format 파일을 설정",{"_22":241,"_24":242,"_75":243,"_77":244,"_79":245,"_51":257,"_42":99},"task-1751363473107","macOS 포매터 설치 스크립트","# 작업: macOS 포맷터 설치 스크립트\n\n> **에픽**: 로컬 포맷터 설치 스크립트 구현\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: Homebrew를 사용하여 macOS에서 포맷터 설치를 자동화하는 셸 스크립트 개발.\n- **근거**: 원활하고 표준화된 로컬 개발 환경을 제공하기 위해, 이 스크립트는 필요한 포맷팅 도구의 획득을 자동화합니다. 설정 프로세스를 코드화함으로써 수동 구성을 없애고 개발자의 설정 장벽을 낮추며, 모든 팀원이 동일한 도구 버전을 사용하도록 보장합니다. 이는 `Automation Tooling` 컴포넌트의 핵심 목표입니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: Prettier와 markdownlint-cli를 설치하는 macOS용 실행 가능 `install_formatters.sh` 스크립트.\n- **사양**:\n - **스크립트 이름**: `install_formatters.sh`\n - **플랫폼**: macOS\n - **의존성 관리자**: Homebrew\n - **설치 도구**: `prettier`, `markdownlint-cli`\n - **실행**: 스크립트는 `bash` 또는 `./`를 통해 실행 가능해야 합니다.\n - **멱등성**: 스크립트는 도구가 이미 설치된 경우 업그레이드를 시도하여 처리해야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── scripts/\n# └── install/\n# └── os/\n# └── macos/\n# └── install_formatters.sh <-- 신규\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"개발자 머신\"\n Start(\"개발자가
'install_formatters.sh' 실행\")\n CheckBrew[\"Homebrew 확인\"]\n InstallBrew{\"Homebrew
설치 여부\"}\n UpdateBrew[\"'brew update' 실행\"]\n InstallTools[\"도구 설치/업그레이드
(Prettier, markdownlint-cli)\"]\n End(\"'설치 완료' 표시\")\n end\n\n subgraph \"외부 서비스\"\n BrewRepo[\"Homebrew 리포지토리\"]\n end\n\n Start --> CheckBrew\n CheckBrew --> InstallBrew\n InstallBrew -- No --> InstallHomebrew[\"Homebrew 설치\"]\n InstallHomebrew --> UpdateBrew\n InstallBrew -- Yes --> UpdateBrew\n UpdateBrew --> BrewRepo\n BrewRepo --> UpdateBrew\n UpdateBrew --> InstallTools\n InstallTools --> BrewRepo\n BrewRepo --> InstallTools\n InstallTools --> End\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 3장에 있습니다.\n\n- [ ] Homebrew 존재 여부 확인 및 설치 로직.\n- [ ] `brew update` 명령어 구현.\n- [ ] Prettier 설치 또는 업그레이드 로직.\n- [ ] markdownlint-cli 설치 또는 업그레이드 로직.\n- [ ] 사용자를 위한 진행률 메시지 포함.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 리포지토리\n- **관련 주요 컴포넌트**:\n - **Automation Tooling**: 이 컴포넌트는 프로젝트 표준을 자동으로 강제하는 모든 스크립트, 구성 및 워크플로우를 포함합니다. 이 설치 스크립트는 개발자가 변경 사항을 커밋하고 푸시하기 전에 콘텐츠를 포맷하는 데 필요한 로컬 도구를 제공하므로 `Automation Tooling` 컴포넌트의 기본 요소이며, 프로젝트의 상위 수준 데이터 흐름과 일치합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `scripts/install/os/macos/install_formatters.sh`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공합니다.\n\n---\n\n### 단계 1: Homebrew 존재 여부 확인 및 설치 로직\n\n#### 1. Homebrew 설치 확인\n\n이 작업은 macOS에 필요한 패키지 관리자인 Homebrew가 시스템에 있는지 먼저 확인하여 스크립트의 안정성을 보장합니다. `command -v brew` 확인은 조용히 그 존재를 검증합니다. 만약 찾을 수 없다면, 스크립트는 사용자에게 알리고 공식 설치 명령어를 사용하여 설치를 진행합니다. 이를 통해 스크립트 실패를 방지하고, 아무것도 설치되지 않은 깨끗한 머신에서도 완전히 자동화된 설정을 제공합니다.\n\n**파일**: `scripts/install/os/macos/install_formatters.sh`\n\n```bash\n#!/bin/bash\n\n# 명령어가 0이 아닌 상태로 종료되면 즉시 스크립트를 중단합니다.\nset -e\n\necho \"--- Homebrew 확인 ---\"\nif ! command -v brew &> /dev/null; then\n echo \"Homebrew를 찾을 수 없습니다. Homebrew를 설치합니다...\"\n /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\nelse\n echo \"Homebrew가 이미 설치되어 있습니다.\"\nfi\n...\n```\n\n---\n\n### 단계 2: `brew update` 명령어 구현\n\n#### 1. Homebrew Formulae 업데이트\n\n이 작업은 로컬 Homebrew 패키지 데이터베이스를 업데이트합니다. 새로운 패키지를 설치하기 전에 Homebrew가 필요한 도구들(`prettier` 및 `markdownlint-cli`)의 최신 버전을 가져오도록 보장하는 중요한 단계입니다. 이를 통해 오래된 버전의 설치를 방지하고 모든 개발자 환경에서 일관성을 보장합니다.\n\n**파일**: `scripts/install/os/macos/install_formatters.sh`\n\n```bash\n...\n echo \"Homebrew가 이미 설치되어 있습니다.\"\nfi\n\necho \"\\n--- Homebrew 업데이트 ---\"\nbrew update\n...\n```\n\n---\n\n### 단계 3: Prettier 설치 또는 업그레이드 로직\n\n#### 1. Prettier의 멱등성 설치 구현\n\n이 작업은 Prettier 포맷터에 대한 멱등성 로직을 구현합니다. 스크립트는 먼저 `brew list`를 사용하여 `prettier`가 이미 설치되어 있는지 확인합니다. 설치되어 있다면, 패키지를 최신 버전으로 업그레이드합니다. 설치되어 있지 않다면, 새로 설치합니다. 이 접근 방식은 스크립트가 여러 번 실행되어도 오류를 일으키지 않으며, 개발자의 도구 세트를 최신 상태로 유지하도록 보장합니다.\n\n**파일**: `scripts/install/os/macos/install_formatters.sh`\n\n```bash\n...\necho \"\\n--- 도구 설치 ---\"\n\nif brew list prettier &>/dev/null; then\n echo \"Prettier가 이미 설치되어 있습니다. 업그레이드합니다...\"\n brew upgrade prettier\nelse\n echo \"Prettier를 설치합니다...\"\n brew install prettier\nfi\n...\n```\n\n---\n\n### 단계 4: markdownlint-cli 설치 또는 업그레이드 로직\n\n#### 1. markdownlint-cli의 멱등성 설치 구현\n\n이 작업은 `markdownlint-cli` 린터에 대해 동일한 멱등성 로직을 구현합니다. 도구가 이미 있는지 확인하고, 있다면 업그레이드하며, 없다면 새로 설치합니다. 이것은 Prettier에 대한 로직과 동일한 방식으로, 필요한 모든 포맷팅 및 린팅 도구에 대해 일관되고 견고한 설치 프로세스를 보장합니다.\n\n**파일**: `scripts/install/os/macos/install_formatters.sh`\n\n```bash\n...\nelse\n echo \"Prettier를 설치합니다...\"\n brew install prettier\nfi\n\nif brew list markdownlint-cli &>/dev/null; then\n echo \"markdownlint-cli가 이미 설치되어 있습니다. 업그레이드합니다...\"\n brew upgrade markdownlint-cli\nelse\n echo \"markdownlint-cli를 설치합니다...\"\n brew install markdownlint-cli\nfi\n...\n```\n\n---\n\n### 단계 5: 사용자를 위한 진행률 메시지 포함\n\n#### 1. 사용자용 진행률 표시기 추가\n\n이 작업은 스크립트 전체에 일련의 `echo` 구문을 추가합니다. 이 메시지들은 사용자에게 스크립트가 무엇을 하고 있는지(예: 의존성 확인, 업데이트, 설치)에 대한 명확한 실시간 피드백을 제공합니다. 이는 스크립트의 실행을 투명하게 만들고 각 단계가 성공적으로 완료되었음을 확인하여 사용자 경험을 향상시킵니다.\n\n**파일**: `scripts/install/os/macos/install_formatters.sh`\n\n```bash\n...\nfi\n\necho \"\\n--- Homebrew 업데이트 ---\"\nbrew update\n\necho \"\\n--- 도구 설치 ---\"\n\nif brew list prettier &>/dev/null; then\n...\nelse\n echo \"markdownlint-cli를 설치합니다...\"\n brew install markdownlint-cli\nfi\n\necho \"\\n--- 설치 완료 ---\"\necho \"Prettier와 markdownlint-cli를 사용할 준비가 되었습니다.\"\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n1. 스크립트가 있는 디렉터리로 이동합니다.\n2. 스크립트를 실행 가능하게 만듭니다.\n3. 스크립트를 실행합니다.\n\n```bash\n# 1. 스크립트 디렉터리로 이동\ncd scripts/install/os/macos\n\n# 2. 스크립트에 실행 권한 추가\nchmod +x install_formatters.sh\n\n# 3. 스크립트 실행\n./install_formatters.sh\n```\n\n### 4.2. 예상 결과\n\n콘솔 출력은 각 프로세스 단계를 확인하는 일련의 진행률 메시지를 표시해야 합니다. Homebrew와 도구들의 설치 여부에 따라 정확한 출력은 약간 다를 수 있지만, 전체적인 흐름은 다음과 같아야 합니다:\n\n```\n--- Homebrew 확인 ---\nHomebrew가 이미 설치되어 있습니다.\n\n--- Homebrew 업데이트 ---\n... (brew update 출력) ...\n\n--- 도구 설치 ---\nPrettier가 이미 설치되어 있습니다. 업그레이드합니다...\n... (prettier에 대한 brew upgrade 출력) ...\nmarkdownlint-cli가 이미 설치되어 있습니다. 업그레이드합니다...\n... (markdownlint-cli에 대한 brew upgrade 출력) ...\n\n--- 설치 완료 ---\nPrettier와 markdownlint-cli를 사용할 준비가 되었습니다.\n```","Prettier와 markdownlint-cli를 설치하는 macOS용 실행 가능한 `install_formatters.sh` 스크립트",[246,249,251,253,255],{"_24":247,"_83":39,"_84":248,"_85":61},"Homebrew 존재 여부 확인 및 설치 로직",9,{"_24":250,"_83":39,"_84":248,"_85":88},"`brew update` 명령어 구현",{"_24":252,"_83":39,"_84":248,"_85":91},"Prettier 설치 또는 업그레이드 로직",{"_24":254,"_83":39,"_84":248,"_85":94},"markdownlint-cli 설치 또는 업그레이드 로직",{"_24":256,"_83":39,"_84":248,"_85":97},"사용자를 위한 진행 상황 메시지 포함","Homebrew를 사용하여 macOS에 포매터 설치를 자동화하는 셸 스크립트를 개발",{"_22":259,"_24":260,"_75":261,"_77":262,"_79":263,"_51":275,"_42":99},"task-1751363506185","Ubuntu 포매터 설치 스크립트","# 작업: Ubuntu 포맷터 설치 스크립트\n\n> **에픽**: 로컬 포맷터 설치 스크립트 구현\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: apt 및 npm을 사용하여 Ubuntu에 포맷터를 자동으로 설치하는 셸 스크립트 개발.\n- **근거**: 모든 개발자 환경에서 일관성을 보장하기 위해, 이 작업은 Ubuntu 플랫폼에 필요한 포맷팅 도구(Prettier, markdownlint-cli) 설정을 자동화합니다. 이러한 표준화는 프로젝트의 핵심 목표이며, 이를 통해 모든 개발자가 `Automation Tooling` 컴포넌트를 올바르게 사용할 수 있게 됩니다. 결과적으로 초기 설정의 어려움을 줄이고, 로컬 환경의 유효성 검사가 CI 파이프라인의 검사와 일치하도록 보장합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: Prettier와 markdownlint-cli를 설치하는 Ubuntu용 실행 가능 `install_formatters.sh` 스크립트.\n- **사양**:\n - 스크립트는 유효한 Bash 스크립트여야 합니다 (`#!/bin/bash`).\n - 사용자가 실행할 수 있어야 합니다 (`chmod +x`).\n - 루트 권한이 필요한 명령어(`apt-get`, 전역 `npm install`)에는 `sudo`를 사용해야 합니다.\n - `npm`의 존재 여부를 확인하고, 없는 경우 `apt-get`을 통해 `nodejs`와 `npm`을 설치해야 합니다.\n - `npm`을 사용하여 `prettier`와 `markdownlint-cli`를 전역으로 설치해야 합니다.\n - 명령어 실행 실패 시 즉시 종료해야 합니다 (`set -e`).\n- **결과 파일 구조**\n\n```bash\n./\n└── scripts/\n └── install/\n └── os/\n └── ubuntu/\n └── install_formatters.sh <-- New\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"Ubuntu 환경\"\n Dev[\"개발자\"]\n Apt[\"apt-get 패키지 관리자\"]\n Npm[\"npm 패키지 관리자\"]\n end\n \n subgraph \"설치 스크립트\"\n Script[\"install_formatters.sh\"]\n end\n\n Dev -- \"1\\. 스크립트 실행\" --> Script\n Script -- \"2\\. 패키지 목록 업데이트\" --> Apt\n Script -- \"3\\. npm 확인\" --> Npm\n Script -- \"4\\. 필요 시 nodejs/npm 설치\" --> Apt\n Script -- \"5\\. Prettier 전역 설치\" --> Npm\n Script -- \"6\\. markdownlint-cli 전역 설치\" --> Npm\n Npm -- \"7\\. 도구 사용 가능\" --> Dev\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 아래 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현 내용은 3장에 기술되어 있습니다.\n\n- [ ] `apt-get`을 사용한 패키지 목록 업데이트 로직.\n- [ ] Node.js 및 npm 존재 여부 확인 및 설치 로직.\n- [ ] npm을 통한 Prettier 전역 설치.\n- [ ] npm을 통한 markdownlint-cli 전역 설치.\n- [ ] 사용자용 안내 및 완료 메시지 포함.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 저장소\n- **관련 주요 컴포넌트**:\n - **Automation Tooling**: 이 작업은 `Automation Tooling` 컴포넌트에 직접적으로 기여합니다. 이 컴포넌트는 프로젝트 표준을 자동으로 강제하는 모든 스크립트, 설정, 워크플로우를 포함합니다. 이 설치 스크립트는 해당 툴링의 기초적인 부분으로, 개발자들이 포맷터를 사용하기 위해 로컬 환경을 설정할 수 있도록 지원합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정될 것입니다.\n\n- `scripts/install/os/ubuntu/install_formatters.sh`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 각 항목에 해당합니다. 각 `단계`는 여러 세부 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `apt-get`을 사용한 패키지 목록 업데이트 로직\n\n#### 1. 스크립트 초기화 및 패키지 업데이트\n\n이 작업은 스크립트의 기초를 설정합니다. `#!/bin/bash` 쉬뱅(shebang)은 스크립트가 Bash로 실행되도록 보장합니다. `set -e`는 중요한 안전장치로, 명령어 실행이 실패할 경우 스크립트를 즉시 종료시켜 불완전하거나 손상된 설치를 방지합니다. 그런 다음, 스크립트는 사용자에게 패키지 목록을 업데이트 중임을 알리고 `sudo apt-get update -y`를 실행합니다. 이는 이후의 설치 과정에서 정확하고 최신 버전의 패키지를 가져오기 위한 필수 전제 조건입니다.\n\n**파일**: `scripts/install/os/ubuntu/install_formatters.sh`\n\n```bash\n#!/bin/bash\n\n# 명령어가 0이 아닌 상태로 종료되면 즉시 스크립트를 종료합니다.\nset -e\n\necho \"--- 패키지 목록 업데이트 중 ---\"\nsudo apt-get update -y\n```\n\n---\n\n### 단계 2: Node.js 및 npm 존재 여부 확인 및 설치 로직\n\n#### 1. Node.js 및 npm 조건부 설치 구현\n\n이 작업은 필수 요소들을 설치하기 전에 먼저 확인하여 스크립트의 안정성을 높입니다. `if ! command -v npm &> /dev/null` 구문은 시스템의 PATH에 `npm` 명령어가 있는지 확인합니다. 만약 `npm`이 없다면, 스크립트는 사용자에게 이를 알리고 `sudo apt-get install -y`를 사용하여 `nodejs`와 `npm`을 모두 설치합니다. `npm`이 이미 존재한다면, 사용자에게 알리고 설치를 건너뛰어 불필요한 작업을 방지합니다.\n\n**파일**: `scripts/install/os/ubuntu/install_formatters.sh`\n\n```bash\n...\nsudo apt-get update -y\n\necho \"\\n--- Node.js 및 npm 확인 중 ---\"\nif ! command -v npm &> /dev/null; then\n echo \"npm을 찾을 수 없습니다. Node.js와 npm을 설치합니다...\"\n sudo apt-get install -y nodejs npm\nelse\n echo \"Node.js와 npm이 이미 설치되어 있습니다.\"\nfi\n```\n\n---\n\n### 단계 3: npm을 통한 Prettier 전역 설치\n\n#### 1. Prettier 전역 설치\n\n이 작업은 프로젝트의 주요 마크다운 포맷터를 설치합니다. 스크립트는 먼저 `sudo -v`를 실행하여 `sudo` 타임스탬프를 갱신합니다. 이를 통해 시간이 좀 지난 후에도 사용자에게 다시 비밀번호를 묻지 않도록 합니다. 그런 다음 `sudo npm install -g prettier`를 사용하여 패키지를 전역으로 설치합니다. `-g` 플래그는 `prettier` 커맨드 라인 도구를 시스템 전역에서 사용할 수 있게 만들어, 어떤 디렉터리에서든 실행할 수 있도록 하므로 필수적입니다.\n\n**파일**: `scripts/install/os/ubuntu/install_formatters.sh`\n\n```bash\n...\nelse\n echo \"Node.js와 npm이 이미 설치되어 있습니다.\"\nfi\n\n# sudo 타임스탬프 갱신\nsudo -v\n\necho \"\\n--- npm으로 도구 설치 중 ---\"\n\necho \"Prettier를 전역으로 설치/업데이트 중...\"\nsudo npm install -g prettier\n```\n\n---\n\n### 단계 4: npm을 통한 markdownlint-cli 전역 설치\n\n#### 1. markdownlint-cli 전역 설치\n\n이 작업은 Prettier가 다루지 않는 마크다운 스타일 규칙을 강제하는 데 사용되는 린터를 설치합니다. Prettier 설치와 유사하게, `sudo npm install -g markdownlint-cli`를 사용하여 `markdownlint` 커맨드 라인 도구를 전역으로 사용할 수 있게 만듭니다. 이를 통해 프로젝트의 마크다운 파일들이 `.markdownlint.jsonc`에 정의된 규칙에 따라 유효성을 검증받을 수 있도록 보장합니다.\n\n**파일**: `scripts/install/os/ubuntu/install_formatters.sh`\n\n```bash\n...\necho \"Prettier를 전역으로 설치/업데이트 중...\"\nsudo npm install -g prettier\n\necho \"markdownlint-cli를 전역으로 설치/업데이트 중...\"\nsudo npm install -g markdownlint-cli\n```\n\n---\n\n### 단계 5: 사용자용 안내 및 완료 메시지 포함\n\n#### 1. 최종 확인 및 안내 메시지 추가\n\n이 마지막 작업은 사용자에게 설치 과정이 성공적으로 완료되었음을 확인하는 중요한 피드백을 제공합니다. 어떤 도구들이 설치되었는지 명시하고 필요한 다음 단계를 안내합니다. 터미널을 다시 시작하거나 프로파일을 소싱하라는 지침은 중요합니다. 왜냐하면 전역 npm 설치는 시스템의 PATH를 수정하는데, 이러한 변경 사항은 현재 셸 세션에 즉시 반영되지 않기 때문입니다.\n\n**파일**: `scripts/install/os/ubuntu/install_formatters.sh`\n\n```bash\n...\necho \"markdownlint-cli를 전역으로 설치/업데이트 중...\"\nsudo npm install -g markdownlint-cli\n\necho \"\\n--- 설치 완료 ---\"\necho \"Prettier와 markdownlint-cli를 사용할 준비가 되었습니다.\"\necho \"변경 사항을 적용하려면 터미널을 다시 시작하거나 'source ~/.bashrc'를 실행해 주세요.\"\n```\n\n---\n\n## 4. 검증 절차\n\n### 4.1. 검증 단계\n\n- Ubuntu 기반 시스템의 개발자는 구현을 검증하기 위해 프로젝트의 루트 디렉터리에서 다음 명령어들을 실행해야 합니다.\n\n```bash\n# 1. 스크립트에 실행 권한 부여\nchmod +x scripts/install/os/ubuntu/install_formatters.sh\n\n# 2. 설치 스크립트 실행\n# 참고: sudo 비밀번호를 입력하라는 메시지가 표시됩니다.\n./scripts/install/os/ubuntu/install_formatters.sh\n\n# 3. PATH가 업데이트되도록 새 터미널을 엽니다.\n# 그 다음, 각 도구의 버전을 확인하여 설치를 검증합니다.\n\n# 4. Prettier 검증\nprettier --version\n\n# 5. markdownlint-cli 검증\nmarkdownlint --version\n```\n\n### 4.2. 예상 결과\n\n- 설치 스크립트는 오류 없이 각 단계에 대한 진행 메시지를 출력해야 합니다.\n- 새 터미널에서 검증 명령어를 실행하면 시스템은 각 도구의 버전 번호를 출력해야 합니다. 정확한 버전 번호는 다를 수 있습니다.\n\n```\n# 검증 명령어 실행 시 예상 출력 (버전은 예시입니다)\n$ prettier --version\n3.2.5\n$ markdownlint --version\n0.39.0\n```","Prettier와 markdownlint-cli를 설치하는 Ubuntu용 실행 가능한 `install_formatters.sh` 스크립트",[264,267,269,271,273],{"_24":265,"_83":39,"_84":266,"_85":61},"`apt-get`을 사용한 패키지 목록 업데이트 로직",10,{"_24":268,"_83":39,"_84":266,"_85":88},"Node.js 및 npm 존재 여부 확인 및 설치 로직",{"_24":270,"_83":39,"_84":266,"_85":91},"npm을 통한 Prettier 전역 설치",{"_24":272,"_83":39,"_84":266,"_85":94},"npm을 통한 markdownlint-cli 전역 설치",{"_24":274,"_83":39,"_84":266,"_85":97},"사용자용 안내 및 완료 메시지 포함","apt와 npm을 사용하여 Ubuntu에 포매터 설치를 자동화하는 셸 스크립트를 개발",{"_22":277,"_24":278,"_75":279,"_77":280,"_79":281,"_51":293,"_42":99},"task-1751363609113","셸 스크립트 코딩 스타일 가이드","# 작업: 셸 스크립트 코딩 스타일 가이드\n\n> **에픽**: 셸 및 CMake 코딩 스타일 가이드 개발\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 셸 스크립트의 코딩 표준을 정의하는 포괄적인 문서를 작성합니다.\n- **근거**: 셸 스크립트 품질에 대한 단일 진실 공급원(single source of truth)을 확립하여, 프로젝트 내의 모든 스크립트가 일관성 있고, 가독성이 높으며, 견고하고, 유지보수하기 쉽도록 보장합니다. 이는 협업을 개선하고 오류를 줄이기 위해 개발 표준을 공식화하려는 프로젝트의 핵심 목표를 직접적으로 지원합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: 셸 스크립트의 원칙, 이름 규칙, 모범 사례를 요약한 `coding_styles.md` 파일.\n- **명세**: 결과물은 다음 섹션을 반드시 포함해야 하는 마크다운 문서입니다.\n - `핵심 원칙`: 규칙의 철학적 기반을 정의합니다(예: 견고함, 자체 문서화).\n - `형식`: 이름 규칙 표를 포함하여, 구체적이고 강제할 수 있는 규칙을 담습니다.\n - `스타일 규칙`: 고품질 스크립트 로직 작성을 위한 모범 사례 가이드라인을 제공합니다.\n - 모든 규칙에는 근거와 설명적인 코드 예시(좋은 예 vs. 나쁜 예)가 함께 제공되어야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── guidelines/\n# └── shell_script/\n# └── coding_styles.md <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 개발자가 스크립트 작성 과정에서 스타일 가이드를 어떻게 활용하는지 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n A[개발자가 새 셸 스크립트를 작성하거나
기존 스크립트를 수정하기 시작] --> B{\"'guidelines/shell_script/coding_styles.md' 참고\"};\n B --> C[\"원칙 적용 (예: 'set -euo pipefail')\"];\n B --> D[\"이름 규칙 준수 (예: 함수에 'lower_snake_case' 사용)\"];\n B --> E[\"모범 사례 구현 (예: 변수를 따옴표로 묶기)\"];\n subgraph \"스크립트 작성\"\n direction LR\n C --> F;\n D --> F[코드 구현];\n E --> F;\n end\n F --> G[스크립트가 프로젝트 표준에 맞춰 완료됨];\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완수해야 합니다. 이것은 상위 수준의 체크리스트이며, 각 항목에 대한 상세 구현은 3절에 있습니다.\n\n- [ ] 견고함, 자체 문서화와 같은 핵심 원칙 정의.\n- [ ] 변수와 함수에 대한 이름 규칙 표.\n- [ ] shebang과 들여쓰기에 대한 형식 규칙.\n- [ ] 오류 검사 및 변수 따옴표 사용에 대한 모범 사례 규칙.\n- [ ] 명확한 좋은/나쁜 코드 예시 포함.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 리포지토리\n- **관련 주요 구성 요소**:\n - **언어 가이드라인**: 이 작업은 이 구성 요소 내에 새로운 문서를 직접 생성합니다. 이는 셸 스크립트 언어에 대한 프로젝트 목표의 구체적인 구현체 역할을 합니다.\n - **엔지니어링 원칙**: 이 작업에서 정의된 규칙들은 프로젝트의 상위 수준의, 언어에 구애받지 않는 원칙(예: 가독성, 명확성, 일관성)에서 파생되어야 하며, 이와 일치해야 합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `guidelines/shell_script/coding_styles.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부적인 `조치`로 나뉩니다. 각 `조치`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 견고함, 자체 문서화와 같은 핵심 원칙 정의\n\n#### 1. 핵심 원칙 섹션 추가\n\n이 조치는 전체 가이드의 기본 철학을 확립합니다. 상위 수준의 원칙을 먼저 정의함으로써, 뒤따르는 구체적인 규칙들 이면의 \"이유\"를 제공하여 개발자들이 법의 조문뿐만 아니라 그 의도를 이해하도록 합니다. 이 섹션에는 안전 실패(fail-safe) 실행 및 자체 문서화 코드 작성에 대한 원칙이 포함될 것입니다. 새 파일을 만들고 초기 개요, 목차, 핵심 원칙 섹션을 추가합니다.\n\n**파일**: `guidelines/shell_script/coding_styles.md`\n\n```markdown\n# 셸 스크립트 코딩 스타일 규칙\n\n버전 v1.0 생성일 2025-06-26 담당자 @movingChurch\n\n---\n\n## 0. 개요\n\n- **목적** 프로젝트 내 셸 스크립트의 일관성과 가독성을 보장하기 위함.\n- **범위** 이 리포지토리의 모든 셸 스크립트 (`*.sh`).\n- **대상** 프로젝트에 기여하는 모든 개발자.\n\n---\n\n## 1. 목차\n\n1. [핵심 원칙](#2-핵심-원칙)\n2. [형식](#3-형식)\n3. [스타일 규칙](#4-스타일-규칙)\n\n## 2. 핵심 원칙\n\n### 원칙 1: 견고하고 안전한(fail-safe) 스크립트 작성\n\n- **범위** 모든 스크립트.\n- **이유** 암묵적인 오류를 방지하고 실패 시 스크립트가 즉시 종료되도록 하여\n 신뢰성을 높이고 디버깅을 단순화하기 위함.\n\n### 원칙 2: 자체적으로 설명되는(Self-Documenting) 코드 작성\n\n- **범위** 모든 변수, 함수, 타겟.\n- **이유** 명확하고 서술적인 이름은 설명 주석의 필요성을 줄여 빌드 로직을\n 더 쉽게 이해하고 유지보수할 수 있도록 만듦.\n\n### 원칙 3: 약어 사용 금지\n\n- **범위** 모든 식별자 (변수, 함수, 타겟 등).\n- **이유** 전체 단어를 사용하면 명확성이 보장되어 코드를 처음 접하는 사람도\n 그 의도를 쉽게 파악할 수 있음.\n\n### 원칙 4: 의미가 명확한 이름 사용\n\n- **범위** 모든 식별자.\n- **이유** 이름은 해당 요소의 목적이나 내용을 명확하게 설명해야 함. 이는 코드의\n 역할을 반영하고 빌드 프로세스를 이해하는 데 도움을 줌.\n\n---\n```\n\n---\n\n### 단계 2: 변수와 함수에 대한 이름 규칙 표\n\n#### 1. 이름 규칙 표 추가\n\n이 조치는 모든 이름 규칙에 대한 빠른 참조 표를 추가합니다. 이를 \"형식\" 섹션에 배치함으로써 기계적으로 확인하고 강제할 수 있는 규칙으로 구분합니다. 이것은 개발자에게 다양한 코드 요소의 이름을 지정하기 위한 명확하고 파싱하기 쉬운 가이드를 제공하며, 코드베이스 전반에 걸쳐 일관성을 유지하는 데 중요합니다.\n\n**파일**: `guidelines/shell_script/coding_styles.md`\n\n```markdown\n...\n## 3. 형식\n\n> **설명** 이름 지정, 들여쓰기, 줄 길이 등과 같이 **린터/포매터로 100% 강제할 수\n> 있는 규칙**을 포함합니다.\n\n### 3.1 이름 규칙\n\n| 코드 요소 | 이름 규칙 스타일 | 예시 |\n| ------------------------ | -------------------- | ------------------------- |\n| 전역/환경 변수 | `UPPER_SNAKE_CASE` | `SCRIPT_DIR`, `API_KEY` |\n| 지역 변수 | `lower_snake_case` | `local user_name` |\n| 함수 | `lower_snake_case` | `install_package()` |\n| 파일 이름 | `lower_snake_case` | `install_dependencies.sh` |\n\n...\n```\n\n---\n\n### 단계 3: shebang과 들여쓰기에 대한 형식 규칙\n\n#### 1. Shebang 형식 규칙 추가\n\n이 조치는 shebang에 대한 요구사항을 성문화합니다. 이것은 스크립트의 이식성과 신뢰성을 위한 중요한 형식 규칙으로, 인터프리터를 명시적으로 선언하고 스크립트가 잘못된 셸에 의해 실행되는 것을 방지합니다. 이 조치는 명확한 좋은/나쁜 예시와 함께 규칙을 추가합니다. 참고: 작업에서는 들여쓰기를 언급했지만, 원본 자료에는 특정 규칙이 정의되어 있지 않으므로 shebang 규칙만 추가됩니다.\n\n**파일**: `guidelines/shell_script/coding_styles.md`\n\n```markdown\n...\n### 3.2 형식 규칙\n\n#### 형식 규칙 1: 항상 shebang 포함\n\n- **범위** 모든 실행 가능한 스크립트 파일.\n- **이유** 스크립트의 인터프리터를 명시적으로 선언하여 의도한 셸 환경에서\n 실행되도록 보장함.\n\n```bash\n# 좋은 예\n#!/bin/bash\n\n# 나쁜 예\n# (shebang 없음)\n```\n\n⸻\n\n## 4. 스타일 규칙\n\n...\n\n```\n\n---\n\n### 단계 4: 오류 검사 및 변수 따옴표 사용에 대한 모범 사례 규칙\n\n#### 1. 스크립트 작성을 위한 모범 사례 추가\n\n이 조치는 스크립트의 견고성과 최신 구문에 초점을 맞춘 일련의 규칙을 도입합니다. 암묵적인 실패를 방지하기 위한 엄격한 오류 검사 활성화(`set -euo pipefail`)와 단어 분리 및 globbing 버그를 피하기 위한 변수 따옴표 사용 의무화를 다룹니다. 또한 가독성 및 중첩 기능이 더 나은 최신 `$(...)` 명령어 치환 사용을 포함합니다. 이 규칙들은 전문적이고 프로덕션 품질의 셸 스크립트를 작성하는 데 기본이 됩니다.\n\n**파일**: `guidelines/shell_script/coding_styles.md`\n\n```markdown\n...\n## 4. 스타일 규칙\n\n### 4.1 스크립트 작성 모범 사례\n\n설명: 견고하고 가독성 있는 셸 스크립트 코드 작성을 위한 가이드라인입니다.\n\n#### 모범 사례 규칙 1: 엄격한 오류 검사 활성화\n\n- **범위** 모든 스크립트의 시작 부분.\n- **이유** 오류 발생 시 종료(`-e`), 설정되지 않은 변수를 오류로 처리(`-u`),\n 파이프라인의 أي 명령어라도 실패하면 실패 처리(`-o pipefail`)하여 스크립트를 더\n 견고하게 만듦.\n\n```bash\n# 좋은 예\nset -euo pipefail\n# 또는\nset -o errexit -o nounset -o pipefail\n\n# 나쁜 예\n# (안전 옵션 없음)\n```\n\n#### 모범 사례 규칙 2: 항상 변수를 따옴표로 묶기\n\n- **범위** 모든 변수 확장.\n- **이유** 변수에 공백이나 특수 문자가 포함될 경우 단어 분리(word splitting) 및\n globbing으로 인한 예기치 않은 동작을 방지함.\n\n```bash\n# 좋은 예\nrm \"$filename\"\n\n# 나쁜 예\nrm $filename\n```\n\n#### 모범 사례 규칙 3: 최신 명령어 치환 사용\n\n- **범위** 모든 명령어 치환.\n- **이유** `$(...)` 구문은 가독성이 더 높고, 기존의 백틱(backticks)과 달리\n 깔끔하게 중첩될 수 있음.\n\n```bash\n# 좋은 예\nlocal current_date=$(date +%F)\n\n# 나쁜 예\nlocal current_date=`date +%F`\n```\n\n...\n\n```\n\n---\n\n### 단계 5: 명확한 좋은/나쁜 코드 예시 포함\n\n#### 1. 명확성을 위한 이름 규칙 및 예제 추가\n\n이 조치는 \"명확성을 위한 이름 규칙\"에 대한 전용 섹션을 추가하여 명확한 예시에 대한 요구사항을 충족시킵니다. 이름 지정의 구문(표)을 넘어 서술적이고 모호하지 않은 이름을 선택하는 의미론으로 나아갑니다. 함수에 `verb_noun`을 사용하고 변수에 일반적인 용어를 피하는 것과 같은 명시적인 규칙을 제공하며, 각 규칙은 명확한 \"좋은 예\" vs. \"나쁜 예\" 코드 스니펫으로 뒷받침됩니다. 이는 자체 문서화 코드 작성이라는 핵심 원칙을 직접적으로 강화합니다.\n\n**파일**: `guidelines/shell_script/coding_styles.md`\n\n```markdown\n...\n### 4.2 명확성을 위한 이름 규칙\n\n설명: 변수와 함수에 대해 명확하고 유지보수하기 쉬운 이름을 선택하는 규칙으로,\n자체 문서화 코드라는 핵심 원칙을 반영합니다.\n\n#### 명확성을 위한 이름 규칙 1: 설명적인 이름을 사용하고 약어 피하기\n\n- **범위** 모든 변수와 함수.\n- **이유** 명확하고 완전한 단어로 된 이름은 코드를 자체 문서화하여 주석의\n 필요성을 줄이고 새로운 기여자가 이해하기 쉽게 만듭니다. 이는 약어를 사용하지\n 않고 자체 문서화 코드를 작성하는 원칙과 일치합니다.\n\n```bash\n# 좋은 예: 설명적이고 명확함\nfunction calculate_disk_usage() {\n local target_directory=\"$1\"\n # ...\n}\n\n# 나쁜 예: 약어를 사용하고 모호함\nfunction get_du() {\n local dir=\"$1\"\n # ...\n}\n```\n\n#### 명확성을 위한 이름 규칙 2: 함수 이름은 verb_noun 형식 따르기\n\n- **범위** 모든 함수.\n- **이유** 일관된 `verb_noun` 구조는 함수가 어떤 객체에 대해 어떤 동작을\n 수행하는지 명확하게 전달합니다.\n\n```bash\n# 좋은 예\nfunction validate_input() { ... }\nfunction create_temporary_file() { ... }\n\n# 나쁜 예\nfunction input_validation() { ... } # 명사 기반 이름은 불명확함\nfunction temp_file() { ... } # 동작을 설명하는 동사가 없음\n```\n\n#### 명확성을 위한 이름 규칙 3: 구체적이고 모호하지 않은 변수 이름 선택\n\n- **범위** 모든 변수.\n- **이유** 변수 이름은 내용이나 목적을 정확하게 반영해야 합니다. 'data', 'temp',\n 'item'과 같은 모호한 이름은 독자가 컨텍스트를 찾아보게 만들어 가독성을\n 떨어뜨립니다.\n\n```bash\n# 좋은 예\nlocal user_list_file=\"users.txt\"\nlocal temporary_file=$(mktemp)\n\n# 나쁜 예\nlocal data_file=\"users.txt\" # 'data'는 너무 일반적임\nlocal tmp=$(mktemp) # 'tmp'는 흔하지만 불명확한 약어임\n```\n\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 주된 검증은 생성된 마크다운 파일이 잘 구성되었고 프로젝트 자체의 마크다운 표준을 준수하는지 확인하는 것입니다. 이를 위해 프로젝트의 자동화된 도구를 사용할 수 있습니다.\n\n```bash\n# 1. 포매터가 설치되어 있는지 확인 (필요시 설치 스크립트 실행)\n# ./scripts/installers/install_formatters_macos.sh 또는 ./scripts/installers/install_formatters_ubuntu.sh\n\n# 2. 새 파일에 포매터/린터 실행\n# 프로젝트의 마스터 실행 스크립트가 이를 처리합니다.\n# (참고: 에픽 10에 따라 이 경로에 향후 스크립트가 존재한다고 가정)\nnpm exec prettier -- --write guidelines/shell_script/coding_styles.md\nnpm exec markdownlint-cli -- guidelines/shell_script/coding_styles.md\n```\n\n### 4.2. 예상 결과\n\n- 검증 명령어는 오류 없이 실행되어야 합니다. `prettier`는 파일을 다시 포맷할 수 있으며, `markdownlint`는 문제를 보고하지 않아야 합니다. 최종적으로 렌더링된 마크다운 파일은 브라우저나 IDE 미리보기에서 명확하게 읽을 수 있어야 합니다.\n\n```\n# Prettier 출력 (예시)\nguidelines/shell_script/coding_styles.md 123ms\n\n# markdownlint 출력 (성공 시)\n(출력 없음)\n```","원칙, 이름 규칙, 모범 사례를 개괄하는 셸 스크립트용 `coding_styles.md` 파일",[282,285,287,289,291],{"_24":283,"_83":39,"_84":284,"_85":61},"견고성, 자체 문서화와 같은 핵심 원칙 정의",11,{"_24":286,"_83":39,"_84":284,"_85":88},"변수 및 함수에 대한 이름 규칙 표",{"_24":288,"_83":39,"_84":284,"_85":91},"shebang 및 들여쓰기에 대한 서식 규칙",{"_24":290,"_83":39,"_84":284,"_85":94},"오류 확인 및 변수 인용에 대한 모범 사례 규칙",{"_24":292,"_83":39,"_84":284,"_85":97},"명확한 좋고 나쁜 코드 예제 포함","셸 스크립트의 코딩 표준을 정의하는 포괄적인 문서를 작성",{"_22":295,"_24":296,"_75":297,"_77":298,"_79":299,"_51":311,"_42":99},"task-1751363657772","CMake 코딩 스타일 가이드","# 작업: CMake 코딩 스타일 가이드\n\n> **에픽**: 셸 및 CMake 코딩 스타일 가이드 개발\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: CMake 스크립트의 코딩 표준을 수립하는 가이드를 작성합니다.\n- **근거**: 프로젝트 내 모든 `CMakeLists.txt` 및 `*.cmake` 파일에 일관되고, 현대적이며, 가독성 좋은 스타일을 공식화하고 강제하기 위함입니다. 이는 유지보수 가능한 지식 기반을 구축하려는 핵심 프로젝트 목표를 지원하며, 빌드 시스템 구성을 공식적으로 문서화된 자산으로 취급함으로써 \"구조화된 문서 저장소\" 아키텍처와 일치합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: 현대적인 타겟 중심(target-centric) 방식을 상세히 기술한 CMake용 `coding_styles.md` 파일.\n- **명세**: 최종 마크다운 문서는 다음 구조화된 섹션을 포함해야 합니다:\n - 핵심 원칙 (타겟 중심 설계, 자체 문서화 코드).\n - 명령어, 변수, 타겟, 함수, 속성에 대한 이름 규칙 표.\n - 서식 규칙 (명령어 대소문자, 들여쓰기, 줄 길이).\n - 스타일 규칙 (명령어 인수 구조, 가시성 키워드 사용법).\n - 파일 구조 및 변수 범위 가이드라인.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── guidelines/\n# └── cpp/\n# └── cmake/\n# └── coding_styles.md <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 개발자가 프로젝트의 개발 수명 주기 내에서 CMake 스타일 가이드와 상호 작용하는 방식을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"개발 워크플로\"\n Dev[\"개발자\"] --> ConsultGuide[\"guidelines/cpp/cmake/coding_styles.md
참조\"];\n ConsultGuide --> AuthorCode[\"CMakeLists.txt
작성/수정\"];\n AuthorCode --> LocalValidation[\"로컬 스크립트 실행
(향후 CMake Linter)\"];\n LocalValidation --> Commit[\"변경 사항 커밋\"];\n end\n\n subgraph \"자동화된 검증\"\n Commit --> TriggerCI[\"CI 파이프라인 트리거\"];\n TriggerCI --> ValidateMarkdown[\"CI에서
coding_styles.md 서식 검증\"];\n ValidateMarkdown --> ReportStatus[\"성공/실패 보고\"];\n end\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완수해야 합니다. 이것은 개략적인 체크리스트이며, 각 항목에 대한 상세 구현은 3장에 있습니다.\n\n- [ ] 핵심 원칙 정의, 타겟 중심 명령어 강조.\n- [ ] 명령어, 변수, 타겟에 대한 이름 규칙 표.\n- [ ] 명령어 대소문자 및 들여쓰기에 대한 서식 규칙.\n- [ ] 명령어 구조 및 가시성 키워드에 대한 스타일 규칙.\n- [ ] 파일 구조 및 변수 범위 가이드라인.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 저장소\n- **관련 주요 구성 요소**:\n - **언어 가이드라인**: 이 작업은 이 구성 요소 내에 새 문서를 직접 생성합니다. CMake에 대한 특정 규칙을 성문화합니다.\n - **엔지니어링 원칙**: CMake 가이드는 가독성, 일관성, 명확한 이름 지정과 같이 이 구성 요소에 정의된 상위 수준의 원칙을 구현합니다.\n - **자동화 도구**: 이 작업이 자동화를 구현하지는 않지만, 생성된 가이드는 향후 이 구성 요소 내의 CMake 린터 또는 포맷터 구성에 대한 명세 역할을 할 것입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `guidelines/cpp/cmake/coding_styles.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `Step`은 **인수 조건**의 항목에 해당합니다. 각 `Step`은 세분화된 `Action`들로 나뉩니다. 각 `Action`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 핵심 원칙 정의, 타겟 중심 명령어 강조\n\n#### 1. 헤더 및 핵심 원칙 섹션 추가\n\n표준 헤더, 목차, \"핵심 원칙\" 섹션을 포함한 초기 파일 구조를 생성합니다. 이 섹션은 CMake 스크립트 작성을 위한 상위 수준의 철학을 정립하며, 모듈성과 명확성을 개선하기 위한 타겟 중심 명령어와 같은 현대적인 방식과 유지보수성 향상을 위한 자체 문서화 코드 원칙에 중점을 둡니다.\n\n**파일**: `guidelines/cpp/cmake/coding_styles.md`\n\n```markdown\n# CMake 코딩 스타일 규칙\n\n버전 v1.0 생성일 2025-06-26 담당자 @movingChurch\n\n---\n\n## 0. 개요\n\n- **목적** 프로젝트 전반에 걸쳐 CMake 스크립트의 일관성, 가독성, 유지보수성을 보장합니다.\n- **범위** 이 리포지토리 내의 모든 `CMakeLists.txt` 및 `*.cmake` 파일.\n- **대상** 이 프로젝트에 기여하는 모든 개발자.\n\n---\n\n## 1. 목차\n\n1. [핵심 원칙](#2-core-principles)\n2. [서식](#3-format)\n3. [스타일 규칙](#4-style-rules)\n\n---\n\n## 2. 핵심 원칙\n\n### 원칙 1 현대적인 타겟 중심(Target-Centric) CMake를 선호합니다\n\n- **범위** 모든 타겟 정의 및 속성 수정.\n- **근거** `target_*` 계열 명령어를 사용하면 속성을 필요한 타겟에 명시적으로 연결하여 모듈성, 캡슐화, 명확성을 향상시킵니다. 이를 통해 구식의 디렉토리 기반 명령어에서 흔히 발생하던 부작용과 숨겨진 의존성을 피할 수 있습니다.\n\n### 원칙 2 자체적으로 문서화되는 코드를 작성합니다\n\n- **범위** 모든 변수, 함수, 타겟.\n- **근거** 명확하고 서술적인 이름은 설명 주석의 필요성을 줄여 빌드 로직을 더 쉽게 이해하고 유지보수할 수 있게 합니다.\n\n### 원칙 3 약어를 사용하지 않습니다\n\n- **범위** 모든 식별자(변수, 함수, 타겟 등).\n- **근거** 단어 전체를 사용하면 명확성이 보장되어 코드를 처음 보는 사람도 그 의도를 쉽게 파악할 수 있습니다.\n\n### 원칙 4 의미적으로 명확한 이름을 사용합니다\n\n- **범위** 모든 식별자.\n- **근거** 이름은 해당 요소의 목적이나 내용을 명확하게 설명해야 합니다. 이는 코드의 역할을 반영하고 빌드 프로세스를 이해하는 데 도움이 됩니다.\n```\n\n---\n\n### 단계 2: 명령어, 변수, 타겟에 대한 이름 규칙 표\n\n#### 1. 이름 규칙 표 추가\n\n\"서식\" 섹션을 정의하고 \"이름 규칙\" 하위 섹션을 추가합니다. 이는 모든 식별자 이름 스타일에 대한 단일하고 권위 있는 참조를 명확한 표 형식으로 제공합니다. 이 규칙들을 강제하는 것은 1단계에서 설명한 자체 문서화 코드 원칙을 달성하는 데 매우 중요합니다.\n\n**파일**: `guidelines/cpp/cmake/coding_styles.md`\n\n```markdown\n...\n---\n\n## 3. 서식\n\n> **설명** 포맷터와 린터로 강제할 수 있는 규칙들을 포함하여, 일관된 모양과 느낌을 보장합니다.\n\n### 3.1 이름 규칙\n\n| 코드 요소 | 이름 스타일 | 예시 |\n| :------------- | :---------------------------- | :------------------------------ |\n| 명령어 | `lowercase` | `project()`, `add_executable()` |\n| 변수 (지역) | `lower_case_with_underscores` | `my_local_variable` |\n| 변수 (전역) | `UPPER_CASE_WITH_UNDERSCORES` | `MY_PROJECT_VERSION` |\n| 함수/매크로 | `lower_case_with_underscores` | `my_custom_function()` |\n| 타겟 | `PascalCase` | `MyExecutable`, `MyLibrary` |\n| 속성 | `UPPERCASE` | `CXX_STANDARD` |\n...\n```\n\n---\n\n### 단계 3: 명령어 대소문자 및 들여쓰기에 대한 서식 규칙\n\n#### 1. 서식 규칙 추가\n\n\"서식 규칙\" 하위 섹션을 추가합니다. 이 섹션은 명령어 대소문자, 들여쓰기, 줄 길이에 대한 객관적이고 강제 가능한 규칙들을 성문화합니다. 이 규칙들은 모든 CMake 파일에 걸쳐 일관된 시각적 구조를 보장하여, 코드를 훑어볼 때 가독성을 크게 향상시키고 인지 부하를 줄여줍니다.\n\n**파일**: `guidelines/cpp/cmake/coding_styles.md`\n\n```markdown\n...\n### 3.2 서식 규칙\n\n#### 서식 규칙 1 모든 명령어 이름은 소문자를 사용합니다\n\n- **범위** 모든 CMake 명령어.\n- **근거** CMake 명령어는 대소문자를 구분하지 않지만, 일관된 스타일은 가독성을 향상시킵니다.\n\n```cmake\n# 좋음\nproject(MyProject)\nadd_executable(MyTarget main.cpp)\n\n# 나쁨\nPROJECT(MyProject)\nAdd_Executable(MyTarget main.cpp)\n```\n\n#### 서식 규칙 2 들여쓰기는 2칸 공백을 사용합니다\n\n- **범위** 모든 들여쓰기 블록.\n- **근거** 탭 너비 설정에 의존하지 않고 일관된 들여쓰기를 보장합니다.\n\n```cmake\n# 좋음\nif(CONDITION)\n message(\"2칸 공백으로 들여쓰기 함\")\nendif()\n\n# 나쁨\nif(CONDITION)\n message(\"4칸 공백으로 들여쓰기 함\")\nendif()\n```\n\n#### 서식 규칙 3 줄 길이는 100자 미만으로 유지합니다\n\n- **범위** 모든 코드 라인.\n- **근거** 특히 분할 화면이나 터미널 뷰에서 가독성을 향상시킵니다.\n...\n\n```\n\n---\n\n### 단계 4: 명령어 구조 및 가시성 키워드에 대한 스타일 규칙\n\n#### 1. 명령어 사용 스타일 규칙 추가\n\n\"스타일 규칙\" 및 \"명령어 사용\" 섹션을 생성합니다. 이 규칙들은 여러 인수를 갖는 호출을 어떻게 포맷할지, 그리고 가시성 키워드(`PUBLIC`/`PRIVATE`/`INTERFACE`)의 의무적 사용과 같은 명령어의 의미론적 구조를 규정합니다. 이는 의존성과 그 범위를 명시적이고 모호하지 않게 만들어 타겟 중심 설계의 핵심 원칙을 강제합니다.\n\n**파일**: `guidelines/cpp/cmake/coding_styles.md`\n\n```markdown\n...\n---\n\n## 4. 스타일 규칙\n\n### 4.1 명령어 사용\n\n#### 명령어 사용 규칙 1 여러 인수를 갖는 명령어는 가독성을 위해 구조화합니다\n\n- **범위** `target_link_libraries`와 같이 여러 인수를 갖는 명령어.\n- **근거** 각 인수를 새 줄에 배치하면 의존성과 속성을 쉽게 훑어볼 수 있습니다.\n\n```cmake\n# 좋음\ntarget_link_libraries(MyTarget\n PUBLIC\n MyLibrary1\n PRIVATE\n MyLibrary2\n)\n\n# 나쁨\ntarget_link_libraries(MyTarget PUBLIC MyLibrary1 PRIVATE MyLibrary2)\n```\n\n#### 명령어 사용 규칙 2 항상 `PUBLIC`/`PRIVATE`/`INTERFACE`를 명시합니다\n\n- **범위** 가시성 키워드를 허용하는 모든 `target_*` 계열 명령어.\n- **근거** 의존성과 속성의 범위를 명시적으로 지정하면 모호성을 방지하고 올바르게 전파되도록 보장합니다.\n\n```cmake\n# 좋음\ntarget_include_directories(MyLibrary\n INTERFACE\n \"${CMAKE_CURRENT_SOURCE_DIR}/include\"\n)\n\n# 나쁨 (그리고 의도치 않게 PUBLIC으로 기본 설정될 수 있음)\ntarget_include_directories(MyLibrary\n \"${CMAKE_CURRENT_SOURCE_DIR}/include\"\n)\n```\n\n...\n\n```\n\n---\n\n### 단계 5: 파일 구조 및 변수 범위 가이드라인\n\n#### 1. 파일 구조 및 변수 범위 규칙 추가\n\n파일 구조와 변수 사용법을 다루는 마지막 섹션들을 추가합니다. 파일 구조 규칙은 `CMakeLists.txt` 파일에 대한 예측 가능한 레이아웃을 제공하여 탐색을 더 쉽게 만듭니다. 변수 범위 규칙은 전역 상태 사용을 지양함으로써 현대적인 CMake 방식을 강화하며, 이는 부작용과 숨겨진 의존성을 최소화하여 빌드 시스템의 견고성을 향상시킵니다.\n\n**파일**: `guidelines/cpp/cmake/coding_styles.md`\n\n```markdown\n...\n### 4.2 파일 구조\n\n#### 파일 구조 규칙 1 `CMakeLists.txt`를 논리적인 섹션으로 구성합니다\n\n- **범위** 모든 `CMakeLists.txt` 파일.\n- **근거** 일관된 구조는 파일을 예측 가능하게 만들고 탐색을 더 쉽게 합니다.\n\n```cmake\n# 좋음\ncmake_minimum_required(VERSION 3.15)\nproject(MyProject LANGUAGES CXX)\n\n# --- 옵션\noption(BUILD_TESTS \"테스트 빌드\" ON)\n\n# --- 의존성\nfind_package(fmt REQUIRED)\n\n# --- 타겟\nadd_library(MyLibrary my_library.cpp)\n\n# --- 타겟 속성\ntarget_link_libraries(MyLibrary PUBLIC fmt::fmt)\n\n# --- 테스팅\nif(BUILD_TESTS)\n # ...\nendif()\n```\n\n### 4.3 변수\n\n#### 변수 규칙 1 전역 변수 사용을 최소화합니다\n\n- **범위** 변수 선언.\n- **근거** 전역 변수는 숨겨진 의존성을 만듭니다. 함수 인자를 통해 변수를 전달하거나 타겟 속성을 사용하는 것을 선호합니다.\n\n```cmake\n# 좋음\n# 속성은 타겟과 함께 캡슐화됩니다\ntarget_compile_definitions(MyTarget PRIVATE MY_DEFINITION)\n\n# 나쁨\n# 이것은 디렉토리 내의 모든 후속 타겟에 영향을 줍니다\nadd_compile_definitions(MY_DEFINITION)\n```\n\n...\n\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n1. **파일 생성 확인**: `guidelines/cpp/cmake/coding_styles.md` 파일이 올바른 디렉토리에 생성되었는지 확인합니다.\n2. **수동 내용 검토**: 생성된 문서를 읽고 인수 조건(핵심 원칙, 이름 규칙 표, 서식 규칙, 스타일 규칙, 파일 구조)에 명시된 모든 섹션이 존재하며 구현 명세와 일치하는지 확인합니다.\n3. **프로젝트 포맷터 실행**: 프로젝트의 포맷팅 및 린팅 스크립트를 실행하여 새 마크다운 파일이 리포지토리 자체 표준을 준수하는지 확인합니다.\n\n```bash\n# 프로젝트 루트에서 마스터 포맷터 스크립트를 실행합니다.\n# 이 스크립트는 새 파일에 Prettier와 markdownlint를 실행합니다.\n./scripts/executables/run_formatters.sh\n```\n\n### 4.2. 예상 결과\n\n- `run_formatters.sh` 스크립트가 `guidelines/cpp/cmake/coding_styles.md`에 대한 포맷팅 또는 린팅 오류 없이 완료됩니다.\n- 스크립트 출력은 확인된 모든 파일이 올바르게 포맷되었음을 나타내야 합니다. 출력 예시:\n\n```\n[INFO] Prettier 포맷터를 실행 중입니다...\n서식을 확인 중입니다...\n모든 파일의 서식이 올바릅니다.\n[INFO] Prettier 검사를 통과했습니다.\n[INFO] markdownlint를 실행 중입니다...\n[INFO] markdownlint 검사를 통과했습니다.\n[INFO] 모든 포맷터와 린터 검사를 통과했습니다.\n```","현대적이고 타겟 중심적인 관행을 상세히 기술하는 CMake용 `coding_styles.md` 파일",[300,303,305,307,309],{"_24":301,"_83":39,"_84":302,"_85":61},"타겟 중심 명령어를 강조하는 핵심 원칙 정의",12,{"_24":304,"_83":39,"_84":302,"_85":88},"명령어, 변수, 타겟에 대한 이름 규칙 표",{"_24":306,"_83":39,"_84":302,"_85":91},"명령어 대소문자 및 들여쓰기에 대한 서식 규칙",{"_24":308,"_83":39,"_84":302,"_85":94},"명령어 구조 및 가시성 키워드에 대한 스타일 규칙",{"_24":310,"_83":39,"_84":302,"_85":97},"파일 구조 및 변수 범위에 대한 가이드라인","CMake 스크립트의 코딩 표준을 수립하는 가이드를 작성",{"_22":313,"_24":314,"_75":315,"_77":316,"_79":317,"_51":329,"_42":99},"task-1751363700634","마크다운 코딩 스타일 가이드","# 작업: 마크다운 코딩 스타일 가이드\n\n> **에픽**: 마크다운 및 Mermaid 스타일 가이드 개발\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 일관성 있고 유지보수 가능한 마크다운 문서를 작성하기 위한 스타일 가이드를 제작합니다.\n- **근거**: 프로젝트 내 마크다운 문법과 스타일에 대한 단일 진실 공급원(single source of truth)을 구축하기 위함입니다. 이를 통해 일관된 표준을 공식화하여 모든 문서의 가독성과 유지보수성을 보장하고, 설정된 자동화 도구(Prettier, markdownlint)와 원활하게 통합되도록 합니다. 이는 개발 가이드라인을 공식화하려는 프로젝트의 핵심 목표와 직접적으로 일치합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: Prettier와 markdownlint로 강제되는 마크다운용 `coding_styles.md` 파일.\n- **명세**:\n - **파일 이름**: `coding_styles.md`\n - **위치**: `guidelines/markdown/`\n - **내용**: 문서는 두 가지 유형으로 분류된 규칙을 정의해야 합니다:\n - **포맷 규칙**: 린터에 의해 자동으로 강제될 수 있는 규칙(예: 줄 길이, 헤더 스타일, 목록 형식). 각 규칙은 이를 강제하는 특정 린터나 설정을 참조해야 합니다.\n - **스타일 규칙**: 명확성을 향상시키지만 수동 검토가 필요할 수 있는 모범 사례(예: 서술적인 링크 텍스트, 한 줄에 한 문장).\n - **예시**: 모든 규칙에는 마크다운 코드 블록에 `GOOD` 및 `BAD` 사용 예시가 함께 제공되어야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── guidelines/\n# └── markdown/\n# └── coding_styles.md <-- 신규\n```\n\n- **프로세스 흐름도**\n 생성된 가이드는 개발자를 위한 참조 자료이자 자동화 도구를 위한 명세 역할을 합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"개발 워크플로\"\n Dev[\"개발자\"]\n Guide[\"guidelines/markdown/coding_styles.md\"]\n Formatter[\"로컬 포맷터
(Prettier/markdownlint)\"]\n NewDoc[\"신규/수정된 .md 파일\"]\n end\n\n Dev -- \"참조\" --> Guide;\n Dev -- \"작성\" --> NewDoc;\n Dev -- \"포맷터 실행\" --> NewDoc;\n Formatter -- \"규칙 적용\" --> Guide;\n Formatter -- \"포맷/린트 실행\" --> NewDoc;\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] 핵심 원칙 문서화: 가독성, 일관성, 자동화.\n- [ ] 린터 설정과 연결된 포맷 규칙 (예: 줄 길이, 헤더, 목록).\n- [ ] 코드 블록 및 강조에 대한 규칙 명세.\n- [ ] 서술적인 링크 텍스트 및 alt 텍스트와 같은 콘텐츠 모범 사례.\n- [ ] 각 규칙에 대한 명확한 good/bad 코드 예시.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 리포지토리\n- **관련된 주요 구성 요소**:\n - **언어 가이드라인**: 이 작업은 이 구성 요소 내의 핵심 문서를 생성하는 것을 포함합니다. `coding_styles.md` 파일은 리포지토리의 모든 마크다운 문서에 대한 기초 가이드라인이 될 것입니다.\n - **자동화 도구**: 가이드라인은 프로젝트에 설정된 포맷터(Prettier) 및 린터(markdownlint)와 직접적으로 일치하도록 작성되어야 합니다. 문서화된 규칙은 `.prettierrc` 및 `.markdownlint.jsonc`의 설정을 반영해야 합니다.\n - **엔지니어링 원칙**: 이 가이드는 가독성과 일관성이라는 상위 수준의 원칙을 마크다운 언어에 대한 구체적이고 실행 가능한 규칙으로 성문화하여 구현합니다.\n\n### 2.2. 영향을 받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `guidelines/markdown/coding_styles.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 여러 세부 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 핵심 원칙 문서화: 가독성, 일관성, 자동화\n\n#### 1. 문서 구조 생성 및 핵심 원칙 정의\n\n이 액션은 개요, 목차, 그리고 모든 후속 규칙을 관장하는 핵심 원칙을 포함하여 스타일 가이드의 기초 구조를 수립합니다. 이러한 원칙들(가독성, 일관성, 자동화)은 프로젝트의 상위 수준 철학을 마크다운 작성의 지침 원칙으로 직접 변환합니다. 이 섹션은 규칙이 *왜* 존재하는지에 대한 맥락을 설정합니다.\n\n**파일**: `guidelines/markdown/coding_styles.md`\n\n```markdown\n# 마크다운 코딩 스타일 규칙\n\n버전 v1.1 생성일 2025-06-28 소유자 [@movingChurch]\n\n---\n\n## 0. 개요\n\n- **목적** 모든 프로젝트에서 일관되고, 읽기 쉽고, 유지보수 가능한 마크다운 문서를\n 보장하기 위함.\n- **범위** 리포지토리 내의 모든 마크다운(`.md`) 파일.\n- **대상** 모든 개발자 및 기여자.\n- **도구** 이 규칙들은 [Prettier](https://prettier.io/)와\n [markdownlint](https://github.com/DavidAnson/markdownlint)에 의해 자동으로\n 강제됩니다.\n\n---\n\n## 1. 목차\n\n1. [핵심 원칙](#2-핵심-원칙)\n2. [포맷](#3-포맷)\n3. [스타일 규칙](#4-스타일-규칙)\n\n---\n\n## 2. 핵심 원칙\n\n### 원칙 1 가독성 우선\n\n- **범위** 모든 마크다운 파일\n- **근거** 렌더링된 결과물과 원본 소스 코드 모두에서 사람이 읽기 쉬운 명확성을\n 우선시합니다.\n\n### 원칙 2 일관성이 핵심\n\n- **범위** 모든 마크다운 파일\n- **근거** 통일된 스타일은 인지 부하를 줄이고 문서 유지보수를 더 쉽게\n 만듭니다.\n\n### 원칙 3 모든 것을 자동화\n\n- **범위** 모든 마크다운 파일\n- **근거** 포맷터와 린터에 의존하여 스타일을 강제하고, 수동적인 노력과 논쟁을\n 최소화합니다.\n```\n\n---\n\n### 단계 2: 린터 설정과 연결된 포맷 규칙 (예: 줄 길이, 헤더, 목록)\n\n#### 1. 린터로 강제되는 포맷 규칙 문서화\n\n이 액션은 100% 자동화로 강제되는 규칙들을 위한 \"포맷\" 섹션을 추가합니다. 이 구분은 개발자들에게 어떤 규칙을 배워야 하고 어떤 규칙이 자동으로 처리되는지를 명확히 해주기 때문에 매우 중요합니다. 줄 길이, 헤더 스타일, 목록 형식에 대한 규칙은 문서 구조와 가독성의 기초가 됩니다. 각 규칙은 이를 강제하는 린터와 규칙 ID(예: MD003)를 명시하여 가이드와 도구 간의 직접적인 연결을 만듭니다.\n\n**파일**: `guidelines/markdown/coding_styles.md`\n\n```markdown\n...\n\n---\n\n## 3. 포맷\n\n> **설명** **린터/포맷터에 의해 100% 강제될 수 있는** 규칙을 포함합니다.\n> 이 규칙들은 포맷터(`npm run format`)를 실행하거나 린터에 의해 자동으로\n> 적용되거나 확인됩니다. 일반적으로 수동 조정은 필요하지 않습니다.\n\n### 3.1 포맷 규칙\n\n#### 포맷 규칙 1 줄은 80자를 초과해서는 안 됩니다\n\n- **범위** 모든 마크다운 파일\n- **근거** 다양한 화면 크기와 나란히 보는 diff에서 가독성을 향상시킵니다.\n `prettier` (`printWidth: 80`, `proseWrap: 'always'`)에 의해 강제됩니다.\n\n#### 포맷 규칙 2 ATX 스타일 헤더(`#`)를 사용합니다\n\n- **범위** 모든 마크다운 파일\n- **근거** 가장 일반적이고 가독성이 좋은 헤더 형식입니다. `markdownlint` (MD003)에\n 의해 강제됩니다.\n\n#### 포맷 규칙 3 문서당 최상위 H1 헤더는 하나만 있어야 합니다\n\n- **범위** 모든 마크다운 파일\n- **근거** 각 문서에 대해 명확하고 단일한 주제를 보장합니다. `markdownlint`\n (MD025)에 의해 강제됩니다.\n\n#### 포맷 규칙 4 헤더 레벨은 순차적으로 증가시켜야 합니다\n\n- **범위** 모든 마크다운 파일\n- **근거** 레벨을 건너뛰면 혼란스러운 문서 구조가 만들어집니다. `markdownlint`\n (MD001)에 의해 강제됩니다.\n\n#### 포맷 규칙 5 순서 없는 목록에는 하이픈(`-`)을 사용합니다\n\n- **범위** 모든 마크다운 파일\n- **근거** 단일하고 일관된 마커는 소스 코드의 가독성을 향상시키고 Prettier의\n 기본 동작과 일치합니다. `markdownlint` (MD004)에 의해 강제됩니다.\n\n#### 포맷 규칙 6 순서 있는 목록은 `1. 1. 1.` 또는 `1. 2. 3.` 스타일을 모두 사용할 수 있습니다\n\n- **범위** 모든 마크다운 파일\n- **근거** 목록 내에서 일관성을 유지하면서 유연성을 허용합니다. `markdownlint`\n (MD029)에 의해 강제됩니다.\n...\n```\n\n---\n\n### 단계 3: 코드 블록 및 강조에 대한 규칙 명세\n\n#### 1. 코드 블록 및 강조에 대한 규칙 문서화\n\n이 액션은 코드 표현 및 텍스트 강조에 대한 규칙을 추가합니다. 울타리 코드 블록에 언어 식별자를 지정하는 것은 구문 강조에 매우 중요하며, 이는 코드 가독성을 크게 향상시킵니다. 강조 구문(`_Italic_`, `**Bold**`)을 표준화하는 것은 \"일관성\" 원칙의 핵심 측면이며 Prettier의 기본 동작과 일치하여 자동화가 예상대로 작동하도록 보장합니다.\n\n**파일**: `guidelines/markdown/coding_styles.md`\n\n```markdown\n...\n#### 포맷 규칙 7 울타리 코드 블록을 사용하고 언어 식별자를 명시합니다\n\n- **범위** 모든 마크다운 파일\n- **근거** 구문 강조를 가능하게 하고 코드의 언어를 명확하게 합니다.\n `markdownlint` (MD046, MD048, MD040)에 의해 강제됩니다.\n\n#### 포맷 규칙 8 이탤릭체에는 단일 밑줄을, 굵은체에는 이중 별표를 사용합니다\n\n- **범위** 모든 마크다운 파일\n- **근거** 강조 표시에 일관된 스타일을 보장합니다. `markdownlint` (MD049, MD050)에\n 의해 강제됩니다.\n\n#### 포맷 규칙 9 공백과 개행을 올바르게 관리합니다\n\n- **범위** 모든 마크다운 파일\n- **근거** POSIX 준수를 보장하고, 보이지 않는 변경을 피하며, 공백을 깔끔하게\n 유지합니다. `prettier` 및 `markdownlint` (MD047, MD009, MD012)에 의해\n 강제됩니다.\n\n#### 포맷 규칙 10 원시 HTML 사용을 제한합니다\n\n- **범위** 모든 마크다운 파일\n- **근거** 마크다운은 의미론적 목적을 위해 사용되어야 합니다. HTML은 마크다운이\n 지원하지 않는 기능에만 사용됩니다. 허용 태그: `br`, `details`, `summary`, `sub`, `kbd`.\n `markdownlint` (MD033)에 의해 강제됩니다.\n...\n```\n\n---\n\n### 단계 4: 서술적인 링크 텍스트 및 alt 텍스트와 같은 콘텐츠 모범 사례\n\n#### 1. 콘텐츠 모범 사례를 위한 \"스타일 규칙\" 문서화\n\n이 액션은 명확성과 유지보수성을 향상시키지만 항상 자동으로 강제할 수는 없는 모범 사례를 다루는 \"스타일 규칙\" 섹션을 추가합니다. 이 규칙들은 콘텐츠 자체의 품질에 중점을 둡니다. 서술적인 링크 텍스트와 이미지 alt 텍스트를 의무화하는 것은 접근성(스크린 리더용)에 매우 중요하며, 모든 독자에게 더 나은 맥락을 제공하여 모호함을 방지합니다.\n\n**파일**: `guidelines/markdown/coding_styles.md`\n\n```markdown\n...\n---\n\n## 4. 스타일 규칙\n\n> **설명** 이 규칙들은 명확성과 유지보수성을 향상시키지만 항상 자동으로 강제되지는\n> 않는 모범 사례입니다.\n\n### 4.1 콘텐츠 및 가독성\n\n설명 명확하고 유지보수 가능한 콘텐츠 작성을 위한 규칙.\n\n콘텐츠 및 가독성 규칙 2 서술적인 링크 텍스트를 작성합니다. • 범위 모든 마크다운\n파일 • 근거 독자의 접근성과 맥락을 향상시킵니다. \"여기를 클릭하세요\"와 같은 일반적인\n문구는 피하세요.\n\n콘텐츠 및 가독성 규칙 3 모든 이미지에 서술적인 대체 텍스트를 제공합니다. • 범위\n모든 마크다운 파일 • 근거 접근성(스크린 리더)에 매우 중요하며 이미지가 로드되지 않을\n경우 표시됩니다.\n```\n\n---\n\n### 단계 5: 각 규칙에 대한 명확한 good/bad 코드 예시\n\n#### 1. 모든 규칙에 Good/Bad 예시 추가\n\n이 액션은 이전 단계에서 정의된 규칙에 구체적인 `GOOD` 및 `BAD` 예시를 추가하는 작업을 포함합니다. 이러한 예시는 추상적인 규칙을 명확하고 실용적인 지침으로 변환하기 때문에 스타일 가이드에 필수적입니다. 또한, 이 액션은 버전 관리 diff를 획기적으로 개선하는 핵심 스타일 가이드라인인 \"한 줄에 한 문장\" 규칙을 추가합니다.\n\n**파일**: `guidelines/markdown/coding_styles.md`\n\n```markdown\n...\n#### 포맷 규칙 2 ATX 스타일 헤더(`#`)를 사용합니다\n...\n```markdown\n# 좋은 예시\n\n# 헤더 1\n\n## 헤더 2\n\n# 나쁜 예시\n\n헤더 1\n======\n\n헤더 2\n------\n```\n\n...\n\n#### 포맷 규칙 5 순서 없는 목록에는 하이픈(`-`)을 사용합니다\n\n...\n\n```markdown\n# 좋은 예시\n\n- 항목 1\n- 항목 2\n\n# 나쁜 예시\n\n* 항목 1\n* 항목 2\n```\n\n...\n\n#### 포맷 규칙 7 울타리 코드 블록을 사용하고 언어 식별자를 명시합니다\n\n...\n\n````markdown\n# 좋은 예시\n\n```cpp\n#include \n\nint main() {\n std::cout << \"Hello, World!\\\\n\";\n return 0;\n}\n```\n\n# 나쁜 예시\n\n```\n// 언어가 명시되지 않음\n...\n```\n````\n\n...\n\n#### 포맷 규칙 8 이탤릭체에는 단일 밑줄을, 굵은체에는 이중 별표를 사용합니다\n\n...\n\n```markdown\n# 좋은 예시\n_이탤릭체_\n**굵은체**\n\n# 나쁜 예시\n*이탤릭체*\n__굵은체__\n```\n\n...\n콘텐츠 및 가독성 규칙 1 한 줄에 한 문장을 작성합니다. • 범위 모든 마크다운 파일 •\n근거 이렇게 하면 버전 관리에서 diff가 훨씬 깔끔해집니다. 한 문장을 변경하면 전체\n단락이 아닌 해당 한 줄만 수정된 것으로 표시됩니다.\n\n```markdown\n# 좋은 예시\n\n이것은 첫 번째 문장입니다.\n이것은 두 번째 문장입니다.\n\n# 나쁜 예시\n\n이것은 첫 번째 문장입니다. 이것은 두 번째 문장입니다.\n```\n\n...\n콘텐츠 및 가독성 규칙 2 서술적인 링크 텍스트를 작성합니다.\n...\n\n```markdown\n# 좋은 예시\n\n자세한 내용은 [기여 가이드라인](./CONTRIBUTING.md)을 참조하세요.\n\n# 나쁜 예시\n\n자세한 내용을 보려면 [여기를 클릭하세요](./CONTRIBUTING.md).\n```\n\n...\n콘텐츠 및 가독성 규칙 3 모든 이미지에 서술적인 대체 텍스트를 제공합니다.\n...\n\n```markdown\n# 좋은 예시\n\n![C++ 빌드 프로세스 다이어그램](./images/build-process.png)\n\n# 나쁜 예시\n\n![](./images/build-process.png)\n```\n\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n구현은 새로 생성된 문서에 대해 프로젝트에 구성된 포맷터와 린터를 실행하여 검증할 수 있습니다. 이를 통해 문서가 자체 규칙을 준수하는지 확인할 수 있습니다.\n\n```bash\n# 1. 프로젝트 루트 디렉토리로 이동합니다.\n\n# 2. 로컬 포맷팅 스크립트를 실행합니다.\n# 이 스크립트는 모든 관련 파일에 대해 Prettier와 markdownlint를 실행합니다.\n# (에픽 4에 따라 npm 스크립트가 구성되었다고 가정)\nnpm run format\n\n# 3. 파일을 수동으로 검토하여 모든 섹션과 규칙이 있는지,\n# 그리고 명세와 일치하는지 확인합니다.\nless guidelines/markdown/coding_styles.md\n```\n\n### 4.2. 예상 결과\n\n검증 단계를 실행한 후 `npm run format` 명령어는 오류 없이 완료되어야 합니다. 출력은 `guidelines/markdown/coding_styles.md`가 올바르게 포맷되었거나 포맷이 성공적으로 적용되었음을 나타내야 합니다. 콘텐츠에 기능적 변경이 발생해서는 안 됩니다.\n\n```\n> prettier --write .\nguidelines/markdown/coding_styles.md 12.3kB\nCheck formatting...\nAll matched files use Prettier code style!\n```","Prettier와 markdownlint에 의해 강제되는 마크다운용 `coding_styles.md` 파일",[318,321,323,325,327],{"_24":319,"_83":39,"_84":320,"_85":61},"핵심 원칙 문서화: 가독성, 일관성, 자동화",13,{"_24":322,"_83":39,"_84":320,"_85":88},"린터 구성과 연결된 서식 규칙 (예: 줄 길이, 헤더, 목록)",{"_24":324,"_83":39,"_84":320,"_85":91},"코드 블록 및 강조에 대한 규칙 명시",{"_24":326,"_83":39,"_84":320,"_85":94},"설명적인 링크 텍스트 및 alt 텍스트와 같은 콘텐츠 모범 사례",{"_24":328,"_83":39,"_84":320,"_85":97},"각 규칙에 대한 명확한 좋고 나쁜 코드 예제","일관되고 유지보수 가능한 마크다운 문서를 작성하기 위한 스타일 가이드를 저술",{"_22":331,"_24":332,"_75":333,"_77":334,"_79":335,"_51":347,"_42":99},"task-1751363754390","Mermaid 다이어그램 스타일 가이드","# 작업: Mermaid 다이어그램 스타일 가이드\n\n> **Epic**: Markdown 및 Mermaid 스타일 가이드 개발\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 명확하고 일관되며 오류 없는 Mermaid 다이어그램 작성을 위한 가이드 제작.\n- **근거**: 모든 프로젝트 문서에 걸쳐 Mermaid 다이어그램을 작성하는 표준화된 방법론을 수립하기 위함입니다. 이를 통해 시각적 일관성을 보장하고, 가독성을 높이며, 일반적인 렌더링 및 파싱 오류를 사전에 방지하여 프로젝트의 \"구조화된 문서 리포지토리\"의 품질과 유지보수성을 향상시킵니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: Mermaid의 구문, 스타일, 구조적 모범 사례를 상세히 기술한 `coding_styles.md` 파일.\n- **세부 사양**:\n - **문서 구조**: 핵심 원칙, 포맷, 스타일 규칙 섹션을 반드시 포함해야 합니다.\n - **내용 - 포맷 규칙**: 노드 ID(`PascalCase`), 따옴표로 묶인 레이블, 줄 바꿈(`
`), 화살표 주위 공백에 대한 구문을 정의해야 합니다.\n - **내용 - 스타일 규칙**: 적절한 노드 모양, 다이어그램 구조(`flowchart TD`), 서브그래프 사용, 코드 작성(짧은 명사 기반 레이블)에 대한 가이드라인을 제공해야 합니다.\n - **내용 - 오류 처리**: 일반적인 파싱 오류(예: 레이블에 마침표 사용)와 그 해결 방법에 대한 요약을 포함해야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── guidelines/\n# └── markdown/\n# └── mermaid/\n# └── coding_styles.md <-- 신규\n```\n\n- **프로세스 흐름 다이어그램**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n DevConsults[\"개발자가
Mermaid 스타일 가이드 참조\"] --> DevAuthors[\"개발자가 Mermaid 다이어그램
작성/수정\"];\n DevAuthors --> LocalPreview[\"로컬에서 미리보기/렌더링
(예: VS Code, GitHub)\"];\n LocalPreview --> ConsistentDiagram[\"명확하고 일관되며
오류 없는 다이어그램 렌더링\"];\n DevAuthors --> PushToRepo[\"개발자가 리포지토리에
변경 사항 푸시\"];\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 아래 항목들을 완료해야 합니다. 이것은 개략적인 체크리스트이며, 각 항목에 대한 자세한 구현 내용은 3장에 있습니다.\n\n- [ ] 파싱 오류 방지를 위한 이름 및 구문 규칙 정의.\n- [ ] 목적에 맞는 노드 모양 사용 가이드라인.\n- [ ] 하향식 흐름 및 서브그래프와 같은 다이어그램 구조 모범 사례.\n- [ ] 일반적인 파싱 오류 및 해결 방법 요약.\n- [ ] 명확성을 위한 스타일링 및 코드 작성 규칙.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 리포지토리\n- **관련 주요 구성 요소**:\n - **언어 가이드라인**: 이 작업은 이 구성 요소 내에 새 문서를 직접 생성합니다. 이 문서의 목적은 프로젝트의 Markdown 파일 내에서 사용되는 기술인 Mermaid에 대한 특정 코딩 스타일 가이드를 제공하는 것입니다.\n - **엔지니어링 원칙**: 이 스타일 가이드는 '가독성과 유지보수성 우선'과 같은 상위 수준의 원칙을 구체적이고 실행 가능한 규칙으로 성문화하여 구현합니다.\n - **자동화 도구**: 이 작업이 도구를 직접 수정하지는 않지만, 생성된 가이드는 이러한 다이어그램을 포함하는 Markdown 파일을 검증하는 린터(Prettier, markdownlint)와 연동되도록 만들어졌습니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `guidelines/markdown/mermaid/coding_styles.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계(Step)`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 세분화된 `액션(Action)`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 파싱 오류 방지를 위한 이름 및 구문 규칙 정의\n\n#### 1. 핵심 문서 구조 생성 및 구문 규칙 공식화\n\n이 액션은 개요, 핵심 원칙, 그리고 중요한 `포맷` 섹션을 포함하여 스타일 가이드의 기본 구조를 설정합니다. `포맷` 섹션은 ID, 레이블, 화살표에 대한 엄격한 구문 규칙을 성문화합니다. 이러한 규칙을 준수하는 것은 가장 일반적인 Mermaid 파싱 오류를 방지하고 모든 다이어그램의 구문적 유효성을 보장하는 데 필수적입니다.\n\n**파일**: `guidelines/markdown/mermaid/coding_styles.md`\n\n```markdown\n# Mermaid 코딩 스타일 가이드\n\n버전 v1.0 생성일 2025-06-26 담당자 @movingChurch\n\n---\n\n## 0. 개요\n\n- **목적**: Markdown 문서에 Mermaid 다이어그램을 포함할 때 일반적인 파싱 오류를 방지하고\n 일관된 스타일을 유지하기 위한 실용적인 규칙을 제공합니다.\n- **범위**: Markdown 문서 내의 모든 Mermaid 다이어그램.\n- **대상**: Mermaid 다이어그램을 생성하거나 수정하는 모든 개발자.\n\n---\n\n## 1. 목차\n\n1. [핵심 원칙](#2-핵심-원칙)\n2. [포맷](#3-포맷)\n3. [스타일 규칙](#4-스타일-규칙)\n\n---\n\n## 2. 핵심 원칙\n\n### 원칙 1: 가독성과 유지보수성 우선\n\n- **범위**: 모든 다이어그램\n- **근거**: 명확하고 일관된 다이어그램은 이해하기 쉽고 유지보수 비용이 낮습니다.\n\n### 원칙 2: 파싱 오류 사전 방지\n\n- **범위**: 다이어그램 구문\n- **근거**: ID와 레이블 같은 요소에 대한 엄격한 구문 규칙을 준수하는 것이 일반적인\n 렌더링 실패를 방지하는 가장 효과적인 방법입니다.\n\n---\n\n## 3. 포맷\n\n> **설명**: 이름 규칙, 들여쓰기, 줄 길이 등 린터/포맷터로 **100% 강제**할 수 있는\n> 규칙을 포함합니다. 이 규칙들은 파서 오류를 방지하는 데 매우 중요합니다.\n\n### 3.1 이름 및 구문 규칙\n\n| 코드 요소 | 이름 규칙 / 스타일 | 예시 |\n| ------------------------------- | ---------------------------------------------------------------------- | -------------------------------- |\n| 노드 ID | `PascalCase` (의미 있는 단어의 조합) | `UserLogin` |\n| 모든 레이블 (노드, 링크 등) | `반드시 따옴표(\\\"\\\")로 묶고 같은 줄에 있어야 합니다. 마침표(.)는 사용할 수 없습니다.` | `[\\\"내 레이블\\\"]` |\n| 줄 바꿈 | `공백이 포함된 레이블에는
사용` | `[\\\"첫 번째 줄
두 번째 줄\\\"]` |\n| 화살표 | `앞뒤에 공백 추가` | `A --> B` |\n\n### 3.2 포매팅 규칙\n\n#### 포맷 규칙 1: 리치 텍스트를 위해 HTML 레이블 활성화\n\n- **범위**: `
`, ``, `` 등을 사용하는 다이어그램\n- **근거**: Mermaid 렌더러는 레이블 내의 HTML 태그를 처리하기 위해 이 플래그를 명시적으로\n 활성화해야 합니다.\n\n```mermaid\n%% 좋은 예\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n A[\"줄 바꿈에는
<br/> 사용\"]\n\n %% 나쁜 예\n %% 이 코드는 줄 바꿈을 올바르게 렌더링하지 않습니다.\n B[\"줄 바꿈에는
<br/> 사용\"]\n```\n\n```\n\n---\n\n### 단계 2: 목적에 맞는 노드 모양 사용 가이드라인\n\n#### 1. 노드 모양 가이드라인 추가\n\n이 액션은 가이드에 `노드 모양` 섹션을 추가합니다. 이 규칙은 시각적 커뮤니케이션에 매우 중요합니다. 결정에는 다이아몬드, 행동에는 사각형 등 요소 유형에 따라 다른 모양을 사용하면 개발자가 다이어그램의 흐름과 목적을 직관적으로 이해할 수 있게 해줍니다. 이는 플로우차트의 시각적 언어를 표준화합니다.\n\n**파일**: `guidelines/markdown/mermaid/coding_styles.md`\n\n```markdown\n...\n---\n\n## 4. 스타일 규칙\n\n### 4.1 노드 모양\n\n**설명**: 요소의 목적(예: 행동, 결정, 시작/종료)을 시각적으로 나타내기 위해\n적절한 노드 모양을 사용합니다.\n\n#### 노드 모양 규칙 1: 목적에 맞는 노드 유형 사용\n\n- **범위**: 모든 플로우차트 다이어그램\n- **근거**: 노드의 시각적 모양은 그 역할과 의미를 직관적으로 전달하여 다이어그램\n 가독성을 향상시킵니다.\n\n| 모양 | 구문 | 권장 사용처 | 예시 |\n| ----------------- | -------------- | ------------------------------- | -------------------------------- |\n| 사각형 | `id[\\\"text\\\"]` | 일반적인 행동, 프로세스 단계 | `ProcessData[\\\"데이터 처리\\\"]` |\n| 둥근 사각형 | `id(\\\"text\\\")` | 보조 작업, 선택적 단계 | `LogEvent(\\\"이벤트 기록\\\")` |\n| 원 | `id((\\\"text\\\"))` | 시작 또는 종료 지점 | `StartNode((\\\"시작\\\"))` |\n| 다이아몬드 | `id{\\\"text\\\"}` | 조건부 분기 | `CheckAuth{\\\"인증되었는가?\\\"}` |\n| 캡슐 | `id([\\\"text\\\"])` | 시작 또는 종료 지점 | `EndNode([\\\"종료\\\"])` |\n\n```mermaid\n%% 좋은 예\nflowchart TD\n StartNode((\\\"시작\\\")) --> ProcessData[\\\"데이터 처리\\\"]\n ProcessData --> CheckAuth{\\\"인증되었는가?\\\"}\n CheckAuth -- \\\"성공\\\" --> LogEvent(\\\"이벤트 기록\\\")\n CheckAuth -- \\\"실패\\\" --> EndNode([\\\"종료\\\"])\n LogEvent --> EndNode([\\\"종료\\\"])\n```\n\n...\n\n```\n\n---\n\n### 단계 3: 하향식 흐름 및 서브그래프와 같은 다이어그램 구조 모범 사례\n\n#### 1. 다이어그램 구조 규칙 추가\n\n이 액션은 `다이어그램 구조` 섹션을 추가합니다. 하향식(`TD`) 흐름으로 표준화하면 리포지토리의 모든 문서에서 일관된 독서 경험을 제공합니다. `subgraph`의 도입은 대규모 다이어그램의 복잡성을 관리하는 도구를 제공하며, 이는 가독성 및 유지보수성이라는 핵심 원칙을 직접적으로 지원합니다.\n\n**파일**: `guidelines/markdown/mermaid/coding_styles.md`\n\n```markdown\n...\n### 4.5 다이어그램 구조\n\n**설명**: 다이어그램의 전반적인 구조적 일관성을 유지하기 위한 규칙입니다.\n\n#### 구조 규칙 1: 다이어그램 방향을 하향식(TD)으로 통일\n\n- **범위**: 모든 다이어그램\n- **근거**: 특별한 이유가 없는 한, 다이어그램 흐름을 하향식(`TD`)으로 통일하면 사용자가\n 여러 문서에 걸쳐 구조를 더 빠르고 직관적으로 파악하는 데 도움이 됩니다.\n\n```mermaid\n%% 좋은 예\nflowchart TD\n UserLogin --> AuthSuccess\n```\n\n#### 구조 규칙 2: 복잡한 다이어그램은 서브그래프로 그룹화\n\n- **범위**: 세 개 이상의 관련 노드 그룹이 있는 복잡한 다이어그램\n- **근거**: `subgraph`로 관련된 요소들을 그룹화하면 전체 다이어그램 구조를 더 쉽게\n 이해할 수 있고 가독성을 크게 향상시킵니다.\n\n```mermaid\n%% 좋은 예\nflowchart TD\n subgraph \"인증 프로세스\"\n UserLogin[\"사용자 로그인\"] --> CheckAuth{\"인증 확인\"}\n end\n CheckAuth -- \"성공\" --> MainService[\"메인 서비스\"]\n```\n\n```\n\n---\n\n### 단계 4: 일반적인 파싱 오류 및 해결 방법 요약\n\n#### 1. 일반적인 오류 및 해결 방법 문서화\n\n이 액션은 `일반적인 오류 및 해결 방법` 섹션을 추가합니다. 이 내용은 개발자가 레이블의 마침표나 잘못된 줄 바꿈으로 인한 오류와 같은 일반적인 문제를 신속하게 해결할 수 있도록 돕는 실용적인 문제 해결 가이드입니다. '좋은 예'와 '나쁜 예' 구문을 명시적으로 제공하여 학습 속도를 높이고 다이어그램 디버깅에 소요되는 시간을 줄입니다.\n\n**파일**: `guidelines/markdown/mermaid/coding_styles.md`\n\n```markdown\n...\n### 4.3 일반적인 오류 및 해결 방법\n\n**설명**: 다음은 일반적인 파싱 오류와 그 해결 방법입니다.\n\n#### 오류 처리 규칙 1: 레이블에 마침표를 사용하지 마세요\n\n- **범위**: 모든 노드 레이블\n- **근거**: Mermaid 파서는 레이블에 마침표(`.`) 사용을 엄격히 금지하며, 이는\n `Parse error`를 유발합니다.\n\n```mermaid\nflowchart TD\n%% 좋은 예\nA[\"서비스 초기화\"]\n\n%% 나쁜 예\nB[\"서비스 초기화.\"]\n```\n\n#### 오류 처리 규칙 2: 공백이 있는 레이블에는 `
` 사용\n\n- **범위**: 공백이 포함된 모든 노드 레이블\n- **근거**: 공백이 있는 레이블에서 줄 바꿈을 위해 `
`을 사용하지 않으면\n `got 'SPACE'` 파싱 오류가 발생할 수 있습니다.\n\n```mermaid\nflowchart TD\n%% 좋은 예\nA[\"마지막
단계 실행\"]\n\n%% 나쁜 예\nB[\"마지막 단계 실행\"]\n```\n\n#### 오류 처리 규칙 3: 레이블에 Markdown 구문을 사용하지 마세요\n\n- **범위**: 모든 노드 레이블\n- **근거**: Mermaid 파서는 레이블 내의 Markdown 구문을 해석하지 않습니다.\n 일반 텍스트로 렌더링되어 의도하지 않은 시각적 결과가 나올 수 있습니다.\n 텍스트 스타일링이 필요할 경우, `htmlLabels`가 활성화된 경우에만 `` 또는 ``와 같은\n HTML 태그를 사용하세요.\n\n```mermaid\nflowchart TD\n%% 좋은 예: 명확성을 위해 일반 텍스트 사용\nA[\"굵은 텍스트 사용\"]\n\n%% 나쁜 예: Markdown은 일반 텍스트로 렌더링됩니다\nB[\"**굵은** 텍스트 사용\"]\n```\n\n...\n\n```\n\n---\n\n### 단계 5: 명확성을 위한 스타일링 및 코드 작성 규칙\n\n#### 1. 스타일링 및 코드 작성 규칙 추가\n\n이 액션은 `클래스를 이용한 스타일링` 및 `코드 작성 스타일` 섹션을 추가합니다. `classDef`를 사용하면 스타일링을 중앙에서 관리하여 다이어그램의 유지보수 및 업데이트를 용이하게 합니다. 주석 금지, 짧은 명사 기반 레이블 선호 등 작성 규칙은 Mermaid 소스 코드 자체를 최대한 자체 설명적으로 만들고 가독성을 높이는 데 중점을 두며, 이는 프로젝트의 핵심 철학과 일치합니다.\n\n**파일**: `guidelines/markdown/mermaid/coding_styles.md`\n\n```markdown\n...\n### 4.2 클래스를 이용한 스타일링\n\n**설명**: `classDef`와 `class`를 사용하여, 특히 결정 및 행동 노드에 일관된\n스타일 패턴을 적용합니다.\n\n#### 스타일링 규칙 1: `classDef`로 스타일 중앙화\n\n- **범위**: 반복적인 노드 유형이 있는 다이어그램\n- **근거**: 스타일 정의를 중앙화하면 다이어그램을 더 쉽게 읽고 유지보수할 수\n 있으며, 통일된 모양을 보장합니다.\n\n```mermaid\n%% 좋은 예\nflowchart TD\n classDef decision fill:#fff8c6,stroke:#333;\n classDef action fill:#e3d7ff,stroke:#333;\n\n Q{\"준비됐나요?\"} --> A[\"프로덕션에 배포\"];\n class Q decision;\n class A action;\n```\n\n...\n\n### 4.4 코드 작성 스타일\n\n**설명**: 다이어그램 코드 자체의 일관성과 명확성을 유지하기 위한 규칙입니다.\n\n#### 스타일 규칙 1: 주석(`%%`)을 사용하지 마세요\n\n- **범위**: 모든 다이어그램\n- **근거**: 주석은 코드를 불필요하게 복잡하게 만들 수 있습니다. 코드는 주석\n 없이도 이해할 수 있을 만큼 명확해야 합니다.\n\n#### 스타일 규칙 2: 레이블은 짧고 명확한 명사로 작성\n\n- **범위**: 모든 노드 레이블\n- **근거**: 짧고 명확한 명사 형태의 레이블은 다이어그램의 가독성을 높이고 각\n 노드의 역할을 직관적으로 파악하는 데 도움이 됩니다.\n\n```mermaid\nflowchart TD\n %% 좋은 예\n A[\"사용자 인증\"]\n\n %% 나쁜 예\n B[\"사용자를 인증하는 프로세스\"]\n```\n\n...\n\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 개발자는 작업이 완료되었는지 확인하기 위해 다음 작업을 수행해야 합니다:\n 1. `guidelines/markdown/mermaid/coding_styles.md` 파일이 3장에 명시된 내용으로 생성되었는지 확인합니다.\n 2. 프로젝트의 로컬 포맷터 스크립트를 실행하여 새 Markdown 파일이 리포지토리 표준을 준수하는지 확인합니다.\n 3. Mermaid를 지원하는 Markdown 렌더러(예: GitHub 웹 인터페이스, VS Code 확장 프로그램)에서 `guidelines/markdown/mermaid/coding_styles.md` 파일을 미리 보고 모든 예제 다이어그램이 파싱 오류 없이 올바르게 렌더링되는지 확인합니다.\n\n```bash\n# 2. 로컬 포맷터 및 린터 실행\n./scripts/executables/run_formatters.sh\n```\n\n### 4.2. 예상 결과\n\n- `run_formatters.sh` 스크립트를 실행한 후, 명령어는 종료 코드 0으로 종료되어야 합니다. 출력에는 새 스타일 가이드를 포함한 모든 파일이 올바르게 포맷되었다고 표시되어야 합니다.\n- Markdown 파일을 미리 볼 때, '좋은 예' 아래의 모든 Mermaid 다이어그램은 예상대로 렌더링되어야 합니다. '나쁜 예' 아래의 다이어그램은 의도한 대로 표시되거나 파싱 오류를 보일 수 있으며, 이는 잘못된 구문을 보여주는 것이므로 허용됩니다. 깨진 이미지 링크나 렌더링되지 않은 코드 블록이 없어야 합니다.","구문, 스타일링, 구조적 모범 사례를 상세히 설명하는 Mermaid용 `coding_styles.md` 파일",[336,339,341,343,345],{"_24":337,"_83":39,"_84":338,"_85":61},"파싱 오류를 방지하기 위한 이름 및 구문 규칙 정의",14,{"_24":340,"_83":39,"_84":338,"_85":88},"목적에 맞는 노드 모양 사용에 대한 가이드라인",{"_24":342,"_83":39,"_84":338,"_85":91},"하향식 흐름 및 서브그래프와 같은 다이어그램 구조 모범 사례",{"_24":344,"_83":39,"_84":338,"_85":94},"일반적인 파싱 오류 및 해결책 요약",{"_24":346,"_83":39,"_84":338,"_85":97},"명확성을 위한 스타일링 및 코드 작성 규칙","명확하고 일관되며 오류 없는 Mermaid 다이어그램을 만들기 위한 가이드를 작성",{"_22":349,"_24":350,"_75":351,"_77":352,"_79":353,"_51":365,"_42":99},"task-1751363803993","C++ 핵심 코딩 스타일 가이드","# 작업: C++ 핵심 코딩 스타일 가이드\n\n> **에픽**: C++ 코딩 및 포맷팅 가이드라인 개발\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 최신 프랙티스와 도구를 기반으로 한 포괄적인 C++ 스타일 가이드 문서를 작성합니다.\n- **근거**: 이 작업은 프로젝트 전반에 걸쳐 C++ 개발 표준을 공식화하는 데 필수적입니다. 명확한 가이드를 생성함으로써 코드 구조, 스타일, 모범 사례에 대한 단일 진실 공급원(single source of truth)을 확립합니다. 이러한 표준화는 코드 가독성과 유지보수성을 향상시키고, 개발자의 인지 부하를 줄이며, `clang-tidy`와 같은 자동화된 도구로 강제할 기반 규칙을 제공합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: 헤더, 스코프, 클래스, 함수, 모범 사례에 대한 규칙을 정의하는 `coding_style.md` 파일.\n- **세부 사양**: 최종 문서는 다음 항목에 대해 명확하게 정의된 섹션과 규칙을 포함해야 합니다:\n - 인클루드 가드 및 순서를 포함한 헤더 파일 구성.\n - 네임스페이스, 변수, 함수에 대한 스코프 규칙.\n - 생성자, 상속, 연산자 오버로딩, 접근 제어를 다루는 클래스 설계 원칙.\n - 매개변수 전달 규칙 및 크기 권장 사항을 포함한 함수 설계.\n - 메모리 관리, 타입 안전성, 제어 흐름 등 최신 C++ 사용을 위한 모범 사례.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── guidelines/\n# └── cpp/\n# └── coding_style.md <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 C++ 코딩 스타일 가이드가 개발자와 자동화된 도구 모두에게 어떻게 중앙 참조점으로 작용하는지를 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"개발 및 검증 워크플로\"\n Dev[\"개발자\"]\n Code[\"C++ 소스 코드\"]\n Guide[\"guidelines/cpp/coding_style.md\"]\n Tooling[\"자동화 도구
(예: clang-tidy)\"]\n \n Dev -- \"참조\" --> Guide\n Dev -- \"작성/수정\" --> Code\n Guide -- \"규칙 정의\" --> Tooling\n Tooling -- \"검증\" --> Code\n Code -- \"피드백 루프\" --> Dev\n end\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 상세 구현은 3절에 기술되어 있습니다.\n\n- [ ] 헤더 파일 규칙(자체 포함, 포함 순서) 문서화.\n- [ ] 스코프 규칙(네임스페이스, 지역 변수) 정의.\n- [ ] 클래스 설계 가이드라인(생성자, 상속, 연산자) 정의.\n- [ ] 함수 설계 규칙(매개변수 전달, 길이) 정의.\n- [ ] 메모리 관리, 타입, 제어 흐름에 대한 모범 사례 정의.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 리포지토리\n- **관련 주요 구성 요소**:\n - **언어 가이드라인**: 이 작업은 이 구성 요소 내의 핵심 산출물을 직접 생성합니다. `coding_style.md` 파일은 핵심 C++ 가이드라인 문서가 될 것입니다.\n - **엔지니어링 원칙**: 이 작업에서 정의된 규칙들은 `principles/` 디렉터리에 설정된 상위 수준의, 언어에 구애받지 않는 원칙들의 구체적인 구현이어야 합니다.\n - **자동화 도구**: 이 가이드는 `clang-format`, `clang-tidy`와 같은 도구에 의해 코드화되고 강제될 규칙에 대한 인간이 읽을 수 있는 명세서 역할을 합니다. 이는 자동화된 검사 뒤에 있는 '이유(why)'를 제공합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `guidelines/cpp/coding_style.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공하게 됩니다.\n\n---\n\n### 1단계: 헤더 파일 규칙(자체 포함, 포함 순서) 문서화\n\n#### 1. C++ 코딩 스타일 가이드 생성 및 헤더 규칙 정의\n\n이 작업은 `coding_style.md` 문서를 만들고 개요, 목차, 그리고 헤더 파일에 대한 첫 번째 주요 규칙 섹션을 포함한 초기 구조를 채웁니다. 이 규칙들은 헤더가 자체적으로 포함되어 독립적으로 컴파일될 수 있도록 보장하고, `#define` 가드를 통해 다중 포함 오류를 방지하며, 유지보수성을 높이고 병합 충돌을 줄이기 위해 포함 순서를 표준화하는 데 매우 중요합니다.\n\n**파일**: `guidelines/cpp/coding_style.md`\n\n```markdown\n# C++ 코딩 스타일 규칙\n\n버전 v1.0.0 생성일 2025-06-30\n\n소유자 @movingChurch\n\n---\n\n## 0. 개요\n\n- **목적**: 코딩 관행을 표준화하고 불필요한 논쟁을 줄여 코드 가독성, 성능, 개발\n 생산성을 향상시키는 것을 목표로 합니다.\n- **범위**: C++20 표준을 따르며, Google C++ 스타일 가이드를 기반으로 합니다.\n- **대상**: 본 코딩 스타일 가이드를 따르는 모든 C++ 개발자.\n\n---\n\n## 1. 목차\n\n1. [핵심 원칙](#2-핵심-원칙)\n2. [포맷](#3-포맷)\n3. [스타일 규칙](#4-스타일-규칙)\n4. [모범 사례](#5-모범-사례)\n\n---\n\n## 2. 핵심 원칙\n\n자세한 개발 원칙은 [C++ 개발 원칙](./principles/README.md) 문서를 참고하십시오.\n\n---\n\n## 3. 포맷\n\n> **설명**: 코드 포맷팅은 `clang-format`을 통해 자동으로 검증됩니다. 모든 코드는\n> 프로젝트에 정의된 포맷팅 규칙을 준수해야 합니다. **포맷터의 결과는 항상 사람의\n> 판단보다 우선합니다.**\n>\n> **구성**: 포맷팅 설정은 `assets/.clang-format` 파일에 정의되어 있습니다. 다음\n> 규칙들은 이 구성의 주요 측면을 설명합니다.\n\n자세한 네이밍 및 포맷팅 규칙은\n[C++ 네이밍 및 포맷팅 규칙](./formatting.md) 문서를 참고하십시오.\n\n---\n\n## 4. 스타일 규칙\n\n> **설명**: 이 섹션의 스타일 규칙은 `clang-tidy`를 사용하여 확인할 수 있습니다.\n> 일부 규칙은 자동으로 수정될 수 있지만, 대부분은 개발자의 신중한 검토가\n> 필요합니다.\n>\n> **구성**: `clang-tidy` 설정은 `assets/.clang-tidy` 파일에 정의되어 있습니다.\n\n### 4.1 헤더 파일\n\n설명: 모든 소스 파일(`.cpp`)은 해당 헤더 파일(`.hpp`)을 가져야 하며, 다음은 예외입니다:\n\n- `main()`을 포함하는 실행 파일의 소스 파일.\n- 테스트용 소스 파일.\n\n#### 헤더 규칙 1: 자체 포함 헤더(Self-contained Headers)\n\n- 모든 헤더 파일은 그 자체로 컴파일 가능해야 합니다.\n- 포함을 목적으로 하는 비-헤더 파일은 `.inc` 확장자를 사용해야 합니다.\n- 인라인 및 템플릿의 경우, 선언과 정의는 같은 헤더 파일에 있어야 하며, 다른\n 헤더 파일로 분리하지 마십시오.\n\n**구현:**\n\n- `#define` 가드를 사용하십시오.\n- 필요한 모든 참조를 직접 포함하고 다른 헤더에 포함된 헤더에 의존하지 마십시오.\n- 헤더 파일 간의 의존성을 최대한 최소화하십시오.\n\n#### 헤더 규칙 2: #define 가드\n\n- 모든 헤더 파일(`.h`, `.hpp`)은 다중 포함을 방지하기 위해 `#define` 가드를\n 가져야 합니다.\n- 단, C++20 모듈 인터페이스 파일(`.ixx`, `.cppm` 등)은 헤더 가드를 사용하지\n 않습니다.\n - 고유성을 보장하기 위해, `#define` 가드는 프로젝트 소스 트리의 절대 경로를\n 기반으로 해야 합니다.\n - 형식은 `_____HPP_` 이어야 합니다.\n\n```cpp\n// include/vision/feature/surf.hpp\n#ifndef VISION__FEATURE__SURF_HPP_\n#define VISION__FEATURE__SURF_HPP_\n\n// ...\n\n#endif // VISION__FEATURE__SURF_HPP_\n```\n\n#### 헤더 규칙 3: 사용하는 것은 포함하라(Include What You Use)\n\n- 파일에서 사용되는 모든 심볼에 대한 헤더는 포함되어야 합니다.\n - 특히, `std 라이브러리`에 대한 헤더는 사용되는 곳에 포함되어야 합니다.\n - 소스 또는 헤더 파일이 다른 곳에 정의된 심볼을 참조하는 경우, 해당 파일은\n 그 심볼의 선언이나 정의를 제공하는 적절한 헤더 파일을 직접 포함해야 합니다.\n - 간접적인 포함에 의존하지 마십시오.\n\n```cpp\n// function.hpp\n#ifndef FUNCTION_HPP_\n#define FUNCTION_HPP_\n\n#include \n\n// ...\n\n#endif // FUNCTION_HPP_\n\n\n// example.hpp\n#ifndef EXAMPLE_HPP_\n#define EXAMPLE_HPP_\n\n#include // std::string에 대한 헤더, example.hpp에 포함되어야 함\n#include \"function.hpp\"\n\nstd::string getFileNameString();\n\n#endif // EXAMPLE_HPP_\n```\n\n#### 헤더 규칙 4: 전방 선언(Forward Declarations)\n\n- 전방 선언은 헤더 파일 간의 불필요한 `#include`를 줄여 컴파일 시간을 단축하는 데\n 유용합니다.\n- 특히 다음과 같은 경우에 신중하게 사용하는 것이 좋습니다:\n - 두 클래스가 서로를 참조하는 순환 종속성을 해결하기 위해.\n - 특정 클래스에 대한 포인터나 참조만 필요할 때, 전체 클래스 정의를 포함하지\n 않기 위해.\n - Pimpl Idiom을 사용할 때.\n- 그러나 단순히 `#include`를 피하기 위해 과도하게 사용하지 마십시오. 전방 선언된\n 타입의 크기나 멤버에 접근해야 할 때는 완전한 타입 정의가 필요하다는 점을\n 인지해야 합니다.\n\n```cpp\n// GOOD: my_class.hpp\n#ifndef MY_CLASS_HPP_\n#define MY_CLASS_HPP_\n\nclass OtherClass; // 전방 선언\n\nclass MyClass {\n public:\n void DoSomething(OtherClass* other);\n private:\n OtherClass* other_ptr_;\n};\n\n#endif // MY_CLASS_HPP_\n```\n\n#### 헤더 규칙 5: 인라인 함수(Inline Functions)\n\n- **함수는 10줄 이하와 같이 작을 때만 인라인으로 정의하십시오.**\n- **10줄을 초과하는 함수는 인라인으로 정의하지 마십시오.**\n- **루프나 switch 문을 포함하는 함수에는 인라인을 사용하지 마십시오.**\n- 함수를 `inline`으로 선언한다고 해서 반드시 인라인화되는 것은 아닙니다. 재귀\n 함수나 가상 함수는 인라인화되지 않습니다.\n\n```cpp\n// GOOD: 10줄 이하의 작은 함수\ninline int Add(int a, int b) {\n return a + b;\n}\n\n// BAD: 10줄을 초과하거나 복잡한 제어 흐름을 가진 함수\ninline void ComplexFunction(int n) {\n if (n < 0) {\n // ...\n }\n for (int i = 0; i < n; ++i) {\n // ...\n }\n}\n```\n\n#### 헤더 규칙 6: 포함 파일의 이름과 순서\n\n- 헤더는 다음 순서로 포함하며, 각 그룹 사이에는 한 줄의 빈 줄을 둡니다:\n - 관련된 헤더 (소스 파일의 경우).\n - C 시스템 헤더.\n - C++ 표준 라이브러리 헤더.\n - 다른 라이브러리 헤더 (서드파티).\n - 프로젝트 헤더.\n- 포함 경로에 `.` (현재 디렉토리)나 `..` (부모 디렉토리)를 사용하지 마십시오.\n- 각 섹션 내에서 포함 파일은 알파벳 순으로 나열해야 합니다.\n\n```cpp\n// vision/src/feature/surf.cpp\n#include \"vision/feature/surf.hpp\"\n\n#include // C 시스템 헤더\n\n#include // C++ 표준 라이브러리 헤더\n#include \n\n#include \"opencv/feature/surf.hpp\" // 다른 라이브러리의 .hpp 파일\n\n#include \"vision/feature/base.hpp\" // 프로젝트의 .hpp 파일\n```\n\n```\n\n---\n\n### 2단계: 스코프 규칙(네임스페이스, 지역 변수) 정의\n\n#### 1. 스코프 규칙 추가\n\n이 작업은 문서에 \"스코프(Scoping)\" 규칙 섹션을 추가합니다. 이 규칙들은 심볼의 가시성을 관리하고 대규모 코드베이스에서 이름 충돌을 방지하는 데 근본적입니다. 이들은 네임스페이스 사용을 의무화하고, 정적 연결(static linkage)을 대체하는 최신 방법(이름 없는 네임스페이스)을 정의하며, 스코프를 제한하고 명확성을 향상시키기 위한 변수 선언 규칙을 수립합니다.\n\n**파일**: `guidelines/cpp/coding_style.md`\n\n```markdown\n...\n#include \"vision/feature/base.hpp\" // 프로젝트의 .hpp 파일\n```\n\n### 4.2 스코프(Scoping)\n\n#### 스코프 규칙 1: 네임스페이스(Namespaces)\n\n- **C++20 모듈 사용을 권장합니다**. 모듈을 사용하지 않는 경우, 네임스페이스를\n 적극적으로 사용하십시오.\n- 네임스페이스는 충돌을 피하기 위해 프로젝트 및 라이브러리 이름을 기반으로\n 명명해야 합니다.\n- 소스 파일 상단에 위치시키고, 내부 연결(internal linkage)을 지정하기 위해 이름\n 없는 네임스페이스(`namespace {}`)를 사용하십시오.\n- `using namespace` 지시문은 `.cpp` 파일 내에서 제한적으로만 허용되며, 헤더\n 파일에서는 절대 사용해서는 안 됩니다.\n\n```cpp\n// GOOD: 헤더 파일\nnamespace my_project::my_module {\nclass MyClass { /*...*/ };\n}\n\n// GOOD: cc 파일\nnamespace my_project::my_module {\n// ...\n}\n\n// BAD: 헤더 파일\nusing namespace std;\n```\n\n#### 스코프 규칙 2: 이름 없는 네임스페이스와 정적 변수\n\n- `.cpp` 파일 내에서 외부로 노출할 필요가 없는 변수나 함수는 **이름 없는\n 네임스페이스** 안에 선언해야 합니다.\n- 내부 연결을 위해 `static` 키워드를 사용하는 것은 C++ 표준에서 더 이상 사용되지\n 않으므로, 대신 이름 없는 네임스페이스를 사용하십시오.\n\n```cpp\n// GOOD\nnamespace {\nconstexpr int kPrivateConstant = 100;\n\nvoid PrivateFunction() {\n // ...\n}\n} // namespace\n```\n\n#### 스코프 규칙 3: 비멤버 함수, 정적 멤버 함수, 전역 함수\n\n- **비멤버 함수**는 특정 클래스와 강하게 결합되지 않은 유틸리티 기능에\n 사용됩니다.\n- **정적 멤버 함수**는 클래스의 인스턴스 데이터에 접근할 필요가 없을 때\n 사용됩니다.\n- **전역 함수**는 가능한 한 피하고, 네임스페이스로 그룹화하여 관리해야 합니다.\n- 전역 오염을 방지하기 위해 함수 선언은 항상 네임스페이스 내에 배치하십시오.\n\n```cpp\n// GOOD: 비멤버 함수 (유틸리티)\nnamespace string_utils {\nstd::vector Split(std::string_view str, char delimiter);\n}\n\n// GOOD: 정적 멤버 함수\nclass File {\n public:\n static bool Exists(const std::string& path);\n // ...\n};\n\n// BAD: 전역 함수\nbool FileExists(const std::string& path); // 네임스페이스로 감싸야 함\n```\n\n#### 스코프 규칙 4: 지역 변수\n\n- 변수는 **가능한 가장 좁은 스코프**에 선언하고, 선언과 동시에 초기화하십시오.\n- C++은 블록 내 어디에서나 변수 선언을 허용하므로, 사용 직전에 선언하는 것이\n 좋은 습관입니다.\n- 루프 변수는 루프 문 내에서 선언하여 스코프를 제한하십시오.\n\n```cpp\n// GOOD: 사용 직전에 변수를 선언하고 초기화\nint i = f();\n// ...\nint j = g();\n\n// BAD: 변수를 미리 선언\nint i;\n// ...\ni = f();\n\n// GOOD: 루프 변수\nfor (int i = 0; i < 10; ++i) {\n // ...\n}\n```\n\n#### 스코프 규칙 5: 정적 및 전역 변수\n\n- **클래스 타입의 정적 및 전역 변수는 금지됩니다.**\n- POD(Plain Old Data) 타입의 정적/전역 변수는 허용되지만, 컴파일 타임 상수가\n 되도록 `constexpr`로 선언하는 것을 강력히 권장합니다.\n- 함수 수준의 정적 변수는 스레드 안전성 문제를 일으킬 수 있으므로 주의해서\n 사용해야 합니다.\n\n```cpp\n// GOOD\nconstexpr int kMaxConnections = 10;\nconstexpr const char* kDefaultName = \"Default\";\n\n// BAD: 클래스 타입의 전역 변수\nstd::string global_string = \"Hello\"; // 초기화 순서 문제를 일으킬 수 있음\n```\n\n```\n\n---\n\n### 3단계: 클래스 설계 가이드라인(생성자, 상속, 연산자) 정의\n\n#### 1. 클래스 설계 가이드라인 추가\n\n이 작업은 객체 지향 설계를 위한 규칙을 제공하는 \"클래스(Classes)\" 섹션을 추가합니다. 이 가이드라인은 올바른 생성자 사용(2단계 초기화), 암시적 변환 방지, Rule of Five 준수, 상속보다 컴포지션 지향, 직관적인 경우로 연산자 오버로딩 제한 등을 정의하여 견고하고 유지보수 가능하며 잘 캡슐화된 코드를 장려합니다.\n\n**파일**: `guidelines/cpp/coding_style.md`\n\n```markdown\n...\nstd::string global_string = \"Hello\"; // 초기화 순서 문제를 일으킬 수 있음\n```\n\n### 4.3 클래스(Classes)\n\n#### 클래스 규칙 1: 생성자(Constructors)\n\n- 생성자에서 실패할 수 있는 초기화(예: 파일 열기, 네트워크 연결)를 수행하지\n 마십시오.\n- 대신, **2단계 초기화(Two-phase initialization)** 패턴(예: `Init()` 메서드나\n 팩토리 함수)을 사용하십시오.\n- 생성자에서 가상 함수를 호출하지 마십시오. 파생 클래스의 오버라이드된 함수가\n 아닌 기본 클래스의 함수가 호출됩니다.\n\n```cpp\n// GOOD: 2단계 초기화\nclass MyService {\n public:\n MyService();\n bool Init(); // 실패 가능한 초기화\n private:\n // ...\n};\n\n// 사용법\nMyService service;\nif (!service.Init()) {\n // 오류 처리\n}\n```\n\n#### 클래스 규칙 2: 암시적 변환(Implicit Conversions)\n\n- **단일 인자 생성자는 `explicit`으로 선언하여** 의도하지 않은 암시적 변환을\n 방지하십시오.\n- 예외는 복사/이동 생성자 또는 `std::initializer_list`를 받는 생성자입니다.\n\n```cpp\n// GOOD: explicit으로 암시적 변환 방지\nclass MyClass {\n public:\n explicit MyClass(int value);\n};\n\n// BAD: int에서 MyClass로의 암시적 변환을 허용\nclass MyClass {\n public:\n MyClass(int value);\n};\n```\n\n#### 클래스 규칙 3: 복사 및 이동 가능 타입\n\n- 클래스를 **복사 가능하거나 이동 가능하게** 만들려면 그 의미와 비용을 명확히\n 이해하고 구현해야 합니다.\n- **Rule of Five/Six**를 따르십시오: 복사/이동 생성자, 복사/이동 할당 연산자,\n 소멸자 중 하나를 정의해야 하는 경우, 다른 필요한 연산들도 정의하거나\n `= default` 또는 `= delete`로 명시적으로 처리해야 합니다.\n- 복사가 필요하지 않은 경우, 복사 생성자와 할당 연산자를 `= delete`로 명시적으로\n 삭제하십시오.\n\n```cpp\n// GOOD: 복사 불가능한 클래스\nclass NonCopyable {\n public:\n NonCopyable(const NonCopyable&) = delete;\n NonCopyable& operator=(const NonCopyable&) = delete;\n // ...\n};\n```\n\n#### 클래스 규칙 4: 구조체(Structs)와 클래스(Classes)의 비교\n\n- **구조체(Structs)**는 주로 **수동적인 데이터 객체(Passive Data Objects)**에\n 사용하십시오.\n- **클래스(Classes)**는 데이터와 함께 **불변성(invariants)**이나 특정 기능을\n 제공하는 객체에 사용하십시오.\n- 구조체의 모든 멤버는 `public`이어야 하며, 멤버 함수는 데이터 접근/설정을 넘는\n 복잡한 로직을 포함해서는 안 됩니다.\n\n```cpp\n// GOOD: 수동적 데이터를 위한 구조체\nstruct Point {\n double x;\n double y;\n};\n\n// GOOD: 불변성을 가진 객체를 위한 클래스\nclass Circle {\n public:\n Circle(Point center, double radius);\n double GetArea() const;\n private:\n bool IsValid() const { return radius_ > 0; } // 불변성\n Point center_;\n double radius_;\n};\n```\n\n#### 클래스 규칙 5: 상속(Inheritance)\n\n- **상속보다 컴포지션을 선호하십시오**.\n- 상속을 사용해야 한다면, **public 상속**은 \"is-a\" 관계를 만족해야 합니다.\n- 파생 클래스는 기본 클래스의 모든 인터페이스를 의미적으로 올바르게 구현해야\n 합니다(리스코프 치환 원칙).\n- **다중 상속은 인터페이스 상속(순수 가상 클래스)에만 허용**되며, 구현 상속은\n 피하십시오.\n\n```cpp\n// GOOD: \"is-a\" 관계를 만족하는 상속\nclass Shape { ... };\nclass Circle : public Shape { ... };\n```\n\n#### 클래스 규칙 6: 연산자 오버로딩(Operator Overloading)\n\n- 연산자 오버로딩은 **직관적이고, 일관되며, 놀랍지 않을 때만** 사용하십시오.\n- 수학적 타입(복소수, 행렬)이나 스마트 포인터와 같이 잘 알려진 관용구에 대해\n 제한적으로 허용됩니다.\n- 오버로딩된 연산자의 의미는 내장 타입의 연산자 의미와 일치해야 합니다(예: `+`는\n 덧셈).\n- 부수 효과가 있는 연산자 오버로딩은 금지됩니다.\n\n```cpp\n// GOOD: 수학적 타입에 대한 연산자 오버로딩\nclass Complex {\n public:\n Complex& operator+=(const Complex& rhs);\n // ...\n};\n\ninline Complex operator+(Complex lhs, const Complex& rhs) {\n lhs += rhs;\n return lhs;\n}\n\n// BAD: 직관적이지 않은 오버로딩\nclass Person {\n public:\n // '<<'가 무엇을 하는지 명확하지 않음 (이름 추가? 데이터 전송?)\n Person& operator<<(const std::string& name);\n};\n```\n\n#### 클래스 규칙 7: 접근 제어(Access Control)\n\n- **클래스의 데이터 멤버는 항상 `private`으로 선언하십시오**.\n- `protected`는 신중하게 사용하십시오. `protected` 멤버는 파생 클래스를 위한\n API의 일부가 되어 캡슐화를 약화시킬 수 있습니다.\n- `struct`를 제외하고 `public` 멤버 변수 사용은 금지됩니다.\n\n```cpp\n// GOOD\nclass MyClass {\n public:\n int GetValue() const { return value_; }\n private:\n int value_;\n};\n\n// BAD\nclass MyClass {\n public:\n int value_; // 데이터 멤버를 public으로 노출\n};\n```\n\n#### 클래스 규칙 8: 선언 순서\n\n- 일관성을 유지하기 위해 클래스 내 선언을 다음 순서로 그룹화하십시오:\n 1. `public:` 섹션: 타입, 상수, 생성자, 소멸자, public 멤버 함수.\n 2. `protected:` 섹션.\n 3. `private:` 섹션: 타입, 상수, private 멤버 함수, 데이터 멤버.\n- 이 순서는 독자가 클래스의 public 인터페이스를 먼저 이해하는 데 도움이 됩니다.\n\n```cpp\n// GOOD\nclass MyClass {\n public:\n // 1. 타입, 상수\n using Ptr = std::unique_ptr;\n static constexpr int kDefaultValue = 0;\n\n // 2. 생성자, 소멸자, 팩토리 함수\n MyClass();\n ~MyClass();\n static Ptr Create();\n\n // 3. Public 메서드\n void DoSomething();\n\n protected:\n // ...\n\n private:\n // 4. Private 멤버 함수\n void HelperFunction();\n\n // 5. 데이터 멤버\n int value_;\n};\n```\n\n```\n\n---\n\n### 4단계: 함수 설계 규칙(매개변수 전달, 길이) 정의\n\n#### 1. 함수 설계 규칙 추가\n\n이 작업은 깔끔하고 예측 가능하며 유지보수 가능한 함수를 만드는 데 초점을 맞춘 \"함수(Functions)\" 섹션을 추가합니다. 이 규칙들은 함수 입력과 출력에 대한 명확한 계약(반환 값과 포인터 기반 출력 매개변수 선호)을 수립하고, 짧고 단일 책임 원칙을 따르는 함수를 권장하며, 모호성과 예기치 않은 동작을 피하기 위해 함수 오버로딩과 기본 인자의 신중한 사용에 대한 지침을 제공합니다.\n\n**파일**: `guidelines/cpp/coding_style.md`\n\n```markdown\n...\n // 5. 데이터 멤버\n int value_;\n};\n```\n\n---\n\n### 4.4 함수(Functions)\n\n#### 함수 규칙 1: 입력과 출력\n\n- **출력은 반환 값으로 반환하는 것을 선호하십시오.** C++11의 이동 의미론과 컴파일러\n 최적화(NRVO) 덕분에 값으로 반환하는 성능 비용이 크게 줄었습니다.\n- **매개변수 순서**는 **입력 -> 입/출력 -> 출력**이어야 합니다.\n- **매개변수 타입 가이드**:\n - **입력**: 값(`T`) 또는 `const` 참조(`const T&`). 작거나 복사 비용이 저렴한\n 타입은 값으로 전달하십시오.\n - **입/출력/출력**: `T*`를 사용하십시오. 포인터를 사용하면 호출자에게 값이\n 수정될 수 있음을 명확히 합니다. `nullptr`가 유효한 값이 아닌 경우 `T&`를\n 사용할 수 있습니다.\n\n```cpp\n// GOOD: 입력 -> 출력 순서, 포인터를 통한 출력\nvoid Parse(std::string_view src, std::string* out);\n\n// BAD: 출력 매개변수가 먼저 옴\nvoid Parse(std::string* out, std::string_view src);\n\n```\n\n#### 함수 규칙 2: 짧은 함수 작성\n\n- 함수는 **작고 단일 작업에 집중**해야 합니다.\n- 함수가 20-40줄(주석 및 빈 줄 제외)을 초과하면 분할할 수 있는지 고려하십시오.\n- **근거**: 작은 함수는 이해, 테스트, 재사용이 더 쉽습니다. 복잡한 로직을 여러\n 작은 함수로 나누면 각 함수의 역할이 명확해지고 코드 응집도가 높아집니다.\n\n```cpp\n// BAD: 단일 함수가 유효성 검사, 필터링, 합산, 결과 저장 등 여러 작업을 수행\nvoid ProcessData(const std::vector& data) {\n // 1. 유효성 검사\n for (int value : data) {\n if (value < 0) {\n // 오류 처리\n return;\n }\n }\n\n // 2. 필터링\n std::vector filtered_data;\n for (int value : data) {\n if (value > 0) {\n filtered_data.push_back(value);\n }\n }\n\n // 3. 합산\n int sum = 0;\n for (int value : filtered_data) {\n sum += value;\n }\n\n // 4. 결과 저장\n SaveResult(sum);\n}\n\n// GOOD: 각 함수가 뚜렷한 작업으로 분리됨\nbool ValidateData(const std::vector& data) {\n for (int value : data) {\n if (value < 0) return false;\n }\n return true;\n}\n\nstd::vector FilterData(const std::vector& data) {\n std::vector filtered_data;\n for (int value : data) {\n if (value > 0) {\n filtered_data.push_back(value);\n }\n }\n return filtered_data;\n}\n\nint CalculateSum(const std::vector& data) {\n int sum = 0;\n for (int value : data) {\n sum += value;\n }\n return sum;\n}\n\nvoid ProcessData(const std::vector& data) {\n if (!ValidateData(data)) {\n return;\n }\n const auto filtered_data = FilterData(data);\n const int sum = CalculateSum(filtered_data);\n SaveResult(sum);\n}\n```\n\n#### 함수 규칙 3: 함수 오버로딩(Function Overloading)\n\n- **함수 오버로딩은 다른 타입의 인자에 대해 동일한 의미의 작업을 수행할 때만\n 사용하십시오.**\n- 호출자는 오버로딩된 함수 간의 차이점을 명확하게 이해할 수 있어야 합니다 (예:\n `Analyze(string_view)` vs `Analyze(span)`).\n- `std::string_view`나 `std::span`과 같은 추상화 타입을 사용하여 인자 타입만으로\n 오버로딩하는 것을 피하는 것이 좋습니다.\n\n#### 함수 규칙 4: 기본 인자(Default Arguments)\n\n- **기본 인자는 신중하게 사용하고 비가상 함수에서만 사용하십시오.**\n- 기본 인자는 항상 동일하며 호출 사이트의 컨텍스트에 의존하지 않을 때만 사용해야\n 합니다.\n- **비가상 함수에서만 기본 인자를 사용하십시오.** 기본 인자는 정적 타입에 바인딩되므로\n 동적 디스패치와 함께 사용하면 예기치 않은 동작을 유발할 수 있습니다.\n\n```cpp\n// GOOD: 비가상 함수에서의 기본 인자\nvoid Log(std::string_view msg, LogLevel level = LogLevel::kInfo);\n\n// BAD: 가상 함수에서의 기본 인자\nclass Base {\n public:\n virtual void Process(int value = 10) = 0;\n};\n\nclass Derived : public Base {\n public:\n void Process(int value = 20) override; // 호출 사이트에 따라 기본값이 달라져 혼란을 유발\n};\n```\n\n#### 함수 규칙 5: 후행 반환 타입 구문\n\n- **기본적으로는 전통적인 반환 타입 구문을 사용하십시오.**\n- **후행 반환 타입(`auto ... -> Type`)**은 제한된 목적에만 사용하십시오:\n 1. 람다 표현식에서 반환 타입을 명시적으로 지정해야 할 때.\n 2. 반환 타입이 매개변수에 의존하는 복잡한 템플릿 함수에서 가독성을 향상시키기\n 위해.\n\n```cpp\n// GOOD: 템플릿에 의존적인 반환 타입\ntemplate \nauto Add(T t, U u) -> decltype(t + u);\n\n// GOOD: 람다의 반환 타입을 명시적으로 지정\nauto my_lambda = [](int x) -> double { return x * 1.5; };\n```\n\n```\n\n---\n\n### 5단계: 메모리 관리, 타입, 제어 흐름에 대한 모범 사례 정의\n\n#### 1. 주석, 예외, 모범 사례에 대한 섹션 추가\n\n이 마지막 작업은 여러 중요한 주제에 대한 포괄적인 가이드라인을 추가하여 문서를 완성합니다. 주석 표준(API용 Doxygen 포함)을 정의하고, 예외 처리에 대한 보수적인 접근 방식(오류 값 선호)을 수립하며, 최신 C++ 관용구에 대한 모범 사례를 자세히 설명합니다. 이러한 사례는 스마트 포인터를 사용한 RAII, `const`/`constexpr`의 올바른 사용, `auto`의 신중한 사용, 안전한 캐스팅, 적절한 제어 흐름 구조를 다루어 개발자가 안전하고 효율적이며 이식성 있는 코드를 작성하도록 보장합니다.\n\n**파일**: `guidelines/cpp/coding_style.md`\n\n```markdown\n...\nauto my_lambda = [](int x) -> double { return x * 1.5; };\n```\n\n### 4.5 주석(Comments)\n\n#### 주석 규칙 1: 주석 스타일\n\n- **`//` 스타일 주석을 사용하십시오.** C 스타일 `/* ... */` 주석은 파일 상단의\n 저작권 정보나 주석 처리된 코드 블록을 제외하고는 사용하지 마십시오.\n- 주석은 명확하고 전문적인 문장으로 작성하고 마침표로 끝나야 합니다.\n\n#### 주석 규칙 2: 주석 대상\n\n- 주석은 코드가 **'무엇을' 하는지가 아니라 '왜' 그렇게 하는지를 설명**해야 합니다.\n 코드 자체는 동작을 명확하게 보여주어야 합니다.\n- **함수 주석**: public API 함수의 선언부에서 함수가 하는 일, 인자의 의미와 제약\n 조건, 반환 값을 상세히 설명하십시오. 복잡한 내부 동작이나 부수 효과가 있다면 명시하십시오.\n- **클래스 주석**: 클래스의 역할과 책임, 사용 예시, 스레드 안전성을 설명하십시오.\n- **변수 주석**: 중요한 멤버 변수나 전역 상수의 목적과 의미를 설명하십시오.\n- **구현 주석**: 코드 블록에서 까다로운 부분이나 복잡한 알고리즘을 설명하십시오.\n 최적화를 위해 의도적으로 복잡하게 작성된 코드에는 반드시 주석을 추가해야 합니다.\n\n```cpp\n// GOOD: 설계 의도를 설명하는 주석\n// 데이터가 정렬되어 있고 평균 검색 성능이 O(log n)으로 매우 빠르기 때문에\n// 이진 검색을 사용함.\nint value = binary_search(data, key);\n\n// BAD: 코드를 그대로 설명하는 불필요한 주석\n// i를 1 증가시킴.\ni++;\n```\n\n#### 주석 규칙 3: TODO 주석\n\n- `TODO` 주석은 임시 코드, 단기적인 해결책, 또는 개선이 필요한 부분을 표시하는 데\n 사용됩니다.\n- **`TODO(username): message` 형식을 따르십시오.** `username`은 담당자의\n 식별자이며, `message`는 해야 할 일을 설명합니다.\n\n```cpp\n// TODO(movingChurch): 이 부분은 향후 더 효율적인 알고리즘으로 교체해야 함.\n```\n\n#### 주석 규칙 4: 공개 API를 위한 Doxygen\n\n- 모든 공개 API(헤더 파일에 선언된 클래스, 함수, 상수 등)는 API 문서화를\n 지원하기 위해 **Doxygen** 스타일 주석을 가져야 합니다.\n- `@brief`, `@param`, `@return`, `@details`와 같은 태그를 사용하여 API의 사용법과\n 동작을 명확하게 설명하십시오.\n\n```cpp\n/**\n * @brief 사용자의 프로필 정보를 업데이트합니다.\n * @details 이 함수는 데이터베이스에 접근하여 사용자 프로필을 업데이트합니다.\n * 네트워크 지연이 발생할 수 있습니다.\n * @param user_id 업데이트할 사용자의 고유 ID.\n * @param profile 새로운 프로필 정보.\n * @return 성공 시 true, 데이터베이스 오류가 있거나 사용자를 찾을 수 없으면 false.\n */\nbool UpdateUserProfile(int user_id, const UserProfile& profile);\n```\n\n### 4.6 예외 처리(Exception Handling)\n\n- **예외는 권장되지 않습니다.**\n- 예외는 **정말로 예외적인 상황**, 즉 프로그램이 정상적인 흐름을 계속할 수 없는\n 치명적인 오류에만 사용해야 합니다.\n- 제어 흐름의 일부로 예외를 사용해서는 안 됩니다.\n\n#### 예외 규칙 1: 예외의 사용\n\n- **장점**:\n - 예외는 일반적인 코드 흐름과 오류 처리 코드를 분리하여 가독성을 향상시킬 수\n 있습니다.\n - 함수 호출 스택을 풀면서 오류를 적절한 핸들러에서 처리할 수 있게 합니다.\n- **단점**:\n - 예외가 발생하면 코드의 실행 경로를 추적하기 어려워집니다.\n - 예외 안전성을 보장하는 코드를 작성하는 것은 복잡하고 어렵습니다(RAII 패턴이\n 필수적).\n - 성능에 민감한 코드에서 예외 처리 비용은 부담이 될 수 있습니다.\n\n#### 예외 규칙 2: `noexcept`\n\n- **예외를 던지지 않는 함수는 `noexcept`로 지정**하는 것을 강력히 권장합니다.\n- `noexcept`는 컴파일러가 더 나은 최적화를 수행하는 데 도움을 주고 API 사용자에게\n 함수가 예외를 던지지 않음을 명확히 알려줍니다.\n- 이동 생성자, 이동 할당 연산자, 소멸자는 반드시 `noexcept`여야 합니다.\n\n```cpp\n// GOOD\nvoid MyFunction() noexcept {\n // ...\n}\n```\n\n#### 예외 규칙 3: 오류 처리 방법\n\n- 예외 대신 **오류를 값으로 반환하는 것을 선호**하십시오.\n - **`std::optional`**: 값이 없을 수 있을 때 사용합니다(예: 객체 검색 실패).\n - **`std::pair` 또는 `struct`**: 성공/실패 상태와 함께 값을 반환합니다.\n - **`std::variant`** (C++17 이상): 성공 값 또는 다양한 오류 코드를\n 나타내는 데 유용합니다.\n - **상태 코드**: 명시적인 enum을 사용하여 오류 상태를 정의하고 반환합니다.\n\n```cpp\n// GOOD: std::optional을 사용한 오류 처리\nstd::optional FindUser(int user_id) noexcept;\n\nif (auto user = FindUser(123)) {\n // 성공\n ProcessUser(*user);\n} else {\n // 실패\n LogError(\"User not found\");\n}\n```\n\n---\n\n## 5. 모범 사례(Best Practices)\n\n설명: 다음은 최신 C++ 기능을 효과적으로 사용하고 일반적인 함정을 피하기 위한 모범 사례입니다.\n\n### 5.1 메모리 및 리소스 관리\n\n#### 모범 사례 1: 스마트 포인터를 사용해 소유권 명확화\n\n- **규칙**: `new`와 `delete`를 직접 사용하는 대신, `std::unique_ptr`, `std::shared_ptr`, `std::weak_ptr`와 같은 스마트 포인터를 사용하여 리소스 소유권을 명확히 표현하십시오. RAII(Resource Acquisition Is Initialization) 패턴을 적극적으로 활용하여 리소스 누수를 방지하십시오.\n- **근거**: 스마트 포인터는 객체의 생명주기를 자동으로 관리하여 메모리 누수나 이중 해제와 같은 일반적인 버그를 방지하고 코드 안정성을 높입니다.\n- **세부 사항**:\n - `std::unique_ptr`: 유일한 소유권을 표현할 때 사용합니다.\n - `std::shared_ptr`: 공유 소유권이 필요할 때 사용하되, 순환 참조 문제를 피하기 위해 `std::weak_ptr`와 함께 사용합니다.\n - 객체 생성 시 `std::make_unique`와 `std::make_shared` 사용을 권장합니다.\n\n```cpp\n// GOOD: 스마트 포인터 사용\nvoid ProcessWidget(std::unique_ptr widget) { /* ... */ }\n\nauto widget = std::make_unique();\nProcessWidget(std::move(widget)); // 소유권 이전\n\n// BAD: new/delete 직접 사용\nWidget* raw_ptr = new Widget();\nProcessWidget(raw_ptr); // 컴파일 오류, 소유권 이전이 명시적이지 않음\ndelete raw_ptr; // 잊기 쉬움\n```\n\n### 5.2 타입과 선언\n\n#### 모범 사례 2: `const`와 `constexpr`의 적극적인 사용\n\n- **규칙**: 변경되지 않는 데이터는 `const`로 선언하고, 컴파일 타임에 결정될 수 있는 상수는 `constexpr`로 선언하십시오. 멤버 함수가 객체의 논리적 상태를 변경하지 않는다면 `const` 한정자를 붙이십시오.\n- **근거**: 불변성을 명시하면 코드의 의도가 명확해지고 컴파일러가 오류를 찾거나 최적화를 수행하는 데 도움이 됩니다.\n\n```cpp\n// GOOD\nconstexpr int kMaxBufferSize = 1024;\nconst std::string kDefaultUserName = \"guest\";\n\nclass DataProcessor {\n public:\n int GetRecordCount() const; // 객체의 상태를 변경하지 않음\n private:\n std::vector records_;\n};\n```\n\n#### 모범 사례 3: 타입 추론(`auto`)은 가독성을 향상시킬 때만 사용\n\n- **규칙**: 반복자나 복잡한 템플릿 타입처럼 타입 이름이 길고 명백할 때 코드를 간결하게 만들기 위해 `auto`를 사용하십시오. 초기화 표현식만으로 타입을 명확히 알 수 없는 경우에는 `auto` 사용을 피하고 타입을 명시적으로 작성하십시오.\n- **근거**: `auto`의 남용은 코드 명확성을 해치고 API의 의도를 파악하기 어렵게 만들 수 있습니다.\n\n```cpp\n// GOOD: 반복자나 복잡한 타입에 사용\nstd::map> my_map;\nfor (auto it = my_map.cbegin(); it != my_map.cend(); ++it) {\n // ...\n}\n\n// BAD: 타입이 명확하지 않을 때\nauto result = GetResult(); // GetResult()의 반환 타입이 불분명함\n\n// GOOD: 명확성을 위해 타입을 명시\nint result = GetResult();\n```\n\n#### 모범 사례 4: C 스타일 캐스트 대신 C++ 캐스트 사용\n\n- **규칙**: C 스타일 캐스트(`(type)value`)는 의도가 불분명하고 위험하므로 사용을 금지합니다. 대신 `static_cast`, `const_cast`, `reinterpret_cast`, `dynamic_cast`와 같이 목적에 맞는 C++ 캐스트를 사용하십시오.\n- **근거**: C++ 캐스트는 캐스팅의 의도를 명확하게 드러내고 컴파일 타임에 더 안전한 타입 검사를 제공합니다.\n\n```cpp\n// GOOD\nfloat value = 3.14f;\nint integer_value = static_cast(value);\n\nconst char* c_str = \"hello\";\nchar* non_const_str = const_cast(c_str);\n\n// BAD\nint another_value = (int)value; // C 스타일 캐스트\n```\n\n#### 모범 사례 5: 고정 너비 정수 타입 사용\n\n- **규칙**: 플랫폼에 따라 크기가 달라질 수 있는 `int`, `long` 대신, 보장된 크기가 필요할 때는 ``의 `int32_t`, `uint64_t` 등을 사용하십시오.\n- **근거**: 고정 너비 정수 타입은 코드의 이식성과 명확성을 향상시킵니다.\n\n```cpp\n// GOOD\n#include \n\nint64_t large_value = 1'000'000'000;\n\n// BAD\nlong long ambiguous_value = 1'000'000'000; // 플랫폼에 따라 크기가 달라질 수 있음\n```\n\n### 5.3 제어 흐름\n\n#### 모범 사례 6: 범위 기반 for 루프 사용\n\n- **규칙**: 컨테이너의 모든 요소를 순회할 때는 인덱스 기반 `for` 루프 대신 범위 기반 `for` 루프를 사용하십시오.\n- **근거**: 코드를 더 간결하게 만들고 반복자나 인덱스 관리에서 발생할 수 있는 오류를 줄여줍니다.\n\n```cpp\n// GOOD\nstd::vector numbers = {1, 2, 3, 4, 5};\nfor (int number : numbers) {\n std::cout << number;\n}\n\n// BAD\nfor (auto it = numbers.begin(); it != numbers.end(); ++it) {\n std::cout << *it;\n}\n```\n\n#### 모범 사례 7: `switch` 문은 `default`를 포함하고 모든 `case`를 처리해야 함\n\n- **규칙**: `switch` 문은 항상 `default` 레이블을 포함해야 합니다. `enum class`와 함께 사용할 때는 모든 열거자를 처리하는 것을 원칙으로 하며, 의도적인 fallthrough에는 `[[fallthrough]]` 속성을 명시해야 합니다.\n- **근거**: 모든 경우를 처리하도록 강제하여 버그를 줄이고 의도하지 않은 fallthrough를 방지합니다.\n\n```cpp\nenum class Color { kRed, kGreen, kBlue };\n\nvoid HandleColor(Color color) {\n switch (color) {\n case Color::kRed:\n // ...\n break;\n case Color::kGreen:\n // ...\n break;\n case Color::kBlue:\n // ...\n break;\n default: // 모든 enum 값을 처리하더라도 default는 필수\n // 이 경우는 발생해서는 안 됨\n assert(false);\n }\n}\n```\n\n### 5.4 기타 주제\n\n#### 모범 사례 8: 전처리기 매크로 사용 최소화\n\n- **규칙**: 매크로 대신 `constexpr` 변수, 인라인 함수, 템플릿 등을 사용하십시오. 매크로는 네임스페이스와 스코프를 무시하여 예기치 않은 문제를 일으킬 수 있습니다.\n- **근거**: 디버깅을 어렵게 만들고 이름 충돌과 같은 부수 효과를 일으킬 수 있습니다.\n\n```cpp\n// GOOD\nconstexpr int kMaxItems = 100;\ntemplate T Max(T a, T b) { return a > b ? a : b; }\n\n// BAD\n#define MAX_ITEMS 100\n#define MAX(a, b) ((a) > (b) ? (a) : (b)) // 부수 효과 위험\n```\n\n#### 모범 사례 9: RTTI(Run-Time Type Information) 사용 지양\n\n- **규칙**: 단위 테스트와 같은 제한된 경우를 제외하고 `typeid`와 `dynamic_cast` 같은 RTTI 기능 사용을 피하십시오.\n- **근거**: RTTI 사용은 종종 설계 결함을 나타냅니다. 타입에 따른 분기가 필요하다면 가상 함수나 방문자 패턴(Visitor pattern)과 같은 다형적 설계를 고려하는 것이 좋습니다.\n\n```cpp\n// BAD: RTTI 사용\nvoid ProcessShape(Shape* shape) {\n if (auto* circle = dynamic_cast(shape)) {\n // Circle 처리\n } else if (auto* square = dynamic_cast(shape)) {\n // Square 처리\n }\n}\n\n// GOOD: 가상 함수 사용 (다형적 설계)\nclass Shape {\n public:\n virtual ~Shape() = default;\n virtual void Draw() const = 0;\n};\n\nclass Circle : public Shape {\n public:\n void Draw() const override { /* ... */ }\n};\n\nvoid ProcessShape(const Shape& shape) {\n shape.Draw();\n}\n```\n\n#### 모범 사례 10: Boost 라이브러리 신중하게 사용\n\n- **규칙**: Boost 라이브러리는 표준 라이브러리로 대체할 수 없는 기능이 필요할 때만 사용하십시오.\n- **근거**: 외부 의존성을 최소화하고 코드 이식성을 높이기 위해 표준 라이브러리를 우선적으로 사용하십시오.\n\n```cpp\n// GOOD: 표준 라이브러리에 기능이 존재할 때\n#include // C++17\nnamespace fs = std::filesystem;\nfs::path p(\"/path/to/file\");\n\n// BAD: 표준 라이브러리로 대체 가능한데 Boost를 사용할 때\n#include \nnamespace fs = boost::filesystem;\nfs::path p(\"/path/to/file\");\n\n// GOOD: 표준 라이브러리에 없는 기능이 필요할 때\n#include // UUID 기능은 표준에 없음\n#include \nboost::uuids::uuid u = boost::uuids::random_generator()();\n```\n\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n- 개발자는 작업이 완료되고 정확한지 확인하기 위해 다음 작업을 수행해야 합니다.\n\n```bash\n# 1. 새 문서가 존재하는지 확인합니다.\nls guidelines/cpp/coding_style.md\n\n# 2. 프로젝트의 포맷팅 스크립트를 실행하여 새 마크다운 파일이\n# 리포지토리의 스타일 표준을 준수하는지 확인합니다. 이 스크립트는\n# 프로젝트 블루프린트에서 실행 진입점으로 정의되어 있습니다.\nscripts/executables/run_formatters.sh\n```\n\n### 4.2. 예상 결과\n\n- 검증 절차를 실행한 후, `ls` 명령어는 파일을 성공적으로 나열해야 합니다. `run_formatters.sh` 스크립트는 오류 없이 실행되어야 하며, 새 `coding_style.md` 문서를 포함한 모든 파일이 올바르게 포맷되었다고 보고해야 합니다.\n\n```\nguidelines/cpp/coding_style.md\n\n[Prettier] 마크다운 파일 포맷팅 중...\n[Prettier] 모든 파일이 올바르게 포맷되었습니다.\n[markdownlint] 마크다운 파일 린팅 중...\n[markdownlint] 모든 파일이 린팅을 통과했습니다.\n포맷터가 성공적으로 실행되었습니다.\n```","헤더, 범위, 클래스, 함수, 모범 사례에 대한 규칙을 정의하는 `coding_style.md` 파일",[354,357,359,361,363],{"_24":355,"_83":39,"_84":356,"_85":61},"헤더 파일 규칙 문서화 (자체 포함, include 순서)",15,{"_24":358,"_83":39,"_84":356,"_85":88},"스코프 규칙 정의 (네임스페이스, 지역 변수)",{"_24":360,"_83":39,"_84":356,"_85":91},"클래스 설계 가이드라인 (생성자, 상속, 연산자)",{"_24":362,"_83":39,"_84":356,"_85":94},"함수 설계 규칙 (파라미터 전달, 길이)",{"_24":364,"_83":39,"_84":356,"_85":97},"메모리 관리, 타입, 제어 흐름에 대한 모범 사례","현대적인 관행과 도구에 기반한 포괄적인 C++ 스타일 가이드 문서를 작성",{"_22":367,"_24":368,"_75":369,"_77":370,"_79":371,"_51":383,"_42":99},"task-1751363856268","C++ 이름 및 서식 가이드","# 작업: C++ 네이밍 및 포매팅 가이드\n\n> **에픽**: C++ 코딩 및 포매팅 가이드라인 개발\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: C++의 모든 네이밍 및 포매팅 컨벤션을 성문화한 문서를 작성합니다.\n- **근거**: 이 문서는 프로젝트의 자동화된 도구(`.clang-format`)가 강제하는 C++ 스타일에 대해 사람이 읽을 수 있는(human-readable) 참조를 제공합니다. 규칙의 배경이 되는 '이유'를 설명하고, 명확한 예시를 제공하며, 개발자를 위한 학습 가이드 역할을 합니다. 이를 통해 전체 코드베이스에서 일관되고 가독성 있는 코드를 보장합니다. 이는 언어별 가이드라인을 공식화하려는 프로젝트의 핵심 목표와 일치합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: `.clang-format` 파일의 컨벤션을 요약하고 명확한 예시를 제공하는 `formatting.md` 파일.\n- **명세**:\n - **생성 파일**: `guidelines/cpp/formatting.md`\n - **내용 섹션**:\n - `.clang-format`을 단일 진실 공급원(source of truth)으로 확립하는 최상위 요약.\n - 모든 네이밍 컨벤션에 대한 요약 테이블.\n - 근거와 코드 예시를 포함한 특정 네이밍 규칙에 대한 상세 섹션.\n - 근거와 코드 예시를 포함한 주요 포매팅 규칙 목록.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── guidelines/\n# └── cpp/\n# └── formatting.md <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 개발자가 자동화 도구와 함께 개발 워크플로우에서 `formatting.md` 가이드를 어떻게 사용하는지 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"개발자 워크플로우\"\n Dev[\"개발자\"]\n Code[\"C++ 코드
작성/수정\"]\n Formatters[\"로컬 포매터 실행
(clang-format)\"]\n end\n \n subgraph \"지식 베이스 (리포지토리)\"\n FormattingDoc[\"guidelines/cpp/formatting.md\"]\n ClangFormat[\" .clang-format \"]\n end\n\n subgraph \"검증\"\n CI[\"CI 파이프라인\"]\n end\n\n Dev -- \"명확화를 위해 참고\" --> FormattingDoc;\n FormattingDoc -- \"다음을 위한
Human-Readable 가이드\" --> ClangFormat;\n Dev --> Code;\n Code -- \"다음에 의해 포매팅됨\" --> Formatters;\n Formatters -- \"다음에 의해 설정됨\" --> ClangFormat;\n Dev -- \"코드 커밋\" --> CI;\n CI -- \".clang-format을
사용하여 검증\" --> Dev;\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 상세 구현은 섹션 3에 있습니다.\n\n- [ ] 모든 코드 요소에 대한 네이밍 컨벤션 요약 테이블.\n- [ ] 네이밍 컨벤션에 대한 상세 규칙 및 근거.\n- [ ] `.clang-format`에서 파생된 주요 포매팅 규칙 요약.\n- [ ] 함수 정의, 호출, 제어 구조에 대한 명확한 good/bad 코드 예시.\n- [ ] `.clang-format` 파일을 단일 진실 공급원으로 참조.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 리포지토리\n- **관련된 주요 컴포넌트**:\n - **언어 가이드라인**: 이 작업은 핵심 C++ 가이드라인 문서를 생성합니다. 이는 이 컴포넌트의 책임을 직접적으로 구현하는 것입니다.\n - **자동화 도구**: 이 문서는 이 컴포넌트의 일부인 `.clang-format` 설정에 의해 강제되는 규칙에 대한 사람이 읽을 수 있는 명세서 역할을 합니다. 이 문서의 주요 목적은 개발자들이 자동화된 도구에 맞춰 작업하도록 하는 것입니다.\n - **엔지니어링 원칙**: 이 작업에서 문서화된 네이밍 및 포매팅 규칙은 `principles/` 디렉토리에 정의된 가독성 및 일관성과 같은 상위 수준의 언어에 구애받지 않는 원칙들의 구체적인 구현입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `guidelines/cpp/formatting.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공하게 됩니다.\n\n---\n\n### 단계 1: `.clang-format` 파일을 단일 진실 공급원으로 참조\n\n#### 1. 파일 생성 및 헤더 추가\n\n이 액션은 문서를 만들고, 자동화된 포매팅 도구인 `clang-format`이 절대적인 진실 공급원이라는 핵심 원칙을 확립합니다. 이 서문은 모호함을 방지하고 개발자에게 최종 설정을 위해 설정 파일을 참조하도록 안내하여 프로젝트의 '자동화 우선' 접근 방식을 강화합니다. 새 파일을 만들고 헤더, 설명 및 목차를 추가합니다.\n\n**파일**: `guidelines/cpp/formatting.md`\n\n```markdown\n# C++ 네이밍 및 포매팅 규칙\n\n버전 v1.0.0 생성일 2025-06-30 소유자 @movingChurch\n\n---\n\n> **설명**: 코드 포매팅은 `clang-format`을 통해 자동으로 검증됩니다.\n> 모든 코드는 프로젝트에 정의된 포매팅 규칙을 따라야 합니다. **포매터의\n> 결과는 항상 사람의 판단보다 우선합니다.**\n>\n> **설정**: 포매팅 설정은 `assets/.clang-format` 파일에 정의되어 있습니다.\n> 다음 규칙들은 해당 설정의 주요 내용을 설명합니다.\n\n---\n\n## 1. 목차\n\n1. [네이밍 컨벤션](#2-네이밍-컨벤션)\n2. [포매팅 규칙](#3-포매팅-규칙)\n\n---\n```\n\n---\n\n### 단계 2: 모든 코드 요소에 대한 네이밍 컨벤션 요약 테이블\n\n#### 1. 네이밍 컨벤션 섹션 및 요약 테이블 추가\n\n이 액션은 \"네이밍 컨벤션\" 섹션을 만들고 요약 테이블을 추가합니다. 이 테이블은 빠른 참조 가이드 역할을 하여, 개발자가 상세한 설명을 읽지 않고도 주어진 코드 요소에 대한 올바른 네이밍 스타일을 신속하게 찾을 수 있게 합니다. 이는 개발자 생산성을 향상시키고 일관성을 강화합니다.\n\n**파일**: `guidelines/cpp/formatting.md`\n\n```markdown\n...\n---\n\n## 2. 네이밍 컨벤션\n\n### 2.1 요약 테이블\n\n| 코드 요소 | 네이밍 스타일 | 예시 |\n| ----------------------------- | ---------------------- | ------------------------------------------ |\n| `file` | `snake_case` | `feature_detector.cpp` |\n| `type` | `PascalCase` | `class FeatureDetector;` |\n| `variable::basic` | `snake_case` | `uint32_t feature_size;` |\n| `variable::class_member` | `snake_case_` | `uint32_t feature_size_;` |\n| `variable::struct_member` | `snake_case` | `double point_x;` |\n| `constant` | `PascalCase` | `const auto OriginX{0.0};` |\n| `global/member/static constant` | `kPascalCase` | `constexpr int kMaxConnections = 10;` |\n| `function` | `PascalCase` | `double Multiply(double lhs, double rhs);` |\n| `method` | `PascalCase` | `int64_t GetCurrentTime();` |\n| `namespace` | `snake_case` | `namespace sensor::lidar { ... }` |\n| `enumerator` | `kPascalCase` | `enum class TimeScale { kNano, kMilli };` |\n| `macro` | `SCREAMING_SNAKE_CASE` | `#define MAX_BUFFER_SIZE 1024` |\n\n...\n```\n\n---\n\n### 단계 3: 네이밍 컨벤션에 대한 상세 규칙 및 근거\n\n#### 1. 근거와 함께 상세 네이밍 규칙 추가\n\n이 액션은 주요 네이밍 컨벤션에 대한 상세한 설명을 제공합니다. 각 규칙에 대한 근거와 명확한 예시를 제공함으로써, 이 가이드는 단순한 지시를 넘어 개발자에게 가독성 있는 코드의 원칙을 교육하고, 표준에 대한 더 깊은 이해와 채택을 촉진합니다.\n\n**파일**: `guidelines/cpp/formatting.md`\n\n```markdown\n...\n### 2.2 네이밍 규칙\n\n#### 네이밍 규칙 1: 수동적 객체(존재)는 명사로, 능동적 객체는 '동사+er'로, 행위(동작)는 명령문으로 명명합니다\n\n- **범위**: 모든 식별자\n- **근거**: 역할을 기준으로 네이밍 컨벤션을 통일하면 코드의 의도를 명확하게\n 전달할 수 있습니다.\n\n```cpp\n// 좋음: 존재 (수동적 객체)\nstruct Point2D {\n double x;\n double y;\n};\n\n// 좋음: 존재 (능동적 객체)\nclass FeatureDetector {\n Feature DetectFeature();\n};\n\n// 좋음: 동작\ndouble Multiply(double lhs, double rhs);\n```\n\n### 네이밍 규칙 2: 클래스 멤버 변수에는 뒤에 밑줄 `_`을 사용합니다\n\n- **범위**: 클래스 멤버 변수\n- **근거**: 멤버 변수를 명확하게 구분하여 가독성을 향상시킵니다.\n\n```cpp\n// 좋음\nclass FeatureDetector {\nprivate:\n uint16_t feature_size_;\n};\n\n// 나쁨\nclass FeatureDetector {\nprivate:\n uint16_t m_feature_size; // 헝가리안 표기법은 사용하지 않습니다.\n};\n```\n\n### 네이밍 규칙 3: 상수에 지정된 접두사와 케이싱을 사용합니다\n\n- **범위**: `constexpr` 또는 `const` 변수\n- **근거**: 상수를 가변 변수와 명확하게 구분하여 가독성을 높이고 의도치 않은\n 수정을 방지합니다. 전역/멤버/정적 상수에 `k` 접두사를 사용하면 그 범위를\n 명확히 알 수 있습니다.\n\n```cpp\n// 좋음\n\n// 전역 상수 및 정적 멤버 상수는 kPascalCase를 사용합니다.\nconstexpr int kMaxConnections = 10;\n\nclass MyClass {\n public:\n static constexpr int kDefaultTimeoutMs = 5000;\n\n explicit MyClass(int max_retries) : kMaxRetries(max_retries) {}\n\n private:\n // 멤버 상수는 kPascalCase를 사용합니다.\n const int kMaxRetries;\n};\n\nvoid DoSomething() {\n // 지역 상수는 'k' 접두사 없이 PascalCase를 사용합니다.\n const auto OriginX{0.0};\n const int MaxIterations = 100;\n}\n```\n\n---\n\n```\n\n---\n\n### 단계 4: `.clang-format`에서 파생된 주요 포매팅 규칙 요약\n\n#### 1. 포매팅 규칙 섹션 추가\n\n이 액션은 포매팅 규칙 전용 섹션을 추가합니다. 이 규칙들은 `.clang-format` 설정에서 직접 파생된 것입니다. 이를 문서화하면 개발자들이 보게 될 자동 변경 사항에 대한 맥락과 설명을 제공하여 포매팅 과정을 투명하고 교육적으로 만듭니다.\n\n**파일**: `guidelines/cpp/formatting.md`\n\n```markdown\n...\n---\n\n## 3. 포매팅 규칙\n\n### 포매팅 규칙 1: 한 줄의 길이는 80자를 초과하지 않아야 합니다\n\n- **범위**: 모든 소스 파일\n- **근거**: 코드 가독성을 향상시키고 코드가 한 화면에 들어오도록 하여 파악하기\n 쉽게 만듭니다.\n\n### 포매팅 규칙 2: 들여쓰기에는 2개의 공백을 사용하고, 문자는 UTF-8로 인코딩합니다\n\n- **범위**: 모든 소스 파일\n- **근거**: 편집기 간의 불일치를 방지하고 문자 인코딩 문제를 피합니다.\n 탭 대신 공백을 사용하며, 1개의 들여쓰기는 2개의 공백과 같습니다.\n...\n```\n\n---\n\n### 단계 5: 함수 정의, 호출, 제어 구조에 대한 명확한 good/bad 코드 예시\n\n#### 1. 코드 구조에 대한 포매팅 규칙 추가\n\n이 액션은 일반적인 C++ 구문에 대한 특정 포매팅 규칙을 문서화합니다. 함수 정의, 호출, 루프 및 조건문에 대해 명확한 \"좋은\" 예와 \"나쁜\" 예를 제공하면 개발자에게 텍스트만으로는 파악하기 어려운 시각적 참조를 제공하여 일반적인 포매팅 오류를 방지하는 데 도움이 됩니다.\n\n**파일**: `guidelines/cpp/formatting.md`\n\n```markdown\n...\n### 포매팅 규칙 3: 함수 선언 및 정의 형식을 준수합니다\n- ... (원본의 규칙 텍스트) ...\n```cpp\n// 좋음: 일반적인 함수 정의\nReturnType ClassName::FunctionName(Type par_name1, Type par_name2) {\n DoSomething();\n ...\n}\n// ... (원본의 다른 좋은 예시들) ...\n```\n\n### 포매팅 규칙 4: 람다 표현식 형식을 준수합니다\n\n- ... (원본의 규칙 텍스트) ...\n\n```cpp\n// 좋음: 기본 람다\nint32_t x{0};\nauto x_plus_n = [&x](int32_t n) -> int32_t { return x + n; }\n// ... (원본의 다른 좋은 예시들) ...\n```\n\n### 포매팅 규칙 5: 함수 호출 형식을 준수합니다\n\n- ... (원본의 규칙 텍스트) ...\n\n```cpp\n// 좋음: 한 줄 호출\nbool result = DoSomething(argument1, argument2, argument3);\n// ... (원본의 다른 좋은 예시들) ...\n```\n\n### 포매팅 규칙 6: 루프와 조건문에는 항상 중괄호 `{}`를 사용하고 지정된 형식을 따릅니다\n\n- ... (원본의 규칙 텍스트) ...\n\n```cpp\n// 좋음\nif (condition) {\n DoOneThing();\n DoAnotherThing();\n} else if (int a = f(); a != 3) {\n DoAThirdThing(a);\n} else {\n DoNothing();\n}\n// ... (원본의 다른 좋고 나쁜 예시들) ...\n```\n\n### 포매팅 규칙 7: 포인터 및 참조 표현식의 공백 규칙을 준수합니다\n\n- ... (원본의 규칙 텍스트) ...\n\n```cpp\n// 좋음\nfloat& example_variable;\nconst auto* data = *example_class->get_status().data;\n\n// 나쁨\nfloat &example_variable;\nconst auto * data = *example_class -> get_status() . data;\n```\n\n### 포매팅 규칙 8: 생성자 초기화 목록에 지정된 형식을 따릅니다\n\n- ... (원본의 규칙 텍스트) ...\n\n```cpp\n// 좋음: 긴 초기화 목록의 경우\nMyClass::MyClass(int var)\n : some_var_(var),\n some_other_var_(var + 1) {\n DoSomething();\n}\n// ... (원본의 다른 좋은 예시들) ...\n```\n\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 이 문서의 성공적인 생성을 확인하려면, 개발자는 이 문서가 프로젝트 자체의 마크다운 포매팅 표준을 준수하는지 확인해야 합니다. 이는 로컬 포매터 스크립트를 실행하여 수행할 수 있습니다.\n\n```bash\n# 1. 프로젝트 루트 디렉토리로 이동합니다\ncd /path/to/readable-code-cpp-development-guidelines\n\n# 2. 로컬 포매터가 설치되었는지 확인합니다\n# (아직 실행하지 않았다면 로컬 설치 스크립트의 지침을 따르세요)\n\n# 3. 프로젝트의 포매터 스크립트를 실행합니다\n./scripts/executables/run_formatters.sh\n```\n\n### 4.2. 예상 결과\n\n- 스크립트는 오류 없이 실행되어야 합니다. 출력은 `prettier`가 `guidelines/cpp/formatting.md`를 확인했으며 파일이 올바르게 포매팅되었거나 수정되었음을 나타내야 합니다.\n\n```\n[INFO] Prettier 포매터 실행 중...\n[INFO] 변경된 파일 포매팅 중...\n[INFO] guidelines/cpp/formatting.md\n[SUCCESS] Prettier 포매팅 완료.\n[INFO] markdownlint 린터 실행 중...\n[INFO] 변경된 파일 린팅 중...\n[SUCCESS] markdownlint 검사 완료. 이슈가 발견되지 않았습니다.\n```","`.clang-format` 파일의 규칙을 요약하고 명확한 예제를 제공하는 `formatting.md` 파일",[372,375,377,379,381],{"_24":373,"_83":39,"_84":374,"_85":61},"모든 코드 요소에 대한 이름 규칙 요약 표",16,{"_24":376,"_83":39,"_84":374,"_85":88},"이름 규칙에 대한 상세 규칙 및 근거",{"_24":378,"_83":39,"_84":374,"_85":91},"`.clang-format`에서 파생된 주요 서식 규칙 요약",{"_24":380,"_83":39,"_84":374,"_85":94},"함수 정의, 호출, 제어 구조에 대한 명확한 좋고 나쁜 코드 예제",{"_24":382,"_83":39,"_84":374,"_85":97},"단일 진실 공급원으로서의 `.clang-format` 파일 참조","C++의 모든 이름 및 서식 규칙을 코드화한 문서를 작성",{"_22":385,"_24":386,"_75":387,"_77":388,"_79":389,"_51":401,"_42":99},"task-1751363907542","C++ 테스팅 계획 및 가이드라인","# 작업: C++ 테스트 계획 및 가이드라인\n\n> **Epic**: C++ 테스트 및 Doxygen 가이드라인 개발\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 프로젝트의 C++ 테스트 전략, 도구 및 모범 사례를 정의합니다.\n- **근거**: 이 작업은 모든 기여가 일관성 있고 유지보수 가능하며 높은 품질 표준을 준수하도록 C++ 테스트 전략을 공식화합니다. 테스트 환경, 방법론, 코드 커버리지와 같은 품질 게이트를 성문화함으로써 이 문서는 강제력 있는 표준이 되며, 이는 이 가이드라인을 사용하여 개발된 모든 소프트웨어의 장기적인 건전성과 신뢰성에 매우 중요합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: 테스트 유형, 명명 규칙, 품질 표준을 설명하는 `test.md` 파일.\n- **세부 사양**: 최종 문서에는 다음 주요 섹션이 포함됩니다:\n - `문서 섹션: 개요`: 핵심 테스트 철학을 정의합니다.\n - `문서 섹션: 테스트 환경`: 툴체인(`Catch2`, `CTest`, `gcovr`)을 명시합니다.\n - `문서 섹션: 테스트 유형`: 테스트(단위, 통합, E2E, 런타임)를 분류합니다.\n - `문서 섹션: 테스트 케이스 작성 방법`: 명명 규칙, AAA 패턴, 단언(assertion) 사용법을 상세히 설명합니다.\n - `문서 섹션: 테스트 품질 표준`: 필수 코드 커버리지 목표를 설정합니다.\n - `문서 섹션: 고급 테스트 기법`: 모의(mocking), 데이터 기반 테스트, E2E 테스트 예제를 제공합니다.\n - `문서 섹션: 테스트 실행 방법`: 로컬 테스트 실행을 위한 CLI 명령어를 나열합니다.\n- **결과 파일 구조**\n\n```bash\n# ./guidelines/\n# └── cpp/\n# └── test.md <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 개발자가 이 가이드라인을 사용하여 C++ 테스트를 작성하고 검증할 때 따르는 워크플로우를 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n Dev[\"개발자\"] -- \"1\\. test.md 가이드라인 참고\" --> WriteTest[\"2\\. 테스트 코드 작성
(Catch2 및 AAA 패턴 사용)\"]\n WriteTest --> TestCode[\"3\\. 테스트 소스 파일
(예: my_feature_test.cpp)\"]\n Dev -- \"4\\. 'cmake --build .' 실행\" --> BuildSystem[\"5\\. 빌드 시스템 (CMake/CTest)\"]\n BuildSystem -- \"6\\. 테스트 발견 및 실행\" --> TestCode\n BuildSystem -- \"7\\. 결과 및 커버리지 보고\" --> Dev\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이는 상위 수준의 체크리스트입니다. 각 항목에 대한 상세 구현은 3절에 있습니다.\n\n- [ ] 테스트 환경(Catch2, CTest) 정의\n- [ ] 테스트 유형(단위, 통합, E2E) 분류\n- [ ] 테스트 케이스 명명 및 구조 규칙(AAA 패턴) 정의\n- [ ] 커버리지 목표를 포함한 테스트 품질 표준 정의\n- [ ] 모의(mocking) 및 데이터 기반 테스트와 같은 고급 기법 예제\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 리포지토리\n- **관련 주요 구성 요소**:\n - **언어 가이드라인**: 이 작업은 C++ 테스트 가이드라인을 직접 생성하며, 이는 이 구성 요소 내의 핵심 산출물입니다. 모든 C++ 테스트 관행에 대한 신뢰할 수 있는 단일 소스(single source of truth) 역할을 합니다.\n - **엔지니어링 원칙**: 이 가이드라인은 구체적인 테스트 표준과 관행을 정의함으로써 코드 품질, 견고성, 유지보수성에 대한 상위 수준의 원칙을 구현합니다.\n - **자동화 도구**: 이 가이드라인은 `자동화 도구` 구성 요소가 구성하고 실행할 책임이 있는 도구(`Catch2`, `CTest`, `gcovr`)와 표준(예: 커버리지 메트릭)을 정의합니다. `CTest` 실행기와 CI 파이프라인은 여기에 정의된 규칙을 사용하여 코드 기여를 검증합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `guidelines/cpp/test.md`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목과 일치합니다. 각 `단계`는 여러 개의 세부 `작업`으로 구성됩니다. 각 `작업`마다 제목과 '무엇을', '왜'를 다루는 명확한 설명, 그리고 정확한 코드 구현을 제공합니다.\n\n---\n\n### 단계 1: 테스트 환경(Catch2, CTest) 정의\n\n#### 1. 가이드라인 문서를 생성하고 테스트 환경 정의하기\n\n이 작업은 C++ 테스트 가이드라인 문서의 기초를 마련합니다. 프로젝트의 테스트 철학을 정의하고 공식 툴체인을 명시하는 것으로 시작합니다. 이를 통해 모든 개발자가 동일한 프레임워크(`Catch2`), 테스트 실행기(`CTest`), 커버리지 도구(`gcovr`)를 사용하도록 보장하며, 이는 일관성 있고 자동화된 검증을 위해 필수적입니다.\n\n**파일**: `guidelines/cpp/test.md`\n\n```markdown\n# C++ 테스트 계획 및 가이드라인\n\n버전 1.0 날짜: 2025-07-01 작성자: @movingChurch\n\n---\n\n## 1. 개요\n\n이 문서는 일관성, 가독성, 유지보수성을 보장하기 위해 C++ 테스트 코드 작성에 대한 코딩 표준과 모범 사례를 정의합니다.\n\n우리의 테스트 철학은 \"테스트는 시스템 동작의 살아있는 문서다\"입니다.\n따라서 모든 테스트는 명확하고, 읽기 쉬우며, 독립적이고, 반복 가능해야 합니다.\n\n## 2. 테스트 환경\n\n- **테스트 프레임워크**: `Catch2`\n- **테스트 실행기**: `CTest`\n- **코드 커버리지**: `gcovr`\n- **CI/CD 통합**: 빌드 중에 CMake는 자동으로 테스트를 발견하고 등록합니다. 빌드 후 명령어는 CTest를 통해 모든 등록된 테스트를 실행합니다. 코드 커버리지 분석이 활성화된 경우, `gcovr`가 실행되며 커버리지 메트릭이 요구 사항을 충족하지 못하면 빌드는 실패합니다.\n```\n\n---\n\n### 단계 2: 테스트 유형(단위, 통합, E2E) 분류\n\n#### 1. 테스트 유형 카테고리 추가하기\n\n이 작업은 명확한 카테고리를 정의하여 테스트 스위트의 구조를 잡습니다. 테스트 유형(단위, 통합, E2E, 런타임)과 위치(`tests/unit/` 등)를 명확히 정의하면 개발자가 테스트를 논리적으로 구성하고, 각 테스트의 범위를 명확히 하며, 빌드 시스템이 필요에 따라 특정 카테고리의 테스트를 실행할 수 있게 해줍니다.\n\n**파일**: `guidelines/cpp/test.md`\n\n```markdown\n...\n\n## 3. 테스트 유형\n\n### 3.1 단위 테스트\n\n- **목적**: 개별 컴포넌트나 함수를 독립적으로 검증합니다.\n- **위치**: `tests/unit/`\n- **핵심 원칙**:\n - 테스트는 독립적이고 반복 가능해야 합니다.\n - 테스트는 Arrange-Act-Assert (AAA) 패턴을 따라야 합니다.\n - 자동 발견을 위해 `TEST_CASE`의 태그는 파일명과 일치해야 합니다.\n\n### 3.2 통합 테스트\n\n- **목적**: 여러 컴포넌트가 함께 예상대로 동작하는지 검증합니다.\n- **위치**: `tests/integration/`\n- **핵심 원칙**:\n - 모듈 간의 상호작용에 중점을 둡니다.\n - 실제 데이터베이스나 외부 시스템을 사용할 수 있지만, 테스트 전용 데이터 및 환경으로 격리되어야 합니다.\n\n### 3.3 End-to-End 테스트\n\n- **목적**: 처음부터 끝까지 완전한 사용자 시나리오를 시뮬레이션합니다.\n- **위치**: `tests/e2e/`\n- **핵심 원칙**:\n - 운영 환경을 모방한 전용 테스트 환경을 사용합니다.\n - 핵심적인 사용자 워크플로우를 다룹니다.\n\n### 3.4 런타임 테스트\n\n- **목적**: 프로그램 실행 중에 발생할 수 있는 성능, 안정성, 리소스 사용량과 같은 비기능적 측면을 검증합니다.\n- **위치**: `tests/runtime/`\n- **핵심 원칙**:\n - 성능 테스트, 부하 테스트, 메모리 누수 감지를 포함합니다.\n - 특정 시나리오 하에서 시스템 동작을 측정하고 분석합니다.\n```\n\n---\n\n### 단계 3: 테스트 케이스 명명 및 구조 규칙(AAA 패턴) 정의\n\n#### 1. 명명 및 구조 규칙 명시하기\n\n이 작업은 개별 테스트 케이스 작성 규칙을 성문화합니다. 명명 규칙은 `CTest` 기반 자동 테스트 발견 시스템이 올바르게 작동하는 데 매우 중요합니다. Arrange-Act-Assert(AAA) 패턴은 모든 테스트가 일관되고, 읽기 쉬우며, 예측 가능한 구조를 갖도록 강제됩니다. 또한 이 섹션에서는 효과적인 단언(assertion)을 위해 `REQUIRE`와 `CHECK`의 사용법을 명확히 합니다.\n\n**파일**: `guidelines/cpp/test.md`\n\n```markdown\n...\n\n## 4. 테스트 케이스 작성 방법\n\n### 4.1 명명 규칙\n\n- **규칙**: 일관성을 유지하고 자동화된 테스트 등록 시스템을 지원하기 위해 아래의 명명 규칙을 따르세요.\n\n| 요소 | 형식 | 예시 |\n| :--------------- | :------------------- | :---------------------------- |\n| 테스트 파일 | `snake_case.cpp` | `my_feature.cpp` |\n| `TEST_CASE` 태그 | `[feature_path]` | `[my_feature]` |\n| `TEST_CASE` 이름 | 설명적인 문장 | `\\\"My new feature validation\\\"` |\n\n- **규칙**: `TEST_CASE` 태그는 `tests//` 디렉토리 다음의 나머지 경로를 반영해야 합니다. 예를 들어, `tests/unit/my_feature.cpp`의 태그는 `[my_feature]`가 되고, `tests/unit/core/utils.cpp`의 태그는 `[core][utils]`가 됩니다. 이는 빌드 시스템이 테스트를 자동으로 발견하고, 그룹화하며, 올바르게 실행하기 위해 **필수**입니다.\n\n### 4.2 구조 (Arrange-Act-Assert)\n\n- **Arrange**(준비): 테스트 사전 조건을 설정합니다 (예: 객체, 입력 데이터 생성).\n- **Act**(실행): 테스트할 코드를 실행합니다.\n- **Assert**(단언): 결과가 예상과 일치하는지 확인합니다.\n\n```cpp\n// 좋은 예시\n// 파일 경로: tests/unit/calculator_test.cpp\nTEST_CASE(\\\"Calculator adds two positive numbers\\\", \\\"[calculator]\\\") {\n // Arrange: 테스트에 필요한 객체와 입력값을 준비합니다.\n Calculator calculator;\n const int Augend = 2;\n const int Addend = 3;\n const int ExpectedSum = 5;\n\n // Act: 테스트할 함수를 실행합니다.\n const int ActualSum = calculator.Add(Augend, Addend);\n\n // Assert: 실제 결과가 예상 결과와 일치하는지 확인합니다.\n REQUIRE(ActualSum == ExpectedSum);\n}\n```\n\n### 4.3 단언(Assertions)\n\n- **`REQUIRE`**: 핵심적인 검증에 사용합니다. 실패 시 테스트 케이스가 즉시 중단됩니다. 이 단언이 실패하면 나머지 테스트가 무의미해지는 조건에 사용하세요.\n- **`CHECK`**: 덜 중요한 검증에 사용합니다. 실패하더라도 테스트 케이스가 계속 진행되므로, 한 번의 실행으로 모든 실패한 단언을 확인할 수 있습니다.\n\n```cpp\n// 좋은 예시\n// 파일 경로: tests/unit/user_profile_test.cpp\nTEST_CASE(\\\"User profile validation\\\", \\\"[user_profile]\\\") {\n // Arrange\n const UserProfile Profile = CreateUserProfile(\\\"test_user\\\", 25);\n\n // Assert\n REQUIRE(Profile.IsActive()); // 사용자가 활성 상태가 아니면 나머지 속성 확인은 의미가 없습니다.\n\n CHECK(Profile.GetUsername() == \\\"test_user\\\"); // 이 확인은 IsActive()가 실패해도 실행됩니다.\n CHECK(Profile.GetAge() == 25); // 이 확인은 GetUsername() 확인이 실패해도 실행됩니다.\n}\n```\n\n```\n\n---\n\n### 단계 4: 커버리지 목표를 포함한 테스트 품질 표준 정의\n\n#### 1. 필수 품질 표준 정의하기\n\n이 작업은 모든 테스트 코드에 대해 타협 불가능한 품질 게이트를 설정합니다. 명시적인 함수 및 라인 커버리지 목표(각각 100%와 80%)를 설정함으로써, 우리는 테스트 스위트가 포괄적이고 회귀(regression) 위험을 최소화하도록 보장합니다. 또한 이 가이드라인은 엣지 케이스를 발견하기 위해 무작위 값을 사용한 견고한 테스트 작성을 권장합니다. 이러한 표준은 CI 파이프라인에 의해 자동으로 강제되도록 의도되었습니다.\n\n**파일**: `guidelines/cpp/test.md`\n\n```markdown\n...\n\n### 4.4 테스트 품질 표준\n\n- **규칙 1: 코드 커버리지 목표를 반드시 충족해야 합니다.**\n - **함수 커버리지**: 100%\n - **라인 커버리지**: 80% 이상\n - **근거**: 높은 커버리지는 테스트되지 않은 코드를 최소화하여 잠재적 버그를 줄이고 코드의 신뢰성을 높입니다. 빌드 시스템은 이 표준을 충족하지 못하면 실패하도록 구성되어 있습니다.\n\n- **규칙 2: 무작위 값을 사용한 반복 테스트를 지향해야 합니다.**\n - **설명**: 테스트는 고정된 값에만 의존해서는 안 됩니다. 다양한 입력 범위에 걸쳐 동작을 검증하기 위해 무작위 데이터를 사용한 반복 테스트를 사용하세요.\n - **근거**: 무작위 테스트는 개발자가 예상하지 못한 엣지 케이스를 발견하고 코드의 견고성을 보장하는 데 효과적입니다. Catch2의 `GENERATE` 매크로나 유사한 기법을 사용하는 것을 권장합니다.\n```\n\n---\n\n### 단계 5: 모의(mocking) 및 데이터 기반 테스트 같은 고급 기법 예제\n\n#### 1. 고급 테스트 기법 및 실행 명령어 문서화하기\n\n이 마지막 작업은 개발자에게 복잡한 테스트 시나리오에 대한 실용적인 해결책을 제공합니다. 의존성 모의(mocking) 및 데이터 기반 테스트를 위한 상세하고 바로 복사-붙여넣기 가능한 예제를 제공하며, 이는 테스트 격리성과 견고성을 유지하는 데 매우 중요합니다. 또한 모든 테스트 로직을 통합 관리하기 위해 C++로 작성된 상위 수준의 통합/E2E 테스트 예제도 포함합니다. 마지막으로, \"실행 방법\" 섹션을 추가하여 개발자가 로컬에서 테스트를 실행하고 디버깅할 때 빠르게 참조할 수 있도록 합니다.\n\n**파일**: `guidelines/cpp/test.md`\n\n```markdown\n...\n\n### 4.5 고급 테스트 기법\n\n이 섹션에서는 실제 프로젝트에서 마주치는 복잡한 상황을 해결하기 위한 실용적인 테스트 기법을 소개합니다.\n\n#### 4.5.1 의존성 격리를 위한 모의(Mocking)\n\n- **문제**: 테스트 대상 코드가 데이터베이스, 네트워크, 파일 시스템과 같은 외부 시스템에 의존할 때, 순수한 단위 테스트는 어려워집니다.\n- **해결책**: 외부 의존성을 제어 가능한 가짜 객체로 대체하기 위해 **모의 객체(Mock Object)**를 사용합니다. 특정 모의 프레임워크에 의존하기보다 인터페이스를 사용하여 수동으로 모의 객체를 작성하는 것을 권장합니다.\n\n```cpp\n// ... (입력의 전체 모의 예제 코드)\n// 1. 테스트 대상이 의존하는 리포지토리 인터페이스\nclass IUserRepository { ... };\n\n// 2. 해당 인터페이스를 사용하는 테스트 대상 클래스\nclass UserManager { ... };\n\n// 3. 수동으로 작성한 모의 리포지토리\nclass MockUserRepository : public IUserRepository { ... };\n\n// 4. 모의 객체를 사용하는 테스트 케이스\n// 파일 경로: tests/unit/user_manager_test.cpp\nTEST_CASE(\\\"UserManager creates a valid user\\\", \\\"[user_manager]\\\") { ... }\n```\n\n#### 4.5.2 데이터 기반 테스트\n\n- **설명**: `4.4`에서 언급했듯이, 다양한 입력값으로 테스트하면 코드의 견고성이 향상됩니다. Catch2의 `GENERATE` 매크로를 사용하면 여러 입력값을 간결하게 테스트할 수 있습니다.\n- **예시**: ...\n\n```cpp\n// 파일 경로: tests/unit/math_utils_test.cpp\nTEST_CASE(\\\"Addition with various inputs\\\", \\\"[math_utils]\\\") {\n // Arrange: 피연산자와 예상 결과를 준비합니다.\n auto [augend, addend, expected_sum] = GENERATE(\n std::make_tuple(1, 2, 3),\n std::make_tuple(-1, 1, 0),\n std::make_tuple(0, 0, 0),\n std::make_tuple(100, 200, 300)\n );\n // ... (Act 및 Assert)\n}\n```\n\n#### 4.5.3 통합 및 E2E 테스트 예제\n\n- **통합 테스트 예제**: 둘 이상의 실제 모듈 간의 상호작용을 검증합니다.\n\n```cpp\n// 파일 경로: tests/integration/config_manager_test.cpp\n// ... (입력의 전체 통합 테스트 예제 코드)\n```\n\n- **E2E 테스트 예제**: E2E 테스트는 전체 시스템의 동작을 검증합니다. 셸 스크립트를 사용하는 대신 C++ 테스트 케이스 내에서 직접 실행 파일을 호출할 수 있습니다.\n\n```cpp\n// 파일 경로: tests/e2e/file_formatter_e2e_test.cpp\n// ... (입력의 전체 E2E 테스트 예제 코드)\n```\n\n## 5. 테스트 실행 방법\n\n`build/` 디렉토리에서 모든 명령어를 실행해야 합니다.\n\n| 분류 | 명령어 | 설명 |\n| ----------------------- | ------------------------------------ | ---------------------------------------------------------- |\n| **표준 워크플로우** | `cmake --build .` | 한 번에 빌드, 모든 테스트 실행, 커버리지 검증을 수행합니다. |\n| **모든 테스트 재실행** | `ctest` | 기존 빌드에서 모든 테스트를 실행합니다. |\n| **그룹별 실행** | `ctest -L unit` | `unit` 레이블이 있는 테스트만 실행합니다. |\n| **개별 테스트 실행** | `ctest -R my_feature` | 이름이 정규식 `my_feature`와 일치하는 테스트를 실행합니다. |\n| **디버깅** | `./tests/run_all_tests [my_feature]` | CTest를 우회하여 테스트 실행 파일을 직접 실행합니다. |\n\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n- 개발자는 작업이 완전하고 정확하게 완료되었는지 확인하기 위해 다음 작업을 수행해야 합니다.\n\n```bash\n# 1. 가이드라인 파일이 생성되었는지 확인\nls guidelines/cpp/test.md\n\n# 2. 파일 내용을 수동으로 검토합니다.\n# 결과물에 명시된 모든 섹션이 포함되어 있는지 확인합니다:\n# - 개요\n# - 테스트 환경\n# - 테스트 유형\n# - 테스트 케이스 작성 방법 (명명, AAA, 단언 포함)\n# - 테스트 품질 표준\n# - 고급 테스트 기법 (모의, 데이터 기반, E2E 포함)\n# - 테스트 실행 방법\nless guidelines/cpp/test.md\n\n# 3. 프로젝트의 포매팅 스크립트를 실행하여 새 파일이 스타일 규칙을 준수하는지 확인합니다.\n# 이 명령어는 프로젝트의 실행 진입점으로 정의되어 있습니다.\nscripts/executables/run_formatters.sh\n```\n\n### 4.2. 예상 결과\n\n- 1단계의 `ls` 명령어는 `guidelines/cpp/test.md` 파일을 성공적으로 나열합니다.\n- 2단계의 수동 검토를 통해 필요한 모든 섹션과 내용이 구현 사양과 일치하는지 확인합니다.\n- 3단계의 `run_formatters.sh` 스크립트는 오류 없이 실행되며, 새로 추가된 `guidelines/cpp/test.md`를 포함한 모든 파일이 올바르게 포맷되었음을 보고합니다. 출력은 다음과 유사해야 합니다:\n\n```\nPrettier 포매터 실행 중...\n모든 파일이 올바르게 포맷되었습니다.\nmarkdownlint 실행 중...\n모든 마크다운 파일이 유효합니다.\n포매팅 완료.\n```","테스트 유형, 이름 규칙, 품질 표준을 설명하는 `test.md` 파일",[390,393,395,397,399],{"_24":391,"_83":39,"_84":392,"_85":61},"테스트 환경 정의 (Catch2, CTest)",17,{"_24":394,"_83":39,"_84":392,"_85":88},"테스트 유형 분류 (단위, 통합, E2E)",{"_24":396,"_83":39,"_84":392,"_85":91},"테스트 케이스의 이름 및 구조 규칙 (AAA 패턴)",{"_24":398,"_83":39,"_84":392,"_85":94},"커버리지 목표를 포함한 테스트 품질 표준 정의",{"_24":400,"_83":39,"_84":392,"_85":97},"모의 객체(mocking) 및 데이터 기반 테스팅과 같은 고급 기법 예제","프로젝트의 C++ 테스팅 전략, 도구, 모범 사례를 정의",{"_22":403,"_24":404,"_75":405,"_77":406,"_79":407,"_51":419,"_42":99},"task-1751363979144","Doxygen 주석 스타일 가이드","# 작업: Doxygen 주석 스타일 가이드\n\n> **Epic**: C++ 테스트 및 Doxygen 가이드라인 개발\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: C++ 코드에서 Doxygen API 문서를 작성하기 위한 일관된 스타일 확립.\n- **근거**: 이 작업은 읽기 쉽고 유지보수하기 좋은 C++ 코드를 만들려는 프로젝트의 핵심 목표를 달성하는 데 매우 중요합니다. 표준화된 Doxygen 스타일 가이드는 모든 API 문서가 통일되고, 예측 가능하며, 완전하도록 보장합니다. 이러한 일관성 덕분에 `자동화 도구`(Doxygen)는 품질 높고 탐색하기 쉬운 문서를 생성할 수 있습니다. 이는 개발자 온보딩, 장기적인 유지보수, 컴포넌트 계약의 명확한 전달에 필수적입니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: 다양한 코드 구성요소에 대한 주석 스타일과 태그 사용법을 상세히 기술한 Doxygen용 `coding_styles.md` 파일.\n- **명세**:\n - **문서 구조**: 가이드는 개요, 핵심 원칙, 일반 규칙(주석 스타일, 태그 사용법), 그리고 컴포넌트별 규칙(파일, 클래스, 함수, 변수)을 포함해야 합니다.\n - **주석 스타일 정의**: 가이드는 여러 줄 블록에는 `/** ... */`, 한 줄 블록에는 `///`, 인라인 멤버 주석에는 `///<` 사용을 명시해야 합니다.\n - **필수 Doxygen 태그**: 가이드는 명령어 접두사로 `@` 사용을 강제하고, `@file`, `@brief`, `@details`, `@param`, `@return`, `@note`, `@warning`, `@deprecated`, `@todo`, `@bug`, `@code`를 포함한 주요 태그의 사용법을 상세히 기술해야 합니다.\n- **결과 파일 구조**\n 다음 파일이 생성됩니다.\n\n```bash\n# ./\n# └── guidelines/\n# └── cpp/\n# └── doxygen/\n# └── coding_styles.md <-- New\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 개발자가 개발 수명주기 내에서 Doxygen 스타일 가이드를 어떻게 활용하는지 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"개발 단계\"\n Dev[\"개발자가 C++ 코드(.hpp, .cpp)를
작성 또는 수정\"]\n Guide[\"'doxygen/coding_styles.md' 참조\"]\n Comment[\"가이드에 따라 코드에
Doxygen 주석 적용\"]\n end\n\n subgraph \"자동화 및 활용 단계\"\n Doxygen[\"Doxygen 도구가 API 문서(HTML) 생성\"]\n Reviewer[\"다른 개발자가
생성된 문서 확인\"]\n end\n\n Dev --> Guide;\n Guide --> Comment;\n Dev --> Comment;\n Comment --> Doxygen;\n Doxygen --> Reviewer;\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완수해야 합니다. 이것은 개략적인 체크리스트이며, 각 항목에 대한 상세 구현은 3장에 있습니다.\n\n- [ ] 문서화를 위한 핵심 원칙 정의.\n- [ ] 표준 Doxygen 주석 블록 스타일 명시.\n- [ ] 파일 수준 주석에 대한 규칙.\n- [ ] 클래스, 함수, 멤버 변수 문서화 가이드라인.\n- [ ] `@todo`, `@bug`, `@code` 같은 고급 태그 예제.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 저장소\n- **관련 주요 컴포넌트**:\n - **언어 가이드라인**: 이 작업은 새로운 C++ 관련 가이드라인 문서를 생성하여 이 컴포넌트에 직접적으로 기여합니다. 프로젝트 내 C++ 코드의 문서화 표준을 성문화합니다.\n - **엔지니어링 원칙**: 이 스타일 가이드의 규칙들은 \"가독성\"과 \"일관성\" 같은 프로젝트의 기본 원칙을 API 문서화에 구체적으로 적용한 직접적인 구현체입니다.\n - **자동화 도구**: 이 가이드는 Doxygen 사용법에 대한 인간이 읽을 수 있는 명세서 역할을 합니다. 도구를 직접 설정하지는 않지만, Doxygen 도구가 처리할 예상 입력 형식(주석이 달린 C++ 코드)을 정의합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `guidelines/cpp/doxygen/coding_styles.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 여러 세부적인 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공할 것입니다.\n\n---\n\n### 1단계: 문서화의 핵심 원칙 정의\n\n#### 1. 문서 생성 및 핵심 원칙 정의\n\n이 액션은 기본 문서인 `coding_styles.md`를 만듭니다. 여기에는 표준 헤더, 문서의 목적과 범위를 정의하는 개요, 탐색을 위한 목차, 그리고 \"핵심 원칙\" 섹션이 포함됩니다. 이 원칙들(의도 문서화 및 일관성 유지)은 이후의 모든 규칙에 대한 철학적 기조를 설정하여 개발자들이 특정 표준 뒤에 있는 '이유'를 이해하도록 보장하기 때문에 매우 중요합니다.\n\n**File**: `guidelines/cpp/doxygen/coding_styles.md`\n\n```markdown\n# Doxygen C++ 코딩 스타일 규칙\n\n버전 v1.1 생성일 2025-06-26 소유자 @movingChurch\n\n---\n\n## 0. 개요\n\n- **목적** C++ 프로젝트의 Doxygen 주석 표준을 정의하여 일관성 있고 유지보수 가능한 문서를 보장합니다.\n- **범위** 이 저장소의 모든 C++ 소스 코드(`.hpp`, `.cpp`).\n- **대상** 프로젝트에 기여하는 모든 C++ 개발자.\n\n---\n\n## 1. 목차\n\n1. [핵심 원칙](#2-core-principles)\n2. [일반 주석 규칙](#3-general-commenting-rules)\n3. [컴포넌트별 스타일 규칙](#4-style-rules-by-component)\n\n---\n\n## 2. 핵심 원칙\n\n### 원칙 1 단순한 동작이 아닌, 의도를 문서화하세요\n\n- **범위** 모든 문서화 주석.\n- **근거** 코드는 _어떻게_ 작동하는지 설명할 수 있지만, 문서는 _왜_ 존재하는지, 설계 결정은 어떠했는지, 그리고 의도된 사용법은 무엇인지 설명해야 합니다. 이러한 맥락은 장기적인 유지보수와 협업에 매우 중요합니다.\n\n### 원칙 2 문서와 코드를 일관되게 유지하세요\n\n- **범위** 모든 코드 수정.\n- **근거** 오래되거나 부정확한 문서는 문서가 없는 것보다 더 해롭습니다. 코드를 변경할 때는 반드시 해당하는 Doxygen 주석도 함께 업데이트해야 합니다.\n```\n\n---\n\n### 2단계: 표준 Doxygen 주석 블록 스타일 명시\n\n#### 1. 일반 주석 및 태그 사용 규칙 추가\n\n이 액션은 \"일반 주석 규칙\" 섹션을 추가합니다. 이는 프로젝트 전체에서 Doxygen 사용의 두 가지 기본 측면, 즉 주석 블록의 시각적 스타일(`/**`, `///`, `///<`)과 명령어 구문(`@` 접두사)을 표준화합니다. 이 규칙들을 강제하면 모든 문서를 즉시 알아볼 수 있고 Doxygen 도구가 정확히 파싱하도록 보장하여, 가독성과 도구 성능을 저하하는 불일치를 방지합니다.\n\n**File**: `guidelines/cpp/doxygen/coding_styles.md`\n\n```markdown\n...\n---\n\n## 3. 일반 주석 규칙\n\n> **설명** 코드베이스 전체에 보편적으로 적용되는 Doxygen 주석 작성의 기본 규칙을 담고 있습니다.\n\n### 3.1 주석 스타일\n\n#### 규칙 1 표준 Doxygen 주석 블록을 사용하세요\n\n- **범위** 모든 Doxygen 주석.\n- **근거** 주석 스타일의 일관성은 가독성을 향상시키고 Doxygen 파서가 문서 블록을 정확히 식별하도록 보장합니다.\n\n```cpp\n# 좋은 예\n/**\n * @brief 파일, 클래스, 함수에 대한 상세 설명을 위한 여러 줄 주석.\n */\n\n/// 선언부 위에 간략한 설명을 위한 한 줄 주석.\nclass MyClass {};\n\nclass MemberExample {\n int member_; ///< 멤버 변수를 위한 인라인 주석.\n};\n```\n\n### 3.2 명령어(태그) 사용법\n\n#### 규칙 1 모든 Doxygen 명령어에 `@` 접두사를 사용하세요\n\n- **범위** 모든 Doxygen 명령어.\n- **근거** Doxygen은 `\\`도 지원하지만, `@`로 표준화하면 프로젝트 전체의 일관성을 보장할 수 있습니다.\n\n```cpp\n# 좋은 예\n/**\n * @brief 올바른 방법입니다.\n * @param user 사용자 객체.\n */\n\n# 나쁜 예\n/**\n * \\brief 이것은 우리의 표준이 아닙니다.\n * \\param user 사용자 객체.\n */\n```\n\n```\n\n---\n\n### 3단계: 파일 수준 주석 규칙\n\n#### 1. 파일 수준 주석 스타일 규칙 정의\n\n이 액션은 \"컴포넌트별 스타일 규칙\" 섹션을 도입하고 파일 수준 주석에 대한 첫 번째 규칙을 명시합니다. 모든 소스 및 헤더 파일은 파일명, 작성자, 목적과 같은 메타데이터를 포함하는 표준 Doxygen 블록으로 시작해야 합니다. 이는 파일을 여는 모든 사람에게 즉각적인 맥락을 제공하며, 상위 수준의 프로젝트 탐색 및 자동화된 문서 생성에 필수적입니다.\n\n**File**: `guidelines/cpp/doxygen/coding_styles.md`\n\n```markdown\n...\n---\n\n## 4. 컴포넌트별 스타일 규칙\n\n### 4.1 파일 주석\n\n#### 규칙 1 모든 소스 및 헤더 파일의 최상단에는 파일 주석 블록이 있어야 합니다\n\n- **범위** `*.hpp`, `*.cpp` 파일.\n- **근거** 파일의 목적, 작성자, 버전에 대한 상위 수준의 개요를 제공하며, 이는 프로젝트 탐색 및 관리에 필수적입니다.\n\n```cpp\n# 좋은 예\n/**\n * @file animal.hpp\n * @author movingChurch (yes@holyground.world)\n * @brief 동물의 기본적인 특징과 행동을 정의합니다.\n * @details 이 파일은 Animal 클래스와 AnimalType 열거형을 포함하며,\n * 객체 지향 동물 모델의 기반을 제공합니다.\n * @version 1.1.0\n * @date 2025-06-24\n * @copyright Copyright (c) 2025 HolyGround, All Rights Reserved.\n */\n```\n\n```\n\n---\n\n### 4단계: 클래스, 함수, 멤버 변수 문서화 가이드라인\n\n#### 1. 자료 구조 문서화 규칙 정의\n\n이 액션은 `class`, `struct`, `enum` 선언을 문서화하는 규칙을 추가합니다. 공개 인터페이스(public-facing)의 자료 구조는 핵심 API 요소입니다. 이들의 목적, 설계, 사용 제약 조건을 문서화하는 것은 사용 가능하고 유지보수 가능한 라이브러리를 만드는 데 있어 타협할 수 없는 부분입니다.\n\n**File**: `guidelines/cpp/doxygen/coding_styles.md`\n\n```markdown\n...\n### 4.2 클래스, 구조체, 열거형 주석\n\n#### 규칙 1 모든 공개(public-facing) 클래스, 구조체, 열거형은 반드시 문서화해야 합니다\n\n- **범위** `class`, `struct`, `enum` 선언.\n- **근거** 자료 구조 또는 타입의 역할, 책임, 사용법을 명확히 합니다.\n\n```cpp\n# 좋은 예: 클래스 주석\n/**\n * @brief 동물의 기본 정보를 나타내는 추상 기본 클래스(ABC).\n * @details 이름, 나이 등 모든 동물의 공통 속성을 관리하고,\n * 소리를 내기 위한 순수 가상 함수를 제공합니다. 이 클래스는\n * 상속을 통해서만 사용해야 합니다.\n * @note 직접 인스턴스화할 수 없습니다.\n * @see Cat, Dog\n */\nclass Animal {\n // ...\n};\n\n# 좋은 예: 열거형 주석\n/**\n * @brief 동물 타입을 위한 열거형.\n */\nenum class AnimalType {\n kUnknown, ///< 알 수 없음. 초기 또는 오류 상태를 나타냅니다.\n kCat, ///< 고양이.\n kDog, ///< 개.\n};\n```\n\n#### 2. 함수 및 메서드 문서화 규칙 정의\n\n이 액션은 모든 public 및 protected 함수를 문서화하기 위한 가이드라인을 추가합니다. 함수는 API의 동작을 정의합니다. 함수의 계약, 즉 무엇을 하는지(`@brief`), 무엇이 필요한지(`@param`), 무엇을 제공하는지(`@return`)를 명확하게 문서화하는 것은 오용을 방지하고 통합을 단순화하는 데 매우 중요합니다.\n\n**File**: `guidelines/cpp/doxygen/coding_styles.md`\n\n```markdown\n...\n### 4.3 함수 및 메서드 주석\n\n#### 규칙 1 모든 public 및 protected 함수/메서드는 반드시 문서화해야 합니다\n\n- **범위** 함수 및 메서드 선언/정의.\n- **근거** 함수의 계약, 즉 목적, 매개변수, 반환 값을 명확하게 정의하며, 이는 API 사용자에게 매우 중요합니다.\n\n#### 규칙 2 필수 태그: `@brief`, `@param`, `@return`\n\n- **범위** 문서화된 모든 함수/메서드.\n- **근거** 가장 중요한 정보가 항상 존재하도록 보장합니다. 모든 매개변수에는 `@param`이 필수이며, 함수가 `void`가 아닌 경우 `@return`이 필수입니다.\n\n```cpp\n# 좋은 예\n/**\n * @brief 두 부동소수점 숫자가 거의 같은지 비교합니다.\n * @details 부동소수점 정밀도 한계 문제를 피하기 위해, 두 숫자의 차이가\n * 아주 작은 값(엡실론)보다 작은지 확인합니다.\n * @param lhs [in] 비교할 첫 번째 숫자 (좌변).\n * @param rhs [in] 비교할 두 번째 숫자 (우변).\n * @return 두 숫자가 거의 같으면 true, 그렇지 않으면 false.\n...\n */\nstatic auto IsEqual(double lhs, double rhs) -> bool;\n```\n\n#### 3. 멤버 변수 문서화 규칙 정의\n\n이 액션은 멤버 변수 문서화 규칙을 추가합니다. 모든 public 및 protected 멤버는 간결한 인라인(`///<`) 주석을 가져야 합니다. 이는 클래스가 관리하는 상태에 대한 즉각적이고 맥락에 맞는 정보를 제공하여 가독성을 높이고 데이터 모델을 더 쉽게 이해할 수 있도록 만듭니다.\n\n**File**: `guidelines/cpp/doxygen/coding_styles.md`\n\n```markdown\n...\n### 4.4 멤버 변수 주석\n\n#### 규칙 1 모든 protected 및 public 멤버 변수는 인라인 주석이 있어야 합니다\n\n- **범위** 멤버 변수 선언.\n- **근거** 변수가 선언된 바로 그 위치에서 변수의 목적에 대한 간결한 설명을 제공합니다.\n\n```cpp\n# 좋은 예\nprotected:\n std::string name_{}; ///< 동물의 이름.\n uint8_t age_{}; ///< 동물의 나이 (0-255세).\n```\n\n```\n\n---\n\n### 5단계: `@todo`, `@bug`, `@code` 같은 고급 태그 예제\n\n#### 1. 고급 및 유틸리티 태그 사용법 정의\n\n이 마지막 액션은 \"고급 및 유틸리티 태그\" 섹션을 추가합니다. 이는 더 이상 사용되지 않는 코드를 위한 `@deprecated`, 강조를 위한 `@note`/`@warning`, 코드 내 이슈 추적을 위한 `@bug`/`@todo`, 사용 예제를 위한 `@code`와 같이 특별한 의미를 전달하는 태그 사용법에 대한 명확한 지침을 제공합니다. 이를 표준화하면 Doxygen이 유용한 상호 참조(예: \"버그 목록\" 페이지)를 자동으로 생성하여 유지보수 작업과 API 예제를 문서에 직접 통합할 수 있습니다.\n\n**File**: `guidelines/cpp/doxygen/coding_styles.md`\n\n```markdown\n...\n### 4.5 고급 및 유틸리티 태그\n\n#### 규칙 1 사용 중단(deprecated)된 코드를 명확히 표시하세요\n\n- **범위** 더 이상 사용되지 않는 함수, 메서드, 클래스, 또는 열거형.\n- **근거** 개발자에게 해당 기능이 더 이상 사용을 권장하지 않으며 미래에 제거될 것임을 알립니다. 대안을 제시하는 것이 좋은 습관입니다.\n\n```cpp\n# 좋은 예\n/**\n * @brief 데이터를 처리하는 오래된 함수.\n * @deprecated NewProcessData()로 대체되었습니다. v2.0에서 제거될 예정입니다.\n * @see NewProcessData()\n */\nvoid OldProcessData();\n```\n\n#### 규칙 2 중요한 정보를 강조하기 위해 주석 태그를 사용하세요\n\n- **범위** 특별한 강조가 필요한 모든 문서 블록.\n- **근거** `@note`, `@warning`, `@attention`은 독자의 주의를 중요한 정보, 잠재적 위험, 또는 주요 고려사항으로 이끄는 표준화된 방법을 제공합니다.\n\n```cpp\n# 좋은 예\n/**\n * @brief 중요한 연산을 수행합니다.\n * @warning 이 함수는 스레드 안전(thread-safe)하지 않습니다. 외부에서 접근을 동기화해야 합니다.\n * @note 성능상의 이유로, 이 함수는 입력 매개변수를 검증하지 않습니다.\n */\nvoid DoCriticalOperation();\n```\n\n#### 규칙 3 작업과 버그를 코드에서 직접 추적하세요\n\n- **범위** 향후 작업이 필요하거나 알려진 이슈가 있는 코드의 모든 부분.\n- **근거** `@todo`와 `@bug`는 작업 및 버그 추적을 소스 코드에 통합하여 개발자에게 잘 보이도록 만듭니다. Doxygen은 이러한 모든 항목의 목록을 생성할 수 있습니다.\n\n```cpp\n# 좋은 예\n/**\n * @brief 총 가격을 계산합니다.\n * @param items 구매할 아이템 목록.\n * @return 총 가격.\n * @bug 대량 주문 할인을 올바르게 처리하지 못합니다.\n * @todo (movingChurch) 할인 로직을 위해 새로운 PricingService를 사용하도록 리팩터링 필요.\n */\nfloat CalculatePrice(const std::vector& items);\n```\n\n#### 규칙 4 명확한 코드 예제를 제공하세요\n\n- **범위** 사용법이 즉시 명확하지 않은 함수/메서드 주석.\n- **근거** `@code`를 통한 구체적인 코드 예제는 개발자가 API를 올바르게 사용하는 방법을 이해하는 가장 빠른 방법인 경우가 많습니다.\n\n```cpp\n# 좋은 예\n/**\n * @brief 두 부동소수점 숫자가 거의 같은지 비교합니다.\n * @return 두 숫자가 거의 같으면 true, 그렇지 않으면 false.\n * @note 사용 예제:\n * @code{.cpp}\n * IsEqual(1.0, 1.00000001); // true\n * IsEqual(1.0, 1.01); // false\n * @endcode\n */\nstatic auto IsEqual(double lhs, double rhs) -> bool;\n```\n\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n1. **파일 생성 확인**: `guidelines/cpp/doxygen/coding_styles.md` 파일이 올바른 디렉터리에 생성되었는지 확인합니다.\n2. **수동 내용 검토**: 생성된 마크다운 파일을 읽고 그 내용을 완료 조건(1.3절)의 각 항목과 비교하여 모든 필수 섹션과 규칙이 있는지 확인합니다.\n3. **프로젝트 포맷터 실행**: 프로젝트의 포맷팅 스크립트를 실행하여 새 마크다운 파일이 저장소의 린팅 및 스타일 표준을 준수하는지 확인합니다.\n\n```bash\n# 프로젝트 루트에서 마스터 포맷팅 스크립트를 실행합니다.\n# 이 스크립트는 포맷팅을 위한 Prettier와 스타일 검사를 위한 markdownlint를 모두 처리해야 합니다.\n./scripts/executables/run_formatters.sh\n```\n\n### 4.2. 예상 결과\n\n- 검증 단계를 실행한 후, `guidelines/cpp/doxygen/coding_styles.md` 파일이 존재하고 그 내용이 명세와 일치할 것입니다.\n- `run_formatters.sh` 스크립트는 성공적으로 실행되고 상태 코드 0으로 종료되어야 합니다. 명령어 출력은 모든 파일이 올바르게 포맷되었음을 나타내야 합니다. 예:\n\n```\n[INFO] Running Prettier formatter...\n[INFO] Running markdownlint...\n[SUCCESS] All files are clean.\n```","다양한 코드 구성 요소에 대한 주석 스타일과 태그 사용법을 상세히 설명하는 Doxygen용 `coding_styles.md` 파일",[408,411,413,415,417],{"_24":409,"_83":39,"_84":410,"_85":61},"문서화를 위한 핵심 원칙 정의",18,{"_24":412,"_83":39,"_84":410,"_85":88},"표준 Doxygen 주석 블록 스타일 명시",{"_24":414,"_83":39,"_84":410,"_85":91},"파일 수준 주석에 대한 규칙",{"_24":416,"_83":39,"_84":410,"_85":94},"클래스, 함수, 멤버 변수 문서화 가이드라인",{"_24":418,"_83":39,"_84":410,"_85":97},"`@todo`, `@bug`, `@code`와 같은 고급 태그 예제","C++ 코드에서 Doxygen API 문서를 작성하기 위한 일관된 스타일을 수립",{"_22":421,"_24":422,"_75":423,"_77":424,"_79":425,"_51":437,"_42":99},"task-1751364033662","Doxygen 구성 파라미터 가이드","# 작업: Doxygen 설정 매개변수 가이드\n\n> **에픽**: C++ 테스트 및 Doxygen 가이드라인 개발\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: Doxygen 설정 매개변수 관리를 위한 참조 문서 제작.\n- **근거**: 프로젝트 전반에 걸쳐 일관되고 높은 품질의 API 문서 생성을 보장하기 위해, Doxygen의 `doxyfile`에 대한 표준화된 가이드가 필요합니다. 이 가이드는 개발자를 위한 단일 진실 공급원(single source of truth) 역할을 하며, 생성된 문서가 프로젝트의 핵심 원칙인 가독성 및 유지보수성과 일치하도록 합니다. 또한, 문서 출력에 대한 모범 사례를 성문화하여 모든 개발자가 통일되고 탐색하기 쉬운 결과물을 생성하도록 보장합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: 주요 `doxyfile` 설정을 기능별로 그룹화하여 설명하는 `parameters.md` 파일.\n- **명세**: 결과물은 필수적인 `doxyfile` 설정 태그를 체계적으로 상세히 기술하는 마크다운 문서(`parameters.md`)입니다. 각 매개변수 설명에는 다음이 포함되어야 합니다:\n - 목적에 대한 명확한 설명.\n - 예상되는 값의 형식 (예: 문자열, `YES | NO`, 경로).\n - 기본값.\n - `@PROJECT_NAME@`와 같은 빌드 시스템 변수를 활용한 간결하고 실용적인 예시.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── guidelines/\n# └── cpp/\n# └── doxygen/\n# └── parameters.md <-- 신규\n```\n\n- **프로세스 순서도**\n이 다이어그램은 개발자가 문서화 워크플로우 내에서 매개변수 가이드를 어떻게 사용하는지 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"개발자 문서화 워크플로우\"\n Dev[\"개발자가 Doxygen 주석과 함께
C++ 코드를 작성\"] --> ConsultsGuide[\"'parameters.md' 가이드 참조\"];\n ConsultsGuide --> ConfiguresDoxyfile[\"로컬 'doxyfile' 설정\"];\n ConfiguresDoxyfile --> GeneratesDocs[\"Doxygen을 실행하여
문서 생성\"];\n GeneratesDocs --> ReviewsDocs[\"표준화된
API 문서 검토\"];\n end\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 상세 구현은 3절에 있습니다.\n\n- [ ] 기본 프로젝트 설정(이름, 버전) 문서화.\n- [ ] 소스 입력 및 분석 설정 설명.\n- [ ] HTML 및 LaTeX 출력 형식 옵션 상세 설명.\n- [ ] Graphviz를 통한 다이어그램 및 그래프 생성 가이드.\n- [ ] 경고, 로깅 및 사용자 정의 설정 참조.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 저장소\n- **관련된 주요 구성 요소**:\n - **언어 가이드라인**: 이 작업은 이 구성 요소 내에 새로운 결과물을 직접 생성합니다. `parameters.md` 파일은 C++ 및 Doxygen 관련 가이드라인의 공식적인 일부가 되어 개발자에게 실행 가능한 지침을 제공합니다.\n - **자동화 도구**: 이 가이드는 자동화 도구의 핵심 설정 파일인 `doxyfile`에 대한 사람이 읽을 수 있는 명세를 제공합니다. 이는 프로젝트의 문서화 표준과 이를 강제하는 도구 사이의 간극을 메웁니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `guidelines/cpp/doxygen/parameters.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 기본 프로젝트 설정(이름, 버전) 문서화\n\n#### 1. 소개 및 기본 프로젝트 설정 섹션 추가\n\n이 작업은 가이드의 기본 구조를 설정합니다. 문서의 목적과 CMake 같은 빌드 시스템과 통합되는 방식을 설명하는 소개 단락을 포함합니다. 그리고 프로젝트, 버전, 출력 위치를 식별하기 위한 필수 Doxygen 태그를 다루는 첫 번째 주요 섹션인 \"기본 프로젝트 설정\"을 추가합니다. 이는 생성된 문서의 핵심 메타데이터를 제공합니다.\n\n**파일**: `guidelines/cpp/doxygen/parameters.md`\n\n```markdown\n# Doxygen 매개변수 관리 가이드\n\n이 문서는 Doxygen 설정 파일(`doxyfile`)의 주요 매개변수를 효과적으로 관리하기 위한\n가이드입니다. 각 매개변수는 기능별로 그룹화되어 있으며, 명확한 이해를 돕기 위해\n설명, 사용 가능한 값, 기본값, 그리고 예시를 포함합니다.\n\n이 설정 파일은 CMake와 같은 빌드 시스템과 연동하여 동적으로 변수를 설정할 수\n있도록 설계되었습니다 (`@VAR_NAME@` 형식 사용).\n\n---\n\n## Ⅰ. 기본 프로젝트 설정\n\n프로젝트 이름, 버전, 설명 등 기본적인 프로젝트 정보를 설정합니다.\n\n### `PROJECT_NAME`\n\n- **설명**: 프로젝트의 이름을 지정합니다. 생성된 문서의 제목이나 헤더 등\n 다양한 곳에서 사용됩니다.\n- **값**: 문자열 (빌드 시스템 변수 사용 권장)\n- **기본값**: `\"My Project\"`\n- **예시**: `PROJECT_NAME = \"@PROJECT_NAME@\"`\n\n### `PROJECT_NUMBER`\n\n- **설명**: 프로젝트의 버전 번호나 리비전을 지정합니다.\n- **값**: 문자열 (빌드 시스템 변수 사용 권장)\n- **기본값**: (없음)\n- **예시**: `PROJECT_NUMBER = \"@PROJECT_VERSION@\"`\n\n### `PROJECT_BRIEF`\n\n- **설명**: 프로젝트에 대한 한 줄 요약을 추가합니다. 각 문서 페이지의 상단에\n 표시됩니다.\n- **값**: 문자열 (빌드 시스템 변수 사용 권장)\n- **기본값**: (없음)\n- **예시**: `PROJECT_BRIEF = \"@PROJECT_DESCRIPTION@\"`\n\n### `OUTPUT_DIRECTORY`\n\n- **설명**: 문서가 생성될 최상위 디렉터리 경로를 지정합니다.\n- **값**: 디렉터리 경로 (빌드 시스템 변수 사용 권장)\n- **기본값**: (현재 디렉터리)\n- **예시**: `OUTPUT_DIRECTORY = \"@DOXYGEN_OUTPUT_DIRECTORY@\"`\n\n### `OUTPUT_LANGUAGE`\n\n- **설명**: 생성될 문서의 언어를 선택합니다.\n- **값**: `English`, `Korean`, `Japanese` 등 지원되는 언어\n- **기본값**: `English`\n- **예시**: `OUTPUT_LANGUAGE = English`\n\n---\n```\n\n---\n\n### 단계 2: 소스 입력 및 분석 설정 설명\n\n#### 1. 소스 입력 및 분석 설정 섹션 추가\n\n이 작업은 Doxygen이 소스 코드를 찾고 파싱하는 방법을 제어하는 매개변수들을 상세히 설명합니다. 입력 디렉터리, 파일 패턴, 제외 항목을 지정하여 문서화 범위를 정의하는 데 매우 중요합니다. 또한 비공개 멤버나 문서화되지 않은 코드를 포함할지 여부와 같이 추출되는 정보의 양을 결정하는 설정을 다루며, 이는 최종 결과물의 완성도와 초점에 직접적인 영향을 미칩니다.\n\n**파일**: `guidelines/cpp/doxygen/parameters.md`\n\n```markdown\n...\n\n## Ⅱ. 소스 입력 및 분석 설정\n\n문서화할 소스 파일의 위치, 인코딩, 추출할 콘텐츠를 제어합니다.\n\n### `INPUT`\n\n- **설명**: 문서화할 소스 파일 및 디렉터리 목록을 지정합니다.\n- **값**: 파일 또는 디렉터리 경로 (빌드 시스템 변수 사용 권장)\n- **기본값**: (없음)\n- **예시**: `INPUT = \"@DOXYGEN_INPUT@\"`\n\n### `RECURSIVE`\n\n- **설명**: `INPUT`에 지정된 디렉터리의 하위 디렉터리를 재귀적으로 탐색할지\n 설정합니다.\n- **값**: `YES | NO`\n- **기본값**: `NO`\n- **예시**: `RECURSIVE = YES`\n\n### `FILE_PATTERNS`\n\n- **설명**: `INPUT` 디렉터리 내에서 검색할 파일 확장자 패턴을 지정합니다.\n- **값**: 와일드카드 패턴 목록 (예: `*.cpp *.h`)\n- **기본값**: (다양한 기본 확장자 패턴)\n- **예시**: `FILE_PATTERNS = *.cpp *.h *.hpp`\n\n### `EXCLUDE`\n\n- **설명**: 문서화에서 제외할 파일 또는 디렉터리 목록을 지정합니다.\n- **값**: 파일 또는 디렉터리 경로 목록\n- **기본값**: (없음)\n- **예시**: `EXCLUDE =`\n\n### `INPUT_ENCODING`\n\n- **설명**: 소스 파일의 문자 인코딩을 지정합니다.\n- **값**: `iconv`가 지원하는 인코딩 (예: `UTF-8`, `EUC-KR` 등)\n- **기본값**: `UTF-8`\n- **예시**: `INPUT_ENCODING = UTF-8`\n\n### `EXTRACT_ALL`\n\n- **설명**: 문서 주석이 없는 코드도 모두 문서에 포함할지 결정합니다.\n- **값**: `YES | NO`\n- **기본값**: `NO`\n- **예시**: `EXTRACT_ALL = NO`\n\n### `EXTRACT_PRIVATE`\n\n- **설명**: 클래스의 `private` 멤버를 문서에 포함할지 설정합니다.\n- **값**: `YES | NO`\n- **기본값**: `NO`\n- **예시**: `EXTRACT_PRIVATE = NO`\n\n### `CPP_CLI_SUPPORT`\n\n- **설명**: C++/CLI 문법을 지원할지 설정합니다.\n- **값**: `YES | NO`\n- **기본값**: `NO`\n- **예시**: `CPP_CLI_SUPPORT = YES`\n\n---\n```\n\n---\n\n### 단계 3: HTML 및 LaTeX 출력 형식 옵션 상세 설명\n\n#### 1. 출력 형식 설정 섹션 추가\n\n이 작업은 주요 문서 결과물인 HTML과 LaTeX의 설정을 위한 매개변수를 문서화합니다. 이 설정들은 최종 결과물의 존재 여부와 구조를 제어하는 데 기본이 됩니다. 예를 들어, `GENERATE_TREEVIEW`는 HTML 출력의 탐색 기능을 향상시켜 프로젝트의 가독성 목표를 직접적으로 지원합니다.\n\n**파일**: `guidelines/cpp/doxygen/parameters.md`\n\n```markdown\n...\n\n## Ⅲ. 출력 형식 설정 (HTML & LaTeX)\n\nHTML 및 LaTeX 문서 생성과 관련된 옵션을 제어합니다.\n\n### `GENERATE_HTML`\n\n- **설명**: 문서를 HTML 형식으로 생성할지 설정합니다.\n- **값**: `YES | NO`\n- **기본값**: `YES`\n- **예시**: `GENERATE_HTML = YES`\n\n### `HTML_OUTPUT`\n\n- **설명**: 생성된 HTML 문서가 저장될 디렉터리 이름을 지정합니다.\n- **값**: 디렉터리 이름\n- **기본값**: `html`\n- **예시**: `HTML_OUTPUT = html`\n\n### `GENERATE_TREEVIEW`\n\n- **설명**: 탐색을 돕기 위해 트리 구조의 사이드 패널을 생성할지 설정합니다.\n- **값**: `YES | NO`\n- **기본값**: `NO`\n- **예시**: `GENERATE_TREEVIEW = YES`\n\n### `GENERATE_LATEX`\n\n- **설명**: 문서를 LaTeX 형식으로 생성할지 설정합니다.\n- **값**: `YES | NO`\n- **기본값**: `YES`\n- **예시**: `GENERATE_LATEX = YES`\n\n### `LATEX_OUTPUT`\n\n- **설명**: 생성된 LaTeX 문서가 저장될 디렉터리 이름을 지정합니다.\n- **값**: 디렉터리 이름\n- **기본값**: `latex`\n- **예시**: `LATEX_OUTPUT = latex`\n\n---\n```\n\n---\n\n### 단계 4: Graphviz를 통한 다이어그램 및 그래프 생성 가이드\n\n#### 1. 다이어그램 및 그래프 설정 섹션 추가\n\n이 작업은 Graphviz 기반의 다이어그램 생성을 위한 문서를 추가합니다. 이 설정들은 클래스 계층 구조나 호출 그래프와 같은 복잡한 코드 구조를 시각화하는 데 매우 중요합니다. 이러한 옵션을 올바르게 설정하면 이해도를 높이고 코드 구성 요소 간의 관계를 명시적으로 만들어주며, 이는 가독성 있고 유지보수 가능한 문서를 만드는 핵심적인 측면입니다.\n\n**파일**: `guidelines/cpp/doxygen/parameters.md`\n\n```markdown\n...\n\n## Ⅳ. 다이어그램 및 그래프 설정 (Graphviz)\n\n클래스 상속 계층도나 호출 그래프와 같은 시각적 다이어그램 생성 옵션을\n제어합니다.\n\n### `HAVE_DOT`\n\n- **설명**: 다이어그램 생성을 위해 `dot` 도구를 사용할지 설정합니다.\n- **값**: `YES | NO`\n- **기본값**: `NO`\n- **예시**: `HAVE_DOT = YES`\n\n### `UML_LOOK`\n\n- **설명**: UML 스타일의 클래스 다이어그램을 생성합니다.\n- **값**: `YES | NO`\n- **기본값**: `NO`\n- **예시**: `UML_LOOK = YES`\n\n### `GRAPHICAL_HIERARCHY`\n\n- **설명**: 클래스 상속 계층도를 그래픽으로 생성합니다.\n- **값**: `YES | NO`\n- **기본값**: `YES`\n- **예시**: `GRAPHICAL_HIERARCHY = YES`\n\n### `DIRECTORY_GRAPH`\n\n- **설명**: 디렉터리 구조를 보여주는 그래프를 생성합니다.\n- **값**: `YES | NO`\n- **기본값**: `YES`\n- **예시**: `DIRECTORY_GRAPH = YES`\n\n### `CALL_GRAPH`\n\n- **설명**: 각 함수가 어떤 다른 함수를 호출하는지 보여주는 호출 그래프를\n 생성합니다.\n- **값**: `YES | NO`\n- **기본값**: `NO`\n- **예시**: `CALL_GRAPH = YES`\n\n### `CALLER_GRAPH`\n\n- **설명**: 각 함수를 어떤 다른 함수들이 호출하는지 보여주는 호출자 그래프를\n 생성합니다.\n- **값**: `YES | NO`\n- **기본값**: `NO`\n- **예시**: `CALLER_GRAPH = YES`\n\n### `MAX_DOT_GRAPH_DEPTH`\n\n- **설명**: 복잡도를 관리하기 위해 그래프의 최대 깊이를 제한합니다.\n- **값**: 정수\n- **기본값**: `0` (무제한)\n- **예시**: `MAX_DOT_GRAPH_DEPTH = 5`\n\n### `DOT_IMAGE_FORMAT`\n\n- **설명**: `dot`으로 생성할 이미지 형식을 지정합니다.\n- **값**: `png`, `svg`, `jpg` 등\n- **기본값**: `png`\n- **예시**: `DOT_IMAGE_FORMAT = svg`\n\n### `INTERACTIVE_SVG`\n\n- **설명**: 형식이 `svg`일 때, 확대/축소 및 이동이 가능한 대화형 이미지를\n 생성합니다.\n- **값**: `YES | NO`\n- **기본값**: `NO`\n- **예시**: `INTERACTIVE_SVG = YES`\n\n---\n```\n\n---\n\n### 단계 5: 경고, 로깅 및 사용자 정의 설정 참조\n\n#### 1. 경고 및 로깅 설정 섹션 추가\n\n이 작업은 Doxygen의 콘솔 출력 및 로깅 동작을 제어하기 위한 매개변수를 문서화합니다. 이 설정들은 깔끔한 빌드 프로세스를 유지하고 문서화 문제를 디버깅하는 데 필수적입니다. 예를 들어, `WARN_IF_UNDOCUMENTED`를 활성화하여 문서화 커버리지를 강제할 수 있으며, 이는 프로젝트 품질 목표를 직접적으로 지원합니다.\n\n**파일**: `guidelines/cpp/doxygen/parameters.md`\n\n```markdown\n...\n\n## Ⅴ. 경고 및 로깅 설정\n\n문서 생성 과정에서 발생하는 경고 메시지를 제어합니다.\n\n### `QUIET`\n\n- **설명**: 일반 메시지가 표준 출력으로 전송되는 것을 방지합니다.\n- **값**: `YES | NO`\n- **기본값**: `NO`\n- **예시**: `QUIET = YES`\n\n### `WARNINGS`\n\n- **설명**: 경고 메시지를 활성화하거나 비활성화합니다.\n- **값**: `YES | NO`\n- **기본값**: `YES`\n- **예시**: `WARNINGS = YES`\n\n### `WARN_IF_UNDOCUMENTED`\n\n- **설명**: 문서 주석이 없는 코드 요소에 대해 경고를 표시합니다.\n- **값**: `YES | NO`\n- **기본값**: `YES`\n- **예시**: `WARN_IF_UNDOCUMENTED = YES`\n\n### `WARN_LOGFILE`\n\n- **설명**: 경고 및 오류 메시지를 지정된 파일에 기록합니다.\n- **값**: 파일 경로\n- **기본값**: (없음, stderr로 출력)\n- **예시**: `WARN_LOGFILE = doxygen-warnings.log`\n\n---\n```\n\n#### 2. 고급 사용자 정의 설정 섹션 추가\n\n이 작업은 문서 내용과 표현을 미세 조정하기 위한 고급 매개변수들을 상세히 설명합니다. 공통 명령어에 대한 별칭 정의(`ALIASES`), 외부 문서 연결(`TAGFILES`), 경로 표시 방식 제어(`STRIP_FROM_PATH`)와 같은 강력한 기능을 다룹니다. 이러한 설정들은 매우 맞춤화되고 전문적인 문서 결과물을 가능하게 합니다.\n\n**파일**: `guidelines/cpp/doxygen/parameters.md`\n\n```markdown\n...\n\n## Ⅵ. 고급 사용자 정의 설정\n\n문서의 내용과 표현을 세밀하게 제어하기 위한 고급 기능입니다.\n\n### `IMAGE_PATH`\n...\n### `STRIP_FROM_PATH`\n\n- **설명**: `FULL_PATH_NAMES`가 `YES`일 때, 파일 경로에서 지정된 부분을\n 제거하여 상대 경로처럼 보이게 만듭니다.\n- **값**: 제거할 경로 (빌드 시스템 변수 사용 권장)\n- **기본값**: (doxygen 실행 디렉터리)\n- **예시**: `STRIP_FROM_PATH = \"@PROJECT_SOURCE_DIR@\"`\n\n---\n```\n\n#### 3. 특수 목록 생성 옵션 섹션 추가\n\n이 작업은 To-Do, Test, Bug 목록과 같은 특수 페이지의 자동 생성을 활성화하는 매개변수를 문서화합니다. 이 기능은 `\\todo`, `\\bug`와 같은 사용자 정의 Doxygen 명령어를 활용하여 개발 노트를 소스 코드에서 직접 수집하여 문서 내의 정리된 섹션으로 통합함으로써, 프로젝트 추적과 투명성을 향상시킵니다.\n\n**파일**: `guidelines/cpp/doxygen/parameters.md`\n\n```markdown\n...\n\n## Ⅶ. 특수 목록 생성 옵션\n\n`\\todo`, `\\bug` 등 특정 명령어에 기반하여 특수 목록 페이지를 생성합니다.\n\n### `GENERATE_TODOLIST`\n\n- **설명**: `\\todo` 명령어로 작성된 내용을 수집하여 '할 일 목록' 페이지를\n 생성합니다.\n- **값**: `YES | NO`\n- **기본값**: `YES`\n- **예시**: `GENERATE_TODOLIST = YES`\n\n### `GENERATE_TESTLIST`\n\n- **설명**: `\\test` 명령어로 작성된 내용을 수집하여 '테스트 목록' 페이지를\n 생성합니다.\n- **값**: `YES | NO`\n- **기본값**: `YES`\n- **예시**: `GENERATE_TESTLIST = YES`\n\n### `GENERATE_BUGLIST`\n\n- **설명**: `\\bug` 명령어로 작성된 내용을 수집하여 '버그 목록' 페이지를\n 생성합니다.\n- **값**: `YES | NO`\n- **기본값**: `YES`\n- **예시**: `GENERATE_BUGLIST = YES`\n\n### `GENERATE_DEPRECATEDLIST`\n\n- **설명**: `\\deprecated` 명령어로 작성된 내용을 수집하여 '사용되지 않는 API\n 목록' 페이지를 생성합니다.\n- **값**: `YES | NO`\n- **기본값**: `YES`\n- **예시**: `GENERATE_DEPRECATEDLIST = YES`\n\n---\n```\n\n#### 4. 소스 브라우징 옵션 섹션 추가\n\n이 마지막 작업은 소스 코드를 문서에 직접 포함하기 위한 매개변수를 문서화합니다. `SOURCE_BROWSER` 기능은 사용자가 생성된 HTML 페이지를 떠나지 않고도 함수나 클래스의 문서에서 해당 구현으로 직접 이동할 수 있게 해줍니다. 이는 코드 탐색을 위한 원활한 경험을 만들고 문서와 소스 간의 연결을 심화시킵니다.\n\n**파일**: `guidelines/cpp/doxygen/parameters.md`\n\n```markdown\n...\n\n## Ⅷ. 소스 브라우징 옵션\n\n생성된 문서 내에서 직접 소스 코드를 탐색하는 것과 관련된 옵션을 설정합니다.\n\n### `SOURCE_BROWSER`\n\n- **설명**: 문서화된 각 파일 및 멤버의 소스 코드를 볼 수 있는 기능을\n 활성화합니다.\n- **값**: `YES | NO`\n- **기본값**: `NO`\n- **예시**: `SOURCE_BROWSER = YES`\n\n### `INLINE_SOURCES`\n\n- **설명**: 멤버의 소스 코드를 해당 상세 설명 섹션에 직접 삽입합니다.\n `SOURCE_BROWSER`가 활성화되어 있어야 합니다.\n- **값**: `YES | NO`\n- **기본값**: `NO`\n- **예시**: `INLINE_SOURCES = YES`\n\n### `STRIP_CODE_COMMENTS`\n\n- **설명**: 소스 브라우저에 표시되는 코드에서 주석을 제거할지 설정합니다.\n- **값**: `YES | NO`\n- **기본값**: `YES`\n- **예시**: `STRIP_CODE_COMMENTS = YES`\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n- **1단계**: 적절한 로컬 설치 스크립트(예: `scripts/installers/macos/install_formatters.sh`)를 실행하여 필요한 모든 포맷터가 설치되었는지 확인합니다.\n- **2단계**: 마스터 포맷팅 스크립트를 실행하여 새로운 마크다운 파일의 스타일 및 일관성 위반 여부를 확인합니다.\n\n```bash\n# 1. 프로젝트 루트 디렉터리로 이동\ncd /path/to/readable-code-cpp-development-guidelines\n\n# 2. 포맷터 스크립트 실행\n./scripts/executables/run_formatters.sh\n```\n\n- **3단계**: 생성된 `guidelines/cpp/doxygen/parameters.md` 파일을 수동으로 검토하여 완료 조건에 명시된 모든 섹션이 올바르게 추가되었고 마크다운 뷰어에서 제대로 렌더링되는지 확인합니다.\n\n### 4.2. 예상 결과\n\n- `run_formatters.sh` 스크립트 실행 후, 명령어는 종료 코드 0으로 종료되어야 하며, 출력은 새로운 `parameters.md`를 포함한 모든 파일이 올바르게 포맷되었음을 나타내야 합니다.\n\n```\n[INFO] Prettier를 실행하여 마크다운 파일을 포맷합니다...\n[SUCCESS] 모든 마크다운 파일이 올바르게 포맷되었습니다.\n[INFO] markdownlint를 실행하여 마크다운 파일을 검사합니다...\n[SUCCESS] 모든 마크다운 파일이 린트 검사를 통과했습니다.\n```\n\n- 수동 검토를 통해 문서화된 8개 섹션(I-VIII) 모두의 존재와 정확성을 확인해야 하며, 이는 구현 명세에 제공된 내용과 일치해야 합니다.","핵심 `doxyfile` 설정을 기능별로 그룹화하여 설명하는 `parameters.md` 파일",[426,429,431,433,435],{"_24":427,"_83":39,"_84":428,"_85":61},"기본 프로젝트 설정 문서화 (이름, 버전)",19,{"_24":430,"_83":39,"_84":428,"_85":88},"소스 입력 및 분석 설정 설명",{"_24":432,"_83":39,"_84":428,"_85":91},"HTML 및 LaTeX 출력 형식 옵션 상세 설명",{"_24":434,"_83":39,"_84":428,"_85":94},"Graphviz를 통한 다이어그램 및 그래프 생성 안내",{"_24":436,"_83":39,"_84":428,"_85":97},"경고, 로깅, 사용자 정의 설정에 대한 참조","Doxygen 구성 파라미터 관리를 위한 참조 문서를 작성",{"_22":439,"_24":440,"_75":441,"_77":442,"_79":443,"_51":457,"_42":99},"task-1751364089724","마크다운 검증을 위한 CI 워크플로","# 작업: 마크다운 유효성 검사를 위한 CI 워크플로\n\n> **에픽**: 자동화된 가이드라인 유효성 검사를 위한 CI 파이프라인 구현\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: GitHub Actions 워크플로를 구현하여 마크다운 파일 서식을 자동으로 검사합니다.\n- **이유**: 이 작업의 목표는 유효성 검사 프로세스를 자동화하여, 저장소의 모든 문서가 정의된 서식과 스타일 표준을 따르도록 보장하는 것입니다. 서식 검사를 CI(지속적 통합) 파이프라인에 통합하면 일관성을 유지하고 수동 코드 리뷰 부담을 줄일 수 있습니다. 또한, 프로젝트의 \"구조화된 문서 저장소\" 아키텍처 무결성을 지킬 수 있습니다. 이 워크플로는 `Language Guidelines`에 명시된 규칙을 강제하는 핵심적인 역할을 수행합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: `main` 브랜치에 대한 `push` 및 `pull request` 시 실행되어 모든 가이드라인 문서를 검증하는 `ci.yml` 워크플로 파일.\n- **사양**:\n - **파일**: `.github/workflows/ci.yml`\n - **트리거**: 워크플로는 `main` 브랜치를 대상으로 하는 `push` 및 `pull_request` 이벤트 시에 실행되어야 합니다.\n - **실행 환경**: 작업(Job)은 `ubuntu-latest` 가상 환경에서 실행되어야 합니다.\n - **핵심 로직**: 워크플로는 `Prettier`와 `markdownlint-cli`를 설치 및 실행하여, 프로젝트의 설정 파일에 따라 모든 마크다운 파일(`**/*.md`)의 유효성을 검사해야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n└── .github/\n └── workflows/\n └── ci.yml <-- New\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 개발자의 코드 기여로 인해 트리거되는 CI 유효성 검사 흐름을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"개발자 작업\"\n A[개발자가 브랜치에
변경 사항을 푸시] --> B{'main'으로
Pull Request 생성};\n end\n\n subgraph \"GitHub Actions CI 파이프라인\"\n B --> C[트리거: 'ci.yml' 워크플로 시작];\n C --> D[설정: 코드 체크아웃 및 Node.js 설치];\n D --> E[설치: npm install prettier markdownlint-cli];\n E --> F{\"검사 전용 모드로 린터 실행\"};\n F -- \"파일 서식이 올바름\" --> G[상태: 성공];\n F -- \"서식 오류 발견\" --> H[상태: 실패];\n end\n\n subgraph \"결과\"\n G --> I[Pull Request에
'모든 검사 통과' 표시];\n H --> J[Pull Request에
'일부 검사에 실패함' 표시];\n end\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 아래 항목들을 완료해야 합니다. 이것은 개략적인 체크리스트이며, 각 항목에 대한 자세한 구현은 3장에 있습니다.\n\n- [ ] `push` 및 `pull_request` 이벤트를 위한 워크플로 트리거 설정\n- [ ] `ubuntu-latest`에서 실행되도록 작업(Job) 설정\n- [ ] Node.js 환경 설정 단계\n- [ ] Prettier 및 markdownlint-cli 의존성 설치 단계\n- [ ] Prettier 검사 모드 실행 단계\n- [ ] 프로젝트 설정을 사용한 markdownlint 실행 단계\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 저장소\n- **관련 주요 구성 요소**:\n - **자동화 도구**: 이 작업은 자동화 도구 구성 요소의 핵심 부분을 직접 구현합니다. `ci.yml` 파일은 유효성 검사 프로세스를 코드로 정의하며, 자동화된 품질 관리를 위한 핵심 자산이 됩니다.\n - **언어 가이드라인**: CI 워크플로는 마크다운 관련 `Language Guidelines`에 문서화된 규칙을 강제하도록 설계되었습니다. 이 워크플로는 해당 문서에 정의된 표준을 기술적으로 강제하는 역할을 합니다.\n - **GitHub Actions**: 이는 워크플로를 호스팅하고 실행하는 데 사용되는 기본 CI/CD 플랫폼(`tool`)입니다. YAML 파일 구조, 구문 및 사용 가능한 액션은 이 기술에 의해 결정됩니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `.github/workflows/ci.yml`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `Step`(단계)은 **완료 조건**의 각 항목에 해당합니다. 각 `Step`은 세분화된 `Action`(조치)으로 나뉩니다. 각 `Action`에 대해 제목, 명확한 설명('무엇을', '왜' 하는지 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `push` 및 `pull_request` 이벤트를 위한 워크플로 트리거 설정\n\n#### 1. 워크플로 이름 및 트리거 정의\n\n이 조치는 워크플로의 정체성과 실행 트리거를 설정합니다. `name`은 GitHub UI에서 사람이 읽을 수 있는 식별자를 제공합니다. `on` 블록은 `main` 브랜치에 코드가 푸시되거나 `main`을 대상으로 하는 풀 리퀘스트가 열리거나 업데이트될 때마다 워크플로가 자동으로 실행되도록 설정합니다. 이를 통해 모든 변경 사항이 병합되기 전에 유효성을 검사할 수 있습니다.\n\n**파일**: `.github/workflows/ci.yml`\n\n```yaml\nname: Markdown Style Check\n\non:\n push:\n branches:\n - main\n pull_request:\n branches:\n - main\n```\n\n---\n\n### 단계 2: `ubuntu-latest`에서 실행되도록 작업(Job) 설정\n\n#### 1. 린팅 작업(Job) 구성\n\n이 조치는 유효성 검사 단계를 위한 메인 작업 컨테이너를 정의합니다. `job`은 동일한 러너에서 실행되는 단계들의 집합입니다. `runs-on: ubuntu-latest`를 지정하여 GitHub에서 제공하는 깨끗하고 표준적인 리눅스 환경을 사용합니다. 이는 Node.js 기반 도구에 대해 보편적이고 신뢰할 수 있는 선택입니다.\n\n**파일**: `.github/workflows/ci.yml`\n\n```yaml\n# ... (on block)\n\njobs:\n lint-and-format-check:\n name: Lint and Format Check\n runs-on: ubuntu-latest\n\n steps:\n # ... (steps will be added here)\n```\n\n---\n\n### 단계 3: Node.js 환경 설정 단계\n\n#### 1. 저장소 코드 체크아웃\n\n이 조치는 공식 `actions/checkout` 액션을 사용하여 저장소 코드의 사본을 러너 환경으로 다운로드합니다. 후속 단계에서 유효성 검사를 수행하려면 프로젝트 파일(마크다운 문서, 린터 설정)에 접근해야 하므로 이는 필수적인 전제 조건입니다.\n\n**파일**: `.github/workflows/ci.yml`\n\n```yaml\n# ... (jobs block)\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@v3\n```\n\n#### 2. Node.js 환경 설정\n\n이 조치는 `actions/setup-node` 액션을 사용하여 특정 Node.js 버전으로 러너를 구성합니다. `Prettier`와 `markdownlint-cli`는 모두 Node.js 패키지이므로, 이들을 설치하고 실행하는 데 필요한 런타임 환경을 만드는 데 이 단계는 필수적입니다. 안정성과 호환성을 위해 버전 `18`을 지정합니다.\n\n**파일**: `.github/workflows/ci.yml`\n\n```yaml\n# ...\n\n steps:\n - name: Checkout repository\n # ...\n - name: Set up Node.js\n uses: actions/setup-node@v3\n with:\n node-version: \"18\"\n```\n\n---\n\n### 단계 4: Prettier 및 markdownlint-cli 의존성 설치 단계\n\n#### 1. 린터 의존성 설치\n\n이 조치는 Node Package Manager (`npm`)를 사용하여 필요한 도구를 설치하는 셸 명령을 실행합니다. `prettier`는 코드 포맷터이고, `markdownlint-cli`는 린터입니다. 이들은 작업(job) 범위 내에서 전역(`-g`)으로 설치되어 후속 단계에서 커맨드 라인 프로그램으로 실행될 수 있습니다.\n\n**파일**: `.github/workflows/ci.yml`\n\n```yaml\n# ...\n\n - name: Set up Node.js\n # ...\n - name: Install dependencies\n run: npm install -g prettier markdownlint-cli\n```\n\n---\n\n### 단계 5: Prettier 검사 모드 실행 단계\n\n#### 1. Prettier를 실행하여 서식 검사\n\n이 조치는 Prettier를 실행하여 프로젝트의 모든 마크다운 파일에 대한 서식의 유효성을 검사합니다. `--check` 플래그는 매우 중요합니다. 이 플래그는 어떤 파일이 올바르게 포맷되지 않았는지 보고하고, 파일을 수정하지 않은 채로 해당 단계를 실패시킵니다. `**/*.md` 글로브 패턴은 디렉터리 구조 내 위치와 관계없이 모든 마크다운 파일이 `.prettierrc.json` 설정에 따라 검사되도록 보장합니다.\n\n**파일**: `.github/workflows/ci.yml`\n\n```yaml\n# ...\n\n - name: Install dependencies\n # ...\n - name: Run Prettier check\n run: prettier --check \"**/*.md\"\n```\n\n---\n\n### 단계 6: 프로젝트 설정을 사용한 markdownlint 실행 단계\n\n#### 1. Markdownlint를 실행하여 스타일 및 구조 검사\n\n이 마지막 조치는 `markdownlint` CLI를 실행하여 단순한 서식을 넘어서는 스타일 및 구조적 문제를 검사합니다. `--config` 플래그를 사용하여 프로젝트의 특정 규칙 세트가 담긴 `.markdownlint.jsonc` 파일을 지정합니다. Prettier 단계와 마찬가지로, 이 명령은 규칙 위반이 발견되면 워크플로를 실패시켜 커밋된 모든 문서가 높은 품질을 유지하도록 보장합니다.\n\n**파일**: `.github/workflows/ci.yml`\n\n```yaml\n# ...\n\n - name: Run Prettier check\n # ...\n - name: Run markdownlint check\n run: markdownlint --config .markdownlint.jsonc \"**/*.md\"\n```\n\n---\n\n## 4. 검증 절차\n\n### 4.1. 검증 단계\n\n1. `main`에서 새 브랜치를 생성합니다.\n2. 새 `.github/workflows/ci.yml` 파일을 이 브랜치에 커밋합니다.\n3. **실패 케이스**를 테스트하기 위해, 임의의 `README.md` 파일에 의도적으로 서식 오류를 만듭니다(예: 제목과 목록 사이의 빈 줄 제거). 이 변경 사항을 커밋하고 푸시합니다.\n4. 생성한 브랜치에서 `main`으로 풀 리퀘스트를 생성합니다.\n5. 풀 리퀘스트의 \"Checks\" 섹션에서 \"Markdown Style Check\" 워크플로가 실행되고 실패하는 것을 확인합니다.\n6. **성공 케이스**를 테스트하기 위해, 로컬에서 서식 오류를 수정합니다(예: 로컬 포맷터 스크립트를 실행하거나 파일을 직접 수정). 수정 사항을 커밋하고 푸시합니다.\n7. \"Markdown Style Check\" 워크플로가 다시 실행되어 녹색 체크 표시와 함께 통과하는 것을 확인합니다.\n\n### 4.2. 예상 결과\n\n- **실패 시**: GitHub Actions 탭의 워크플로 실행에 빨간색 'X'가 표시됩니다. 실패한 단계(예: `Run Prettier check`)의 로그에는 서식이 필요한 파일을 나타내는 오류 메시지가 표시됩니다.\n\n```\n[warn] Checking formatting...\n[warn] principles/core-philosophy.md\n[error] Code style issues found in the above file(s). Forgot to run Prettier?\nError: Process completed with exit code 1.\n```\n\n- **성공 시**: 워크플로가 성공적으로 완료됩니다. 풀 리퀘스트에는 \"Markdown Style Check\" 워크플로 옆에 녹색 체크 표시와 함께 \"모든 검사를 통과했습니다\"와 같은 메시지가 표시됩니다.","main 브랜치에 대한 push 및 pull request 시 실행되어 모든 가이드라인 문서를 검증하는 `ci.yml` 워크플로 파일",[444,447,449,451,453,455],{"_24":445,"_83":39,"_84":446,"_85":61},"`push` 및 `pull_request` 이벤트를 위한 워크플로 트리거 구성",20,{"_24":448,"_83":39,"_84":446,"_85":88},"`ubuntu-latest`에서 실행되도록 작업 설정",{"_24":450,"_83":39,"_84":446,"_85":91},"Node.js 환경 설정 단계",{"_24":452,"_83":39,"_84":446,"_85":94},"Prettier 및 markdownlint-cli를 위한 의존성 설치 단계",{"_24":454,"_83":39,"_84":446,"_85":97},"Prettier를 확인 모드로 실행하는 단계",{"_24":456,"_83":39,"_84":446,"_85":176},"프로젝트 구성을 사용하여 markdownlint를 실행하는 단계","마크다운 파일 서식을 자동으로 확인하는 GitHub Actions 워크플로를 구현",{"_22":459,"_24":460,"_75":461,"_77":462,"_79":463,"_51":477,"_42":99},"task-1751364163736","마크다운 포매터 실행을 위한 로컬 스크립트","# 작업: 마크다운 포매터 실행을 위한 로컬 스크립트\n\n> **Epic**: 로컬 포매터 실행 스크립트 구현\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 프로젝트 내 모든 마크다운 파일의 포매팅과 린팅을 자동화하는 쉘 스크립트를 개발합니다.\n- **근거**: 프로젝트의 마크다운 스타일 및 포매팅 가이드라인을 강제하기 위한 표준화된 로컬 메커니즘을 제공합니다. 이 스크립트는 `Automation Tooling` 컴포넌트의 핵심 부분으로, 모든 문서 기여가 버전 관리에 커밋되기 전에 일관성을 유지하도록 보장합니다. 이를 통해 CI 파이프라인 실패를 줄이고 전체 기술 자료의 가독성과 품질을 유지할 수 있습니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: 의존성을 확인하고, Prettier와 markdownlint로 수정 사항을 적용한 후, 요약 보고서를 출력하는 실행 가능한 `run_formatters.sh` 스크립트.\n- **사양**:\n - **스크립트 이름**: `run_formatters.sh`\n - **권한**: 실행 가능 (`+x`)\n - **의존성**: `git`, `prettier`, `markdownlint`\n - **핵심 로직**: 스크립트는 모든 `.md` 파일을 찾아 포매터를 실행하고, `git diff`를 사용해 변경 사항을 보고해야 합니다.\n - **함수**: 주 로직을 위한 `main()` 함수와 보고를 위한 `print_summary()` 헬퍼 함수를 구현합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── scripts/\n# └── executables/\n# └── run_formatters.sh <-- 수정됨\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n A[\"시작\"] --> B{\"의존성 확인
(git, prettier, markdownlint)\"};\n B -- \"모두 발견\" --> C[\"모든 *.md 파일 찾기\"];\n B -- \"누락\" --> B_Fail[\"오류와 함께 종료\"];\n C --> D[\"파일에 Prettier 실행\"];\n D --> E[\"파일에 markdownlint 실행\"];\n E --> F[\"git diff로
수정된 파일 식별\"];\n F --> G[\"요약 보고서
생성 및 출력\"];\n G --> H[\"종료\"];\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현 내용은 3절에 있습니다.\n\n- [ ] `git`, `prettier`, `markdownlint`에 대한 의존성 검증 로직.\n- [ ] `.git` 및 `node_modules`를 제외하고 모든 마크다운 파일을 찾는 로직.\n- [ ] 대상 파일에 `prettier --write` 실행.\n- [ ] 프로젝트 설정을 사용하여 `markdownlint --fix` 실행.\n- [ ] `git diff`를 사용하여 수정된 파일을 감지하고 목록을 만드는 로직.\n- [ ] 실행 결과에 대한 포맷된 요약 보고서.\n\n## 2. 기술적 컨텍스트\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 구조화된 문서 리포지토리\n- **관련 주요 컴포넌트**:\n - **Automation Tooling**: 이 스크립트는 이 컴포넌트의 핵심 요소입니다. 개발자에게 문서화된 표준을 자동으로 강제하는 로컬 도구를 제공하여 다른 컴포넌트의 규칙을 코드화하는 책임을 집니다.\n - **Language Guidelines**: 이 스크립트는 `Markdown Coding Style Guide`에 정의된 특정 마크다운 스타일과 포매팅 규칙을 강제함으로써 이 컴포넌트에 직접적으로 기여합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `scripts/executables/run_formatters.sh`\n\n## 3. 구현 사양\n\n> **참고**: 아래 각 `Step`은 **인수 조건**의 항목에 해당합니다. 각 `Step`은 일련의 세부적인 `Action`으로 나뉩니다. 각 `Action`에 대해 제목, 명확한 서술적 설명('무엇을', '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### Step 1: `git`, `prettier`, `markdownlint`에 대한 의존성 검증 로직\n\n#### 1. 명령어 존재 여부 확인 로직 구현\n\n이 액션은 필요한 모든 커맨드 라인 도구(`git`, `prettier`, `markdownlint`)가 설치되어 시스템의 PATH에서 사용 가능한지 확인함으로써 스크립트의 안정성을 보장합니다. 의존성을 미리 확인하여, 스크립트 실행 중 모호한 'command-not-found' 오류로 실패하는 대신, 사용자 친화적인 명확한 오류 메시지와 함께 빠르게 실패하도록 만듭니다. 이는 개발자가 필요한 설치 스크립트를 실행하도록 안내합니다.\n\n**파일**: `scripts/executables/run_formatters.sh`\n\n```shell\n# --- Dependency Validation ---\n\nfor cmd in git prettier markdownlint; do\n if ! command -v \"$cmd\" >/dev/null; then\n printf \"Error: Required command '%s' is not installed.\\\\n\" \"$cmd\" >&2\n printf \"Please run the appropriate installation script from scripts/install/os/\\\\n\" >&2\n exit 1\n fi\ndone\n```\n\n---\n\n### Step 2: `.git`과 `node_modules`를 제외한 모든 마크다운 파일을 찾는 로직\n\n#### 1. 프로젝트 루트 디렉토리 결정\n\n이 액션은 스크립트가 프로젝트 내 어디에서든 호출될 수 있도록 합니다. `git rev-parse --show-toplevel`을 사용하여 Git 리포지토리의 루트를 안정적으로 찾은 다음, 현재 디렉토리를 해당 루트로 변경합니다. 이를 통해 모든 후속 파일 경로와 `find` 명령어가 일관되고 예측 가능한 기준 위치에서 작동하게 되어 스크립트의 견고성을 높입니다.\n\n**파일**: `scripts/executables/run_formatters.sh`\n\n```shell\nmain() {\n # 스크립트가 어디서 실행되든 상관없이 프로젝트 루트 디렉토리를 가져옵니다.\n PROJECT_ROOT=$(git rev-parse --show-toplevel)\n cd \"$PROJECT_ROOT\"\n ...\n}\n```\n\n#### 2. 대상 마크다운 파일 모두 찾기\n\n이 액션은 `find` 명령어를 사용하여 `.md` 확장자를 가진 모든 파일을 재귀적으로 검색합니다. `.git/`과 `node_modules/` 디렉토리를 명시적으로 제외하는 것이 중요합니다. 이는 포매터가 내부 버전 관리 파일이나 서드파티 의존성을 수정하려는 시도를 방지하여 오류와 원치 않는 부작용을 막습니다.\n\n**파일**: `scripts/executables/run_formatters.sh`\n\n```shell\n ...\n printf \"%bRunning Markdown formatters in: %s%b\\\\n\" \"$COLOR_CYAN\" \"$PROJECT_ROOT\" \"$COLOR_RESET\"\n\n # .git 또는 node_modules에 있는 파일을 제외하고 모든 마크다운 파일을 찾습니다.\n FILES_TO_CHECK=$(find . -name \"*.md\" -not -path \"./.git/*\" -not -path \"./node_modules/*\")\n\n if [ -z \"$FILES_TO_CHECK\" ]; then\n printf \"No Markdown files to check. Exiting.\\\\n\"\n exit 0\n fi\n ...\n```\n\n---\n\n### Step 3: 대상 파일에 `prettier --write` 실행\n\n#### 1. 파일 목록을 Prettier로 파이핑하여 인플레이스(in-place) 포매팅 수행\n\n이 액션은 찾아낸 마크다운 파일 목록에 대해 Prettier 포매터를 실행합니다. `--write` 플래그는 Prettier가 프로젝트의 `.prettierrc` 설정 파일에 정의된 규칙에 따라 파일을 직접 수정하도록 지시합니다. `xargs`를 사용하면 스크립트가 많은 수의 파일을 효율적으로 처리할 수 있습니다. 이것이 스타일 일관성을 강제하는 주요 액션입니다.\n\n**파일**: `scripts/executables/run_formatters.sh`\n\n```shell\n ...\n # 포매터를 실행합니다.\n printf \"\\\\n%b--- Running Prettier ---%b\\\\n\" \"$COLOR_GRAY\" \"$COLOR_RESET\"\n echo \"$FILES_TO_CHECK\" | xargs prettier --write --log-level warn\n ...\n```\n\n---\n\n### Step 4: 프로젝트 설정을 사용하여 `markdownlint --fix` 실행\n\n#### 1. 파일 목록을 markdownlint로 파이핑하여 자동 수정 수행\n\n이 액션은 동일한 파일 목록에 대해 markdownlint 린터를 실행합니다. `--fix` 플래그는 프로젝트별 설정 파일(`.markdownlint.jsonc`)에 기반하여 발견된 모든 규칙 위반을 자동으로 수정하려고 시도합니다. 이 단계는 Prettier가 다루지 않는 구조적, 의미적 규칙을 강제하여 포괄적인 문서 품질을 보장합니다.\n\n**파일**: `scripts/executables/run_formatters.sh`\n\n```shell\n ...\n printf \"\\\\n%b--- Running markdownlint ---%b\\\\n\" \"$COLOR_GRAY\" \"$COLOR_RESET\"\n echo \"$FILES_TO_CHECK\" | xargs markdownlint --config .markdownlint.jsonc --fix\n ...\n```\n\n---\n\n### Step 5: `git diff`를 사용하여 수정된 파일을 감지하고 목록을 만드는 로직\n\n#### 1. 포매터 수정 사항을 분리하기 위해 현재 모든 변경 사항을 스테이징\n\n이 액션은 `git add .`를 사용하여 개발자의 작업 디렉토리에 있는 모든 스테이징되지 않은 변경 사항을 스테이징합니다. 이는 `git diff`를 위한 깨끗한 기준선을 만듭니다. 이렇게 함으로써 스크립트는 관련 없는 로컬 변경 사항과 섞이지 않고, 후속 단계에서 포매터에 의해서만 수정된 파일을 정확하게 식별할 수 있습니다.\n\n**파일**: `scripts/executables/run_formatters.sh`\n\n```shell\n ...\n # 포매터의 변경 사항을 분리하기 위해 현재 모든 변경 사항을 스테이징합니다.\n git add .\n\n # 포매터를 실행합니다.\n ...\n```\n\n#### 2. 파일들을 순회하며 `git diff`를 사용하여 변경 사항 감지\n\n이 액션은 확인된 파일 목록을 순회하며 각 파일에 대해 `git diff --quiet`를 실행합니다. 이 명령어는 파일의 현재 상태(포매팅 후)와 Git 인덱스에 있는 상태(포매팅 전)를 비교합니다. 차이점이 감지되면 파일 경로가 목록에 추가되고 카운터가 증가합니다. 이것이 최종 보고서를 위한 데이터를 수집하는 핵심 로직입니다.\n\n**파일**: `scripts/executables/run_formatters.sh`\n\n```shell\n ...\n local modified_files=\"\"\n local modified_count=0\n local total_count=0\n\n for file in $FILES_TO_CHECK; do\n total_count=$((total_count + 1))\n if ! git diff --quiet -- \"$file\"; then\n modified_count=$((modified_count + 1))\n modified_files=\"${modified_files}\\\\n - ${file}\"\n fi\n done\n ...\n```\n\n#### 3. Git 인덱스를 원래 상태로 복원\n\n이 액션은 `git reset`을 실행하여 프로세스 초기에 임시로 추가되었던 변경 사항들을 언스테이징합니다. 이는 개발자의 Git 스테이징 영역을 원래 상태로 복원하는 중요한 정리 단계로, 스크립트가 사용자의 워크플로우에 의도치 않은 부작용을 일으키지 않도록 보장합니다.\n\n**파일**: `scripts/executables/run_formatters.sh`\n\n```shell\n ...\n print_summary \"$total_count\" \"$modified_count\" \"$modified_files\"\n\n # git 인덱스를 원래 상태로 복원합니다.\n printf \"\\\\n%bRestoring git index...%b\\\\n\" \"$COLOR_GRAY\" \"$COLOR_RESET\"\n git reset >/dev/null\n}\n```\n\n---\n\n### Step 6: 실행 결과에 대한 포맷된 요약 보고서\n\n#### 1. 전용 요약 출력 함수 구현\n\n이 액션은 모든 출력 로직을 `print_summary()`라는 단일 헬퍼 함수로 캡슐화합니다. 이는 코드 구성과 가독성을 향상시킵니다. 이 함수는 ANSI 색상 코드를 사용하여 확인된 총 파일 수, 수정된 파일 수, 그리고 수정된 파일 목록을 강조하는 명확하고 시각적으로 구분되는 보고서를 제공하여, 사용자에게 스크립트의 결과를 즉시 명확하게 보여줍니다.\n\n**파일**: `scripts/executables/run_formatters.sh`\n\n```shell\n# --- Helper Functions ---\n\nprint_summary() {\n local total_count=$1\n local modified_count=$2\n local modified_files=$3\n\n printf \"\\\\n%b=====================================%b\\\\n\" \"$COLOR_GREEN\" \"$COLOR_RESET\"\n printf \"%b Markdown Formatting Summary %b\\\\n\" \"$COLOR_GREEN\" \"$COLOR_RESET\"\n printf \"%b=====================================%b\\\\n\" \"$COLOR_GREEN\" \"$COLOR_RESET\"\n printf \" Total files checked: %s\\\\n\" \"$total_count\"\n printf \" Files auto-formatted: %s\\\\n\" \"$modified_count\"\n\n if [ \"$modified_count\" -gt 0 ]; then\n printf \" Modified files list:\\\\n\"\n printf \"%b%b%b\\\\n\" \"$COLOR_YELLOW\" \"$modified_files\" \"$COLOR_RESET\"\n printf \"\\\\n%bNOTE: Formatting changes have been applied. Please review and commit them.%b\\\\n\" \"$COLOR_YELLOW\" \"$COLOR_RESET\"\n else\n printf \"%bAll files are correctly formatted!%b\\\\n\" \"$COLOR_GREEN\" \"$COLOR_RESET\"\n fi\n printf \"%b=====================================%b\\\\n\\\\n\" \"$COLOR_GREEN\" \"$COLOR_RESET\"\n}\n```\n\n#### 2. 주 로직의 끝에서 요약 함수 호출\n\n이 액션은 `print_summary` 함수를 호출하여 보고서 생성을 시작합니다. `git diff` 루프 동안 수집된 카운터와 수정된 파일 목록을 전달합니다. 이것이 스크립트가 정리하고 종료하기 전의 주 실행 흐름의 마지막 단계입니다.\n\n**파일**: `scripts/executables/run_formatters.sh`\n\n```shell\n ...\n for file in $FILES_TO_CHECK; do\n ...\n done\n\n print_summary \"$total_count\" \"$modified_count\" \"$modified_files\"\n\n # git 인덱스를 원래 상태로 복원합니다.\n ...\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n개발자는 스크립트의 올바른 구현을 검증하기 위해 다음 작업을 수행해야 합니다.\n\n```bash\n# 1. OS에 맞는 설치 스크립트(예: scripts/install/os/macos.sh)를 실행하여\n# 모든 의존성이 설치되었는지 확인합니다.\n\n# 2. 테스트를 위해 서식이 잘못된 임시 마크다운 파일을 생성합니다.\n# 내용을 문자 그대로 보존하기 위해 작은따옴표를 사용한 점에 유의하세요.\necho '#bad header\n\n- un-ordered list item 1\n- un-ordered list item 2\n\n' > test-format.md\n\n# 3. 포매터 스크립트를 실행 가능하게 만듭니다.\nchmod +x scripts/executables/run_formatters.sh\n\n# 4. 프로젝트 루트에서 포매터 스크립트를 실행합니다.\n./scripts/executables/run_formatters.sh\n\n# 5. 테스트 파일의 내용을 확인하여 포매팅되었는지 확인합니다.\ncat test-format.md\n\n# 6. 임시 파일을 정리합니다.\nrm test-format.md\n```\n\n### 4.2. 예상 결과\n\n검증 절차를 실행한 후, 스크립트 실행 시 터미널 출력은 하나의 파일이 자동 포매팅되었다고 보고해야 합니다.\n\n```\n# 스크립트 출력 (색상은 다를 수 있음)\n=====================================\n 마크다운 포매팅 요약\n=====================================\n 확인한 총 파일 수: [숫자]\n 자동 포매팅된 파일: 1\n 수정된 파일 목록:\n - ./test-format.md\n\n참고: 포매팅 변경 사항이 적용되었습니다. 검토 후 커밋해주세요.\n=====================================\n```\n\n마지막 검증 단계의 `cat` 명령어는 `test-format.md`의 수정된 내용을 다음과 같이 표시해야 합니다:\n\n```markdown\n# bad header\n\n- un-ordered list item 1\n- un-ordered list item 2\n```","의존성을 확인하고, Prettier와 markdownlint로 수정 사항을 적용하며, 요약 보고서를 출력하는 실행 가능한 `run_formatters.sh` 스크립트",[464,467,469,471,473,475],{"_24":465,"_83":39,"_84":466,"_85":61},"`git`, `prettier`, `markdownlint`를 확인하는 의존성 검증 로직",21,{"_24":468,"_83":39,"_84":466,"_85":88},"`.git`과 `node_modules`를 제외하고 모든 마크다운 파일을 찾는 로직",{"_24":470,"_83":39,"_84":466,"_85":91},"대상 파일에 `prettier --write` 실행",{"_24":472,"_83":39,"_84":466,"_85":94},"프로젝트 구성을 사용하여 `markdownlint --fix` 실행",{"_24":474,"_83":39,"_84":466,"_85":97},"`git diff`를 사용하여 수정된 파일을 감지하고 목록화하는 로직",{"_24":476,"_83":39,"_84":466,"_85":176},"실행 결과에 대한 형식화된 요약 보고서","프로젝트의 모든 마크다운 파일에 대한 서식 지정 및 린팅을 자동화하는 셸 스크립트를 개발","optionPrices",[480,481],{"_28":29,"_26":27},{"_28":482,"_26":483},"github",50000,"earlybird_policies",[486],{"_22":487,"_488":23,"_489":490,"_26":491,"_492":493,"_494":495,"_496":497,"_42":99},"b43973bd-745b-47c6-9f31-9f7ce771c98d","product_id","type","EARLYBIRD",169150,"max_quantity",100,"start_at","2025-07-01T14:00:00.000Z","end_at","2025-07-08T14:59:00.000Z",{"_22":499,"_24":500,"_26":501,"_28":29,"_30":31,"_32":502,"_34":503,"_36":504,"_38":39,"_40":505,"_484":807},"ba4a70e0-b270-4912-9da0-9f752b36b2f3","C++ DevEnv Accelerator : 크로스플랫폼 C++ 환경 자동화",99000,"a439c68c-2d13-40d6-b97b-03b461f5439d","2025-06-20T09:11:06.491Z","2025-06-27T07:13:22.832Z",{"_22":502,"_24":500,"_42":506,"_44":31,"_45":46,"_47":507,"_49":508,"_51":509,"_53":510,"_55":39,"_56":511,"_58":59,"_60":61,"_62":61,"_63":512,"_70":517,"_478":804},"C++ 환경을 수동으로 구성하느라 며칠씩 허비하는 일은 이제 그만하세요. 이 프로젝트는 Clang 툴체인부터 VS Code 설정까지 전체 설치 과정을 자동화하는, 실전 테스트를 거친 단일 스크립트를 제공합니다. 명령어 하나로 macOS 또는 Linux에서 일관성 있는 전문가 수준의 개발 환경을 실행하고, 가장 중요한 일인 코드 작성에 다시 집중하세요.","예전에는 C++ 프로젝트를 위해 새 컴퓨터를 설정하는 것이 두려웠습니다. 제 Mac에서는 Homebrew를, Linux 서버에서는 APT를 다루며 Clang, CMake, VS Code가 서로 잘 작동하도록 애쓰는 것은... 알 수 없는 오류와 낭비되는 오후로 가득 찬 반복되는 악몽이었습니다. 모든 새로운 팀원은 똑같이 고통스러운 몇 시간짜리 학습 곡선을 겪어야 했고, 어느 두 설정도 정확히 같지 않았습니다.\n\n전환점은 간단한 OS 업데이트로 인해 팀의 절반이 사용하던 핵심 빌드 도구가 망가졌을 때 찾아왔습니다. 우리는 일관된 상태로 돌아가기 위해 하루를 꼬박 허비했습니다. 저는 우리가 단지 시간을 잃고 있는 것이 아니라, 추진력과 집중력을 잃고 있다는 것을 깨달았습니다. 수동 설정 과정은 실질적인 골칫거리가 되어버렸습니다.\n\n그때 저는 우리의 개발 환경을 하나의 제품처럼 다루기로 결심했습니다. 자동화되고, 테스트 가능하며, 절대적으로 신뢰할 수 있어야 했습니다. 저는 각 도구에 대해 작고 재사용 가능한 셸 스크립트를 만드는 것부터 시작했고, 이를 *멱등성* 있게, 즉 문제를 일으키지 않고 몇 번이고 안전하게 실행할 수 있도록 만드는 데 집중했습니다. 그런 다음 이들을 모두 하나로 묶는 오케스트레이션 스크립트를 구축했고, 이 스크립트는 OS를 자동으로 감지하고 올바른 단계를 순서대로 실행합니다.\n\n그 결과가 바로 이 프로젝트입니다. 예전에는 몇 시간 동안 좌절감을 느끼며 수동으로 해야 했던 작업이 이제는 `bash setup.sh`라는 단일 명령어로 끝납니다. 우리는 몇 분 만에 새로운 개발자를 온보딩하고, CI 파이프라인은 설정이 예기치 않게 중단되지 않도록 보장합니다. **여러분이** 시간을 되찾고 진정으로 중요한 것, 즉 훌륭한 소프트웨어를 만드는 데 집중할 수 있도록 이 프로젝트를 공유합니다.\n","# 프로젝트 명세서: readable-code-cpp-development-environment\n\n## 1. 프로젝트 정의\n\n### 1.1. 주요 목표\n\n- macOS 및 Linux에서 크로스 플랫폼 C++ 개발 환경 자동 설정.\n\n### 1.2. 핵심 기능\n\n- 모든 필수 도구를 단일 명령으로 설정.\n- macOS와 Linux 모두를 위한 크로스 플랫폼 지원.\n- 안전하고 반복 가능한 실행을 위한 멱등성 스크립트 실행.\n- 설정 확인을 위한 자동 검증 스크립트.\n\n### 1.3. 결과물\n\n- 단일 명령 실행을 위한 마스터 설정 스크립트 (`setup.sh`).\n- 도구 설치 확인을 위한 검증 스크립트 (`verify.sh`).\n- 플랫폼별 모듈식 설치 스크립트 모음.\n- 자동 테스트를 위한 지속적 통합 워크플로 (`ci.yml`).\n- 포괄적인 프로젝트 문서 (`README.md`).\n\n## 2. 시스템 아키텍처\n\n### 2.1. 아키텍처 패턴\n\n- **모듈식 스크립트 기반 오케스트레이션**: 중앙 스크립트(`setup.sh`)가 운영체제에 따라 더 작고 전문화된 재사용 가능한 스크립트에 작업을 위임하는 설계. 이를 통해 유지보수성과 관심사 분리를 촉진합니다.\n\n### 2.2. 의존성 다이어그램\n\n- 에픽 간의 빌드 의존성을 시각화한 다이어그램입니다. 프로젝트는 공통 기반에서 시작하여 플랫폼별 기능을 구축한 후, 최종적으로 검증 가능한 제품으로 통합됩니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n ShellFoundation[\"셸 스크립팅
기반\"]\n PlatformAbstractions[\"플랫폼별
설치 추상화\"]\n BuildToolchain[\"C++ 빌드 툴체인
설치\"]\n DevTools[\"개발자 생산성
도구 설치\"]\n VSCodeConfig[\"VS Code
구성\"]\n Orchestration[\"환경 오케스트레이션
및 샘플 프로젝트\"]\n VerificationScript[\"설치
검증 스크립트\"]\n CIWorkflow[\"지속적 통합
워크플로\"]\n Documentation[\"프로젝트 문서
및 README\"]\n\n ShellFoundation --> PlatformAbstractions\n PlatformAbstractions --> BuildToolchain\n PlatformAbstractions --> DevTools\n DevTools --> VSCodeConfig\n BuildToolchain --> Orchestration\n DevTools --> Orchestration\n VSCodeConfig --> Orchestration\n Orchestration --> VerificationScript\n VerificationScript --> CIWorkflow\n CIWorkflow --> Documentation\n```\n\n### 2.3. 프로그램 흐름\n\n- 아래의 시퀀스 다이어그램은 사용자가 시작하는 일반적인 실행 흐름을 설정부터 검증까지 보여줍니다.\n\n```mermaid\n%%{ init: { \"sequence\": { \"htmlLabels\": true } } }%%\nsequenceDiagram\n participant User as \"사용자\"\n participant SetupSH as \"setup.sh
(오케스트레이터)\"\n participant PlatformScripts as \"플랫폼별 스크립트
(macOS/Linux)\"\n participant CommonScripts as \"공통 스크립트\"\n participant VerifySH as \"verify.sh
(검증기)\"\n\n User->>SetupSH: \"`bash setup.sh` 실행\"\n SetupSH->>SetupSH: \"OS 감지 (macOS 또는 Linux)\"\n SetupSH->>PlatformScripts: \"도구 설치 프로그램 호출 (예: `install_clang.sh`)\"\n PlatformScripts-->>SetupSH: \"설치 확인\"\n SetupSH->>CommonScripts: \"공통 모듈 호출 (예: `configure_vscode.sh`)\"\n CommonScripts-->>SetupSH: \"구성 확인\"\n SetupSH->>User: \"설정 완료 보고\"\n\n User->>VerifySH: \"`bash verify.sh` 실행\"\n VerifySH->>VerifySH: \"PATH에서 필요한 CLI 도구 확인\"\n VerifySH-->>User: \"성공 또는 실패 보고\"\n```\n\n### 2.4. 구성 요소별 역할 및 책임\n\n- **setup.sh**\n - **역할:** 메인 진입점 및 오케스트레이터.\n - **상호작용:** 호스트 OS를 감지하고 모든 설치 및 구성 스크립트를 미리 정의된 순서로 실행하여 의존성이 충족되도록 보장합니다.\n- **verify.sh**\n - **역할:** 설정 후 검증.\n - **상호작용:** 독립적으로 작동하여 시스템 PATH에 모든 필수 도구가 존재하고 실행 가능한지 확인하며, 최종 성공 기준으로 사용됩니다.\n- **macos/scripts**\n - **역할:** macOS 특정 설치 프로그램.\n - **상호작용:** macOS 시스템에서 `setup.sh`에 의해 호출됩니다. Homebrew를 활용하여 모든 필수 도구와 애플리케이션을 설치하고 관리합니다.\n- **linux/scripts**\n - **역할:** Linux 특정 설치 프로그램.\n - **상호작용:** Linux 시스템에서 `setup.sh`에 의해 호출됩니다. `apt` 패키지 관리자를 사용하여 모든 필수 도구를 설치하고 관리합니다.\n- **common/scripts**\n - **역할:** OS에 구애받지 않는 구성 작업.\n - **상호작용:** 플랫폼별 설치 후 `setup.sh`에 의해 호출되어 VS Code 구성 및 샘플 프로젝트 스캐폴딩과 같이 두 운영체제에 공통적인 작업을 수행합니다.\n- **.github/workflows/ci.yml**\n - **역할:** 지속적 통합 워크플로.\n - **상호작용:** GitHub 호스팅 러너에서 `setup.sh` 및 `verify.sh` 스크립트를 자동으로 실행하여 모든 코드 변경에 대해 macOS와 Linux 모두에서 설정 프로세스의 무결성을 검증합니다.\n\n### 2.5. 기술 스택\n\n- **언어:**\n - Shell\n- **프레임워크:**\n - 해당 없음\n\n## 3. 디렉터리 구조\n\n### 3.1. 개요\n\n- 디렉터리 구조는 플랫폼별(macOS, Linux), 공통 및 CI 관련 스크립트를 위한 별도의 폴더로 관심사를 분리하여 명확성과 모듈성을 증진하도록 구성되었습니다.\n\n### 3.2. 폴더 트리\n\n```bash\n/\n├── .github/\n│ └── workflows/\n├── assets/\n├── documents/\n│ └── guidelines/\n└── scripts/\n └── cpp_development_environment/\n ├── common/\n ├── linux/\n └── macos/\n```\n\n## 4. 실행 계획\n\n프로젝트 실행은 계층적 접근 방식을 따르며, 기본적인 셸 스크립팅 표준 및 유틸리티에서 시작합니다. 그런 다음 macOS와 Linux를 위한 플랫폼별 추상화 계층을 구축하고, C++ 툴체인과 개발자 생산성 도구의 병렬 설치를 진행합니다. 마지막으로, 시스템은 오케스트레이션 스크립트, VS Code 구성, 검증 프로세스, CI 자동화 및 포괄적인 문서로 통합됩니다.\n\n---\n\n### 에픽 1: 셸 스크립팅 기반\n\n- **목표:** 로깅, OS 감지, 오류 처리를 위한 스타일 가이드 및 유틸리티 함수를 포함한 기본적인 셸 스크립팅 요소를 확립합니다.\n- **작업**\n - **1.1 셸 스크립트 코딩 스타일 가이드:** 스크립트 일관성을 위한 공식 규칙을 정의하여 원칙과 모범 사례를 담은 마크다운 문서를 만듭니다.\n - **1.2 OS에 구애받지 않는 유틸리티 스크립트:** 로깅, OS 감지, 프로그램 검증을 위한 재사용 가능한 함수의 중앙 집중식 스크립트를 만듭니다.\n\n### 에픽 2: 플랫폼별 설치 추상화\n\n- **목표:** macOS(Homebrew)와 Linux(APT)를 위한 멱등성 있는 플랫폼별 유틸리티 계층을 만들어 패키지 설치 및 검증을 추상화합니다.\n- **작업**\n - **2.1 macOS 설치 유틸리티 스크립트 (Homebrew):** 멱등성 있는 formula 및 cask 설치를 보장하기 위해 Homebrew용 추상화 계층을 개발합니다.\n - **2.2 Linux 설치 유틸리티 스크립트 (APT):** 일관된 패키지 설치와 캐시 관리를 보장하기 위해 APT용 추상화 계층을 개발합니다.\n\n### 에픽 3: C++ 빌드 툴체인 설치\n\n- **목표:** Clang, CMake, Ninja를 포함한 필수 C++ 빌드 툴체인의 크로스 플랫폼 설치를 자동화합니다.\n- **작업**\n - **3.1 크로스 플랫폼 Clang 스위트 설치:** macOS와 Linux 모두에 Clang 컴파일러와 관련 도구(clangd, clang-tidy, lldb)를 설치하는 스크립트를 만듭니다.\n - **3.2 크로스 플랫폼 CMake 설치:** 두 플랫폼 모두에서 핵심 의존성으로 CMake 빌드 시스템 생성기를 설치하는 스크립트를 만듭니다.\n - **3.3 크로스 플랫폼 Ninja 설치:** 두 플랫폼 모두에서 핵심 의존성으로 Ninja 빌드 시스템을 설치하는 스크립트를 만듭니다.\n\n### 에픽 4: 개발자 생산성 도구 설치\n\n- **목표:** 핵심 개발자 생산성 도구인 Git, GitHub CLI, Visual Studio Code, Fira Code 글꼴의 설치를 자동화합니다.\n- **작업**\n - **4.1 크로스 플랫폼 Git 설치:** 핵심 의존성으로 Git 버전 관리 시스템을 설치하는 스크립트를 만듭니다.\n - **4.2 크로스 플랫폼 GitHub CLI 설치:** Linux에서 사용자 정의 APT 리포지토리를 처리하며 `gh` 명령줄 도구를 설치하는 스크립트를 만듭니다.\n - **4.3 크로스 플랫폼 Visual Studio Code 설치:** 시스템별 패키지 유형(cask, deb)을 처리하며 VS Code 편집기를 설치하는 스크립트를 만듭니다.\n - **4.4 크로스 플랫폼 Fira Code 글꼴 설치:** 코드 가독성 향상을 위해 Fira Code 프로그래밍 글꼴을 설치하는 스크립트를 만듭니다.\n\n### 에픽 5: VS Code 구성\n\n- **목표:** 원활한 개발 경험을 위해 C++ 특정 설정 및 확장으로 VS Code 환경을 구성합니다.\n- **작업**\n - **5.1 VS Code 설정 템플릿:** 편집기 글꼴, 저장 시 서식 지정 동작, clangd 설정을 지정하는 C++ 개발용 표준화된 JSON 구성을 정의합니다.\n - **5.2 VS Code 구성 스크립트:** 필요한 확장을 멱등성 있게 설치하고 JSON 템플릿의 설정을 사용자 구성에 병합하는 스크립트를 개발합니다.\n\n### 에픽 6: 환경 오케스트레이션 및 샘플 프로젝트\n\n- **목표:** 메인 `setup.sh` 진입점을 개발하고 샘플 C++ 프로젝트를 스캐폴딩하여 즉각적이고 검증 가능한 결과를 제공합니다.\n- **작업**\n - **6.1 메인 오케스트레이션 스크립트 (`setup.sh`):** OS를 감지하고 모든 설치 및 구성 모듈을 올바른 순서로 실행하는 마스터 스크립트를 만듭니다.\n - **6.2 샘플 C++ 프로젝트 스캐폴딩 스크립트:** CMake를 사용하여 \"Hello, World\" C++ 프로젝트를 생성, 빌드 및 실행하여 완전히 작동하는 환경을 시연하는 스크립트를 만듭니다.\n\n### 에픽 7: 설치 검증 스크립트\n\n- **목표:** 모든 필수 도구가 설치되고 접근 가능한지 프로그래밍 방식으로 확인하는 독립적인 `verify.sh` 스크립트를 만듭니다.\n- **작업**\n - **7.1 검증 스크립트 (`verify.sh`):** 모든 필수 CLI 도구의 존재와 실행 가능성을 확인하고 누락된 것이 있으면 오류와 함께 종료하는 독립적인 스크립트를 개발합니다.\n\n### 에픽 8: 지속적 통합 워크플로\n\n- **목표:** macOS와 Linux 모두에서 설정 및 검증 스크립트를 자동으로 테스트하는 GitHub Actions 워크플로를 구현합니다.\n- **작업**\n - **8.1 GitHub Actions CI 워크플로:** 모든 변경 시 `setup.sh` 및 `verify.sh` 스크립트를 실행하여 크로스 플랫폼 호환성을 보장하는 `ci.yml` 워크플로 파일을 만듭니다.\n\n### 에픽 9: 프로젝트 문서 및 README\n\n- **목표:** 사용자와 기여자를 위한 기본 가이드 역할을 하는 포괄적인 `README.md` 파일을 만듭니다.\n- **작업**\n - **9.1 프로젝트 README 문서:** 프로젝트의 목적, 아키텍처, 설정 지침, 사용 가이드를 개괄적으로 설명하는 상세한 `README.md` 파일을 작성합니다.\n","> 환경 설정을 병목 현상에서 제거하고 C++ 개발 워크플로우를 표준화하세요.\n\nC++ 개발 환경 설정은 까다롭고 시간이 많이 소요되기로 악명 높습니다. macOS와 Linux 간의 불일치, 수동 도구 설치, 충돌하는 설정들은 생산성 저하와 불안정한 빌드 프로세스로 이어집니다. 이 프로젝트는 개발 환경을 코드로 취급하여 이 문제를 체계적으로 해결합니다.\n\n모듈형 스크립트 기반의 오케스트레이션 시스템을 제공하여 최신 C++ 환경 구성을 위한 모범 사례를 코드화합니다. 컴파일러, 빌드 도구, 에디터 설정을 자동화함으로써 팀의 모든 개발자와 모든 CI 실행이 검증 가능하고 동일한 기준점에서 동작하도록 보장합니다. 전문적인 C++ 환경을 귀찮은 작업이 아닌, 누구나 쉽게 사용할 수 있는 필수품으로 만드는 것이 목표입니다.","### 제공되는 것들\n\n- macOS 및 Linux용 자동화된 단일 명령어 설치 스크립트 (`setup.sh`)\n- `Clang`, `CMake`, `Ninja`를 포함한 완전한 최신 C++ 툴체인\n- 핵심 개발자 생산성 도구: `Git`, `GitHub CLI`, `Visual Studio Code`\n- 사용자 설정을 덮어쓰지 않으면서 필수 C++ 확장 프로그램을 설치하고 최적의 설정을 적용하는 지능형 VS Code 설정 스크립트\n- 설치가 성공적으로 완료되었는지 즉시 확인할 수 있는 독립형 검증 스크립트 (`verify.sh`)\n- 모든 업데이트에서 스크립트가 완벽하게 작동함을 보장하는 CI 워크플로우 파일 (`ci.yml`)\n\n### 기대할 수 있는 변화\n\n- **며칠이 아닌 단 몇 분 만에 완벽하게 작동하는 C++ IDE를 갖추세요.**\n- **로컬 머신과 CI/CD 파이프라인 간의 완벽한 일관성을 달성하세요.**\n- **명령어 하나로 새로운 개발자를 즉시 온보딩하고, 설치 과정의 마찰을 제거하세요.**\n- **언제든지 자신 있게 설치를 실행하세요.** 멱등성(idempotent)을 보장하는 설계로 기존 설정을 절대 손상시키지 않습니다.\n- **시스템 관리가 아닌 C++ 로직에 집중하세요.** 도구와 씨름하는 대신 문제 해결에 시간을 쏟으세요.","2025-06-27T07:13:22.699Z",[513,514,515,516],"C++ 개발자: 새로운 머신마다 빌드 도구와 린터를 수동으로 설정하는 데 지친 분","엔지니어링 매니저: 개발 환경을 표준화하고 팀 온보딩을 가속화하려는 분","DevOps 엔지니어: CI/CD 파이프라인을 위해 신뢰할 수 있고 스크립트 가능한 C++ 환경을 구축해야 하는 분","학생 또는 교육자: 학습을 위해 최신 C++ 툴체인을 설정하는 간단한 원스텝 프로세스가 필요한 분",[518,534,551,568,585,600,615,629,642,657,672,687,704,721,738,755,772,787],{"_22":519,"_24":278,"_75":520,"_77":521,"_79":522,"_51":533,"_42":99},"task-1751000527776","# 작업: 셸 스크립트 코딩 스타일 가이드\n\n> **에픽**: 셸 스크립팅 기초\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 셸 스크립트의 일관성과 가독성을 위한 공식적인 규칙 모음.\n- **근거**: 이 프로젝트의 아키텍처는 전적으로 셸 스크립트로 구성되어 있습니다 (`모듈식 스크립트 기반 오케스트레이션`). 필수적인 스타일 가이드를 제정하는 것은 장기적인 유지보수성, 가독성, 협업에 매우 중요합니다. 이는 모든 스크립트가 특정 기능과 관계없이 통일된 표준에 따라 작성되도록 보장하여, 개발자의 인지 부하를 줄이고 디버깅을 단순화하며 일반적인 스크립팅 오류를 방지합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 핵심 원칙, 서식 규칙, 스타일 모범 사례를 기술한 마크다운 문서.\n- **명세**: 최종 문서는 다음을 포함해야 합니다:\n - 버전, 생성일, 소유자가 포함된 메타데이터 헤더.\n - 견고함과 명확성 같은 상위 수준의 목표를 정의하는 \"핵심 원칙\" 섹션.\n - 이름 규칙과 같은 결정론적 규칙을 담은 \"서식\" 섹션.\n - 견고한 코드를 작성하기 위한 모범 사례를 상세히 설명하는 \"스타일 규칙\" 섹션.\n - 모든 규칙에 대해 대조적인 `GOOD` 및 `BAD` 예시.\n- **결과 파일 구조**\n\n```bash\n# ./\n└── documents/\n └── guidelines/\n └── shell_script/\n └── coding_styles.md <-- 수정됨\n```\n\n- **프로세스 흐름도**\n이 작업은 모든 실행 가능 스크립트의 개발 프로세스를 통제하는 가이드라인을 생성합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph A [\"개발 워크플로\"]\n Dev[\"개발자\"] -- \"읽음\" --> StyleGuide[\"셸 스크립트
코딩 스타일 가이드\"];\n StyleGuide -- \"정보 제공\" --> Dev;\n Dev -- \"스크립트 작성/수정\" --> Script[\"예: install_clang.sh\"];\n Script -- \"준수해야 함\" --> StyleGuide;\n end\n subgraph B[\"CI/CD 파이프라인\"]\n CodeReview[\"동료/자동화
코드 리뷰\"] -- \"준수 여부 검증\" --> Script;\n end\n A --> B\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 상세 구현은 섹션 3에 있습니다.\n\n- [ ] 견고함과 명확성 같은 핵심 원칙 정의.\n- [ ] 이름 규칙을 포함한 서식 섹션.\n- [ ] 모범 사례를 포함한 스타일 규칙 섹션.\n- [ ] 좋은 사례와 나쁜 사례에 대한 예시.\n- [ ] 명확한 버전 및 소유권 헤더.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 스크립트 기반 오케스트레이션\n- **관련 주요 구성 요소**:\n - **모든 스크립팅 구성 요소**: 이 스타일 가이드는 리포지토리 내 모든 현재 및 미래의 셸 스크립트에 대한 구현 표준을 지시하는 기초 문서입니다. 그 영향은 다방면에 걸치며 다음 주요 구성 요소에 영향을 줍니다:\n - `setup.sh`: 메인 오케스트레이터는 명확성과 견고함을 위해 이 규칙들을 준수해야 합니다.\n - `verify.sh`: 검증 스크립트는 검사의 신뢰성을 보장하기 위해 가이드를 따라야 합니다.\n - `macos/scripts/*`: 모든 macOS 특정 설치 스크립트는 이 표준에 따라 작성되어야 합니다.\n - `linux/scripts/*`: 모든 Linux 특정 설치 스크립트는 이 표준에 따라 작성되어야 합니다.\n - `common/scripts/*`: 모든 OS에 구애받지 않는 스크립트는 프로젝트 전반의 일관성을 보장하기 위해 준수해야 합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `documents/guidelines/shell_script/coding_styles.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `조치`로 나뉩니다. 각 `조치`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 견고함과 명확성 같은 핵심 원칙 정의\n\n#### 1. 핵심 원칙 섹션 수립\n\n이 조치는 문서의 다른 모든 규칙에 대한 철학적 기반을 정의하는 것입니다. 이 섹션은 뒤따르는 엄격한 규칙들 뒤에 있는 '왜'를 설명합니다. 스크립트는 견고해야 하고(고장 안전), 자체적으로 문서화되어야 하며(명확한 이름), 명시적이어야 하고(약어 사용 금지), 의미적으로 명확해야 한다는 점을 분명히 해야 합니다. 이러한 원칙들은 개발자들이 일관된 결정을 내리는 데 지침이 됩니다.\n\n**파일**: `documents/guidelines/shell_script/coding_styles.md`\n\n```markdown\n...\n## 2. 핵심 원칙\n\n### 원칙 1 견고하고 고장 안전한 스크립트를 작성하라\n\n- **범위** 모든 스크립트.\n- **근거** 암묵적 오류를 방지하고 실패 시 스크립트가 즉시 종료되도록 보장하여, 신뢰성을 높이고 디버깅을 단순화합니다.\n\n### 원칙 2 자체적으로 문서화되는 코드를 작성하라\n\n- **범위** 모든 변수, 함수, 타겟.\n- **근거** 명확하고 서술적인 이름은 설명 주석의 필요성을 줄여, 빌드 로직을 더 쉽게 이해하고 유지보수할 수 있게 합니다.\n\n### 원칙 3 약어를 사용하지 말라\n\n- **범위** 모든 식별자 (변수, 함수, 타겟 등).\n- **근거** 전체 단어를 사용하면 명확성이 보장되어 코드를 처음 보는 사람도 그 의도를 쉽게 파악할 수 있습니다.\n\n### 원칙 4 의미적으로 명확한 이름을 사용하라\n\n- **범위** 모든 식별자.\n- **근거** 이름은 요소의 목적이나 내용을 명확하게 설명해야 합니다. 이것은 코드의 역할을 반영하고 빌드 프로세스를 이해하는 데 도움이 됩니다.\n...\n```\n\n---\n\n### 단계 2: 이름 규칙을 포함한 서식 섹션\n\n#### 1. 이름 규칙을 포함한 서식 섹션 정의\n\n이 조치는 객관적이고 강제할 수 있는 서식 규칙을 수립합니다. 주된 초점은 일관성에 매우 중요한 이름 규칙에 있습니다. 모호함을 없애기 위해 변수, 함수, 파일 이름에 대한 명확한 테이블을 정의합니다. 추가로, 셰뱅(shebang)의 의무적 사용과 같은 다른 결정론적 규칙도 포함합니다.\n\n**파일**: `documents/guidelines/shell_script/coding_styles.md`\n\n```markdown\n...\n## 3. 서식\n>\n> **설명** 이름 규칙, 들여쓰기, 줄 길이 등과 같이 **린터/포맷터에 의해 100% 강제될 수 있는 규칙**을 포함합니다.\n\n### 3.1 이름 규칙\n\n| 코드 요소 | 이름 스타일 | 예시 |\n|---|---|---|\n| 전역/환경 변수 | `UPPER_SNAKE_CASE` | `SCRIPT_DIR`, `API_KEY` |\n| 지역 변수 | `lower_snake_case` | `local user_name` |\n| 함수 | `lower_snake_case` | `install_package()` |\n| 파일 이름 | `lower_snake_case` | `install_dependencies.sh` |\n...\n```\n\n---\n\n### 단계 3: 모범 사례를 포함한 스타일 규칙 섹션\n\n#### 1. 스타일 규칙 섹션 정의\n\n이 조치는 더 견고하고 가독성 있는 스크립트를 만드는 모범 사례를 성문화합니다. 이것들은 핵심 원칙을 직접적으로 지원하는 스타일적인 선택입니다. 이 섹션에는 엄격한 오류 검사(`set -euo pipefail`), 단어 분리 문제를 방지하기 위한 변수 인용, 더 나은 가독성과 중첩 기능을 위한 최신 명령어 치환 사용에 대한 규칙을 포함해야 합니다.\n\n**파일**: `documents/guidelines/shell_script/coding_styles.md`\n\n```markdown\n...\n## 4. 스타일 규칙\n\n### 4.1 스크립팅 모범 사례\n\n설명 견고하고 가독성 있는 셸 스크립트 코드를 작성하기 위한 가이드라인입니다.\n\n#### 모범 사례 규칙 1 엄격한 오류 검사를 활성화하라\n\n- **범위** 모든 스크립트의 시작 부분.\n- **근거** 오류 발생 시 종료(`-e`), 설정되지 않은 변수를 오류로 처리(`-u`), 파이프라인의 어떤 명령이라도 실패하면 실패 처리(`-o pipefail`)하여 스크립트를 더 견고하게 만듭니다.\n\n```bash\n# GOOD\nset -euo pipefail\n# 또는\nset -o errexit -o nounset -o pipefail\n\n# BAD\n# (안전 옵션 없음)\n```\n\n...\n\n```\n\n---\n\n### 단계 4: 좋은 사례와 나쁜 사례에 대한 예시.\n\n#### 1. 모든 규칙에 좋은/나쁜 예시가 있는지 확인\n\n이 조치는 전체 문서에 대한 품질 검사입니다. \"서식\" 및 \"스타일 규칙\" 섹션에 정의된 모든 단일 규칙에는 규칙의 올바른(`GOOD`) 적용과 잘못된(`BAD`) 적용을 모두 보여주는 명확하고 간결한 코드 블록이 동반되어야 합니다. 이는 개발자에게 즉각적이고 실용적인 명확성을 제공합니다.\n\n**파일**: `documents/guidelines/shell_script/coding_styles.md`\n\n```markdown\n...\n#### 모범 사례 규칙 2 항상 변수를 인용하라\n\n- **범위** 모든 변수 확장.\n- **근거** 변수에 공백이나 특수 문자가 포함될 때 단어 분리 및 글로빙(globbing)으로 인한 예기치 않은 동작을 방지합니다.\n\n```bash\n# GOOD\nrm \"$filename\"\n\n# BAD\nrm $filename\n```\n\n...\n\n#### 명확성을 위한 이름 규칙 2 함수 이름에 동사_명사 형식을 따르라\n\n- **범위** 모든 함수.\n- **근거** 일관된 `verb_noun` 구조는 함수가 어떤 객체에 대해 어떤 동작을 수행하는지 명확하게 전달합니다.\n\n```bash\n# GOOD\nfunction validate_input() { ... }\nfunction create_temporary_file() { ... }\n\n# BAD\nfunction input_validation() { ... } # 명사 기반 이름은 불명확함\nfunction temp_file() { ... } # 동작을 설명하는 동사가 없음\n```\n\n...\n\n```\n\n---\n\n### 단계 5: 명확한 버전 및 소유권 헤더.\n\n#### 1. 문서 헤더 추가/확인\n\n이 조치는 문서가 버전 관리 및 소유권에 대한 적절한 메타데이터를 갖도록 보장합니다. 헤더는 파일의 첫 번째 요소여야 하며, 문서 버전, 생성/마지막 업데이트 날짜, 그리고 유지보수를 책임지는 소유자 또는 팀을 명확히 명시해야 합니다.\n\n**파일**: `documents/guidelines/shell_script/coding_styles.md`\n\n```markdown\n\n# 셸 스크립트 코딩 스타일 규칙\n\n버전 v1.0\n생성일 2025-06-26\n소유자 @movingChurch\n\n---\n...\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n1. 텍스트 편집기나 마크다운 뷰어에서 `documents/guidelines/shell_script/coding_styles.md` 파일을 엽니다.\n2. 1.3절의 완료 조건 체크리스트와 문서를 비교 검토합니다.\n3. 버전, 날짜, 소유자 정보가 포함된 문서 헤더가 있는지 확인합니다.\n4. \"핵심 원칙\" 섹션이 있는지 확인합니다.\n5. 이름 규칙 표를 포함한 \"서식\" 섹션이 있는지 확인합니다.\n6. \"스타일 규칙\" 섹션이 있는지 확인합니다.\n7. \"서식\" 및 \"스타일 규칙\" 섹션의 모든 규칙을 훑어보고, 각 규칙 바로 뒤에 `GOOD` 및 `BAD` 예시를 모두 포함하는 코드 블록이 있는지 확인합니다.\n\n### 4.2. 예상 결과\n\n- `documents/guidelines/shell_script/coding_styles.md` 파일이 완전히 채워지고 올바르게 서식화됩니다.\n- 문서 내용이 3절에 명시된 섹션 및 규칙과 정확히 일치합니다.\n- 렌더링 시, 이 문서는 프로젝트 내 모든 셸 스크립팅을 위한 완전하고 모호하지 않은 스타일 가이드 역할을 합니다.\n","핵심 원칙, 서식 규칙 및 스타일 모범 사례를 요약한 마크다운 문서입니다.",[523,525,527,529,531],{"_24":524,"_83":39,"_84":61,"_85":61},"견고성 및 명확성과 같은 핵심 원칙 정의.",{"_24":526,"_83":39,"_84":61,"_85":88},"이름 지정 규칙을 포함한 서식에 대한 섹션.",{"_24":528,"_83":39,"_84":61,"_85":91},"모범 사례를 포함한 스타일 규칙에 대한 섹션.",{"_24":530,"_83":39,"_84":61,"_85":94},"좋은 사례와 나쁜 사례에 대한 예시.",{"_24":532,"_83":39,"_84":61,"_85":97},"명확한 버전 및 소유권 헤더.","셸 스크립트의 일관성과 가독성을 위한 공식적인 규칙 집합입니다.",{"_22":535,"_24":536,"_75":537,"_77":538,"_79":539,"_51":550,"_42":99},"task-1751000589523","OS에 구애받지 않는 유틸리티 스크립트","# 작업: OS에 구애받지 않는 유틸리티 스크립트\n\n> **에픽**: 셸 스크립팅 기반\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 다른 모든 스크립트를 위한 공통적이고 재사용 가능한 셸 함수들의 중앙화된 스크립트.\n- **근거**: 로깅, OS 감지, 명령어 검증과 같은 핵심 작업을 표준화하는 공유 유틸리티의 기초 계층을 구축하기 위함입니다. 이러한 함수를 중앙화하면 코드 중복을 줄이고, 유지보수성을 향상시키며, 모든 플랫폼별 및 공통 설치 스크립트에서 일관된 동작을 보장하여 프로젝트의 \"모듈식 스크립트 기반 오케스트레이션\" 아키텍처를 직접적으로 지원합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 로깅, OS 감지, 프로그램 검증을 위한 함수를 포함한 스크립트.\n- **사양**:\n - 스크립트는 strict 모드로 시작해야 합니다: `set -euo pipefail`.\n - 로깅 함수 구현: `log_info()`, `log_error()`, `log_warning()`.\n - OS 감지 함수 구현: `detect_os()`, 이 함수는 `DETECTED_OPERATING_SYSTEM` 변수를 export합니다.\n - 프로그램 확인 함수 구현: `is_program_installed()`.\n - 명령어 검증 함수 구현: `verify_command()`.\n- **결과 파일 구조**\n\n```bash\n# ./scripts/cpp_development_environment/\n# └── common/\n# └── os_agnostic_utils.sh <-- 신규\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"오케스트레이션 스크립트 (예: setup.sh)\"\n A[실행 시작]\n B[\"source common/os_agnostic_utils.sh\"]\n C{로깅 필요?}\n D{OS 감지 필요?}\n E{프로그램 확인 필요?}\n end\n\n subgraph \"os_agnostic_utils.sh\"\n F[log_info, log_error, ...]\n G[detect_os]\n H[is_program_installed, ...]\n end\n\n A --> B\n B --> C\n B --> D\n B --> E\n\n C -- 예 --> F\n D -- 예 --> G\n E -- 예 --> H\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] 표준화된 로깅 함수 (`log_info`, `log_error`, `log_warning`).\n- [ ] 신뢰할 수 있는 OS 감지 함수 (`detect_os`).\n- [ ] 범용 프로그램 설치 확인 함수 (`is_program_installed`).\n- [ ] 유연한 명령어 검증 함수 (`verify_command`).\n- [ ] 최상단에 strict 모드 설정 (`set -euo pipefail`).\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 스크립트 기반 오케스트레이션\n- **관련 주요 구성 요소**:\n - `common/os_agnostic_utils.sh`: 이 작업의 대상 파일입니다. 공유 라이브러리 역할을 합니다.\n - `setup.sh`: 메인 오케스트레이터는 이 유틸리티 스크립트를 `source`하여 전체 설치 과정에서 OS 감지 및 로깅에 해당 함수들을 사용합니다.\n - `macos/scripts` & `linux/scripts`: 플랫폼별 설치 스크립트는 이 유틸리티 스크립트를 `source`하여 멱등성 검사를 위해 `is_program_installed`를 사용하고, 일관된 출력을 위해 로깅 함수를 사용합니다.\n - `verify.sh`: 검증 스크립트는 `is_program_installed`와 `verify_command`를 사용하여 모든 도구가 올바르게 설치되고 실행 가능한지 확인합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `scripts/cpp_development_environment/common/os_agnostic_utils.sh`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부적인 `조치`로 나뉩니다. 각 `조치`에 대해 제목, 명확한 서술적 설명('무엇'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 표준화된 로깅 함수 (`log_info`, `log_error`, `log_warning`)\n\n#### 1. 타임스탬프가 포함된 로깅 함수 구현\n\n이 조치는 모든 스크립트에서 로그 출력을 표준화하기 위해 세 개의 함수를 생성합니다. `log_info`는 일반적인 상태 업데이트를 제공하고, `log_warning`은 중요하지 않은 문제를 강조하며, `log_error`는 실패를 보고합니다. `log_error`에 `>&2`를 사용하면 오류 메시지를 표준 오류(standard error)로 리디렉션하는데, 이는 진단 출력을 프로그램 데이터와 분리하는 표준적인 관행입니다. 각 로그 항목에는 더 나은 추적성을 위해 타임스탬프가 포함됩니다.\n\n**파일**: `scripts/cpp_development_environment/common/os_agnostic_utils.sh`\n\n```shell\n# --- Logging functions ---\n# Usage: log_info \"This is an info message\"\nlog_info() {\n echo \"[INFO] $(date +'%Y-%m-%d %H:%M:%S') - $1\"\n}\n\n# Usage: log_error \"This is an error message\"\nlog_error() {\n echo \"[ERROR] $(date +'%Y-%m-%d %H:%M:%S') - $1\" >&2\n}\n\n# Usage: log_warning \"This is a warning message\"\nlog_warning() {\n echo \"[WARN] $(date +'%Y-%m-%d %H:%M:%S') - $1\"\n}\n```\n\n---\n\n### 단계 2: 신뢰할 수 있는 OS 감지 함수 (`detect_os`)\n\n#### 1. `detect_os` 함수 생성\n\n이 조치는 호스트 운영 체제를 판별하는 함수를 구현합니다. `$OSTYPE` 환경 변수를 검사하고 더 넓은 호환성을 위해 `uname -s`로 대체합니다. 출력을 \"macos\" 또는 \"linux\"로 정규화하고 `DETECTED_OPERATING_SYSTEM`으로 export합니다. 이 export된 변수는 메인 `setup.sh` 오케스트레이터가 어떤 플랫폼별 스크립트 디렉터리(`macos/` 또는 `linux/`)를 사용할지 결정하는 데 중요합니다. 지원되지 않는 OS가 감지되면 스크립트는 오류와 함께 종료됩니다.\n\n**파일**: `scripts/cpp_development_environment/common/os_agnostic_utils.sh`\n\n```shell\n# Detects the current operating system and exports it as DETECTED_OPERATING_SYSTEM\n# Usage: detect_os\n# echo \"Running on: $DETECTED_OPERATING_SYSTEM\"\ndetect_os() {\n local detected_os_type\n if [[ -z \"${OSTYPE-''}\" ]]; then\n case \"$(uname -s)\" in\n Darwin*) detected_os_type=\"darwin\" ;;\n Linux*) detected_os_type=\"linux-gnu\" ;;\n *) detected_os_type=\"unknown\" ;;\n esac\n else\n detected_os_type=\"$OSTYPE\"\n fi\n\n if [[ \"$detected_os_type\" == \"darwin\"* ]]; then\n export DETECTED_OPERATING_SYSTEM=\"macos\"\n elif [[ \"$detected_os_type\" == \"linux-gnu\"* ]]; then\n export DETECTED_OPERATING_SYSTEM=\"linux\"\n else\n log_error \"❌ Unsupported operating system: '$detected_os_type'\"\n exit 1\n fi\n log_info \"Operating System detected: $DETECTED_OPERATING_SYSTEM\"\n}\n```\n\n---\n\n### 단계 3: 범용 프로그램 설치 확인 함수 (`is_program_installed`)\n\n#### 1. `is_program_installed` 함수 구현\n\n이 조치는 프로그램이 시스템의 `PATH`에 있는지 확인하는 간단하고 POSIX 호환 함수를 생성합니다. 실행 파일의 존재를 테스트하는 권장 방법인 `command -v`를 사용합니다. 출력은 의도적으로 억제되어(`&>/dev/null`) 함수가 조건문(예: `if is_program_installed \"git\"; then ...`)에서 깔끔하게 사용될 수 있습니다. 이것은 멱등성 있는 스크립트 설계의 초석으로, 스크립트가 이미 존재하는 도구의 설치를 건너뛸 수 있게 합니다.\n\n**파일**: `scripts/cpp_development_environment/common/os_agnostic_utils.sh`\n\n```shell\n# --- OS-Agnostic Program and Command Utilities ---\n\n# Checks if a program (command) is installed and in PATH.\n# This function is universal for any POSIX-compliant shell.\n# Usage: if is_program_installed \"git\"; then ...\nis_program_installed() {\n local program_name=\"$1\"\n command -v \"$program_name\" &>/dev/null\n}\n```\n\n---\n\n### 단계 4: 유연한 명령어 검증 함수 (`verify_command`)\n\n#### 1. `verify_command` 함수 구현\n\n이 조치는 단순히 프로그램의 존재를 확인하는 것보다 더 강력한 검사를 제공하는 함수를 생성합니다. `is_program_installed`를 사용한 후, 버전 플래그(기본값 `--version`)로 프로그램을 실행하려고 시도합니다. 이는 프로그램이 `PATH`에 있을 뿐만 아니라 실행 가능하고 손상되지 않았는지 확인하는 데 도움이 됩니다. 함수는 출력과 종료 상태를 기록하며, 일부 도구는 버전 확인 시 0으로 종료하지 않을 수 있으므로 0이 아닌 종료 코드를 경고로 처리합니다.\n\n**파일**: `scripts/cpp_development_environment/common/os_agnostic_utils.sh`\n\n```shell\n# Verifies if a command is available and executable by running it with a version flag.\n# This is generally OS-agnostic, as most command-line tools support a --version or similar flag.\n# Usage: verify_command \"git\" \"[--version]\"\nverify_command() {\n local program_to_verify=\"$1\"\n local verification_arguments=\"${2:---version}\" # Default to --version if no second arg\n\n log_info \"Verifying '$program_to_verify' command...\"\n if is_program_installed \"$program_to_verify\"; then\n log_info \"Attempting to get version or status: $program_to_verify $verification_arguments\"\n local verification_output\n local verification_exit_status\n # Using eval to correctly interpret verification_arguments if it contains spaces or multiple options\n # Capture both stdout and stderr\n verification_output=$(eval \"$program_to_verify $verification_arguments\" 2>&1)\n verification_exit_status=$?\n log_info \"Output of '$program_to_verify $verification_arguments':\"\n # Log multiline output correctly\n while IFS= read -r line; do log_info \" $line\"; done <<<\"$verification_output\"\n\n if [ $verification_exit_status -eq 0 ]; then\n log_info \"✅ '$program_to_verify' verification successful (command exited with 0).\"\n else\n # For many tools, a non-zero exit for a version check is not a critical failure.\n log_warning \"⚠️ '$program_to_verify $verification_arguments' exited with status $verification_exit_status. This might be normal for some tools.\"\n fi\n else\n log_error \"❌ '$program_to_verify' not found in PATH. Verification failed.\"\n return 1\n fi\n return 0\n}\n```\n\n---\n\n### 단계 5: 최상단에 strict 모드 설정 (`set -euo pipefail`)\n\n#### 1. 스크립트 앞에 Strict 모드 설정 추가\n\n이 조치는 스크립트 상단에 Bash \"strict 모드\" 설정을 추가합니다. `set -e`는 명령어가 실패하면 스크립트가 즉시 종료되도록 합니다. `set -u`는 설정되지 않은 변수를 오류로 처리합니다. `set -o pipefail`은 파이프라인이 0이 아닌 상태로 종료된 마지막 명령어의 종료 상태를 반환하게 합니다. 이러한 설정은 빠르고 예측 가능하게 실패하며 조용한 오류를 방지하는 강력한 스크립트를 만드는 데 중요합니다.\n\n**파일**: `scripts/cpp_development_environment/common/os_agnostic_utils.sh`\n\n```shell\n#!/bin/bash\n\nset -euo pipefail\n\n# ... (rest of the script)\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 개발자는 터미널에서 스크립트를 소싱하고 그 함수들을 실행하여 출력과 동작을 관찰함으로써 구현을 검증할 수 있습니다.\n\n```bash\n# 1. 스크립트 디렉터리로 이동\ncd scripts/cpp_development_environment/common\n\n# 2. 스크립트를 실행 가능하게 만듦 (필요 시)\nchmod +x os_agnostic_utils.sh\n\n# 3. 현재 셸 세션에 함수를 로드하기 위해 스크립트를 소싱\nsource ./os_agnostic_utils.sh\n\n# 4. 로깅 함수 검증\nlog_info \"정보 로그 테스트\"\nlog_warning \"경고 로그 테스트\"\nlog_error \"오류 로그 테스트\"\n\n# 5. OS 감지 검증\ndetect_os\necho \"감지된 OS: $DETECTED_OPERATING_SYSTEM\"\n\n# 6. 프로그램 확인 함수 검증 (성공 및 실패 사례)\nif is_program_installed \"ls\"; then echo \"✅ 'ls'가 설치되었습니다.\"; else echo \"❌ 'ls'를 찾을 수 없습니다.\"; fi\nif is_program_installed \"non_existent_program_xyz\"; then echo \"❌ 존재하지 않는 프로그램을 찾았습니다!\"; else echo \"✅ 존재하지 않는 프로그램을 올바르게 찾지 못했습니다.\"; fi\n\n# 7. 명령어 검증 함수 검증\nverify_command \"bash\" \"--version\"\n```\n\n### 4.2. 예상 결과\n\n- 터미널 출력은 다음과 유사해야 합니다 (타임스탬프는 다를 수 있음). `log_error`의 오류가 보여야 합니다. OS 감지는 시스템을 올바르게 식별해야 합니다. 프로그램 확인은 올바른 상태를 보고해야 합니다.\n\n```\n[INFO] <타임스탬프> - 정보 로그 테스트\n[WARN] <타임스탬프> - 경고 로그 테스트\n[ERROR] <타임스탬프> - 오류 로그 테스트\n[INFO] <타임스탬프> - 운영 체제 감지됨: macos (또는 linux)\n감지된 OS: macos (또는 linux)\n✅ 'ls'가 설치되었습니다.\n✅ 존재하지 않는 프로그램을 올바르게 찾지 못했습니다.\n[INFO] <타임스탬프> - 'bash' 명령어 검증 중...\n[INFO] <타임스탬프> - 버전 또는 상태 확인 시도: bash --version\n[INFO] <타임스탬프> - 'bash --version'의 출력:\n[INFO] <타임스탬프> - GNU bash, version 3.2.57(1)-release (x86_64-apple-darwin21)\n[INFO] <타임스탬프> - Copyright (C) 2007 Free Software Foundation, Inc.\n[INFO] <타임스탬프> - ✅ 'bash' 검증 성공 (명령어 종료 코드 0).\n```","로깅, OS 감지 및 프로그램 검증을 위한 함수가 포함된 스크립트입니다.",[540,542,544,546,548],{"_24":541,"_83":39,"_84":88,"_85":61},"표준화된 로깅 함수 (`log_info`, `log_error`, `log_warning`).",{"_24":543,"_83":39,"_84":88,"_85":88},"신뢰할 수 있는 OS 감지 함수 (`detect_os`).",{"_24":545,"_83":39,"_84":88,"_85":91},"범용 프로그램 설치 확인 함수 (`is_program_installed`).",{"_24":547,"_83":39,"_84":88,"_85":94},"유연한 명령어 검증 함수 (`verify_command`).",{"_24":549,"_83":39,"_84":88,"_85":97},"상단에 엄격 모드 설정 (`set -euo pipefail`).","다른 모든 스크립트를 위한 공통적이고 재사용 가능한 셸 함수들의 중앙 집중식 스크립트입니다.",{"_22":552,"_24":553,"_75":554,"_77":555,"_79":556,"_51":567,"_42":99},"task-1751000644138","macOS 설치 유틸리티 스크립트 (Homebrew)","# 작업: macOS 설치 유틸리티 스크립트 (Homebrew)\n\n> **에픽**: 플랫폼별 설치 추상화\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 멱등성 있는 패키지 설치를 보장하기 위한 Homebrew 작업 추상화 계층.\n- **근거**: 모든 macOS 설치 스크립트에서 Homebrew 패키지 관리를 중앙화하고 표준화합니다. 이 추상화는 멱등성을 제공하여 스크립트를 여러 번 실행해도 오류가 발생하거나 기존 소프트웨어를 다시 설치하지 않도록 보장합니다. 또한 확인, 설치, 검증의 상용구 로직을 재사용 가능한 단일 함수에서 처리하여 개별 설치 스크립트를 단순화합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: Homebrew formula와 cask를 모두 설치하고 검증하는 함수를 포함한 유틸리티 스크립트.\n- **사양**:\n - `install_with_brew()`: Homebrew formula 또는 cask를 멱등성 있게 설치하는 공개 함수.\n - `_install_with_brew()`: 핵심 `brew install` 명령을 실행하는 내부 헬퍼 함수.\n - `install_and_verify_tool()`: 도구의 설치와 후속 검증을 조율하고, 치명적 오류와 비치명적 오류를 처리하는 로직을 포함하는 포괄적인 래퍼 함수.\n- **결과 파일 구조**\n\n```bash\n# ./scripts/cpp_development_environment/\n# └── macos/\n# └── common_utils.sh <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 상위 수준의 설치 스크립트(예: `install_git.sh`)가 이 작업에서 생성된 함수를 어떻게 사용하는지 보여줍니다. 로직은 선언적이고 견고하게 설계되었습니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph install_git.sh\n A[\"install_and_verify_tool 'git' 'git' 'formula' 'true' 호출\"]\n end\n \n subgraph common_utils.sh\n B[\"install_and_verify_tool()\"]\n C{\"'git' 설치 및 검증 완료?\"}\n D[\"install_with_brew()\"]\n E{\"'git' formula 설치 완료?\"}\n F[\"_install_with_brew()\"]\n G[\"'brew install git' 실행\"]\n H[\"verify_command 'git'\"]\n I{\"검증 완료?\"}\n end\n\n subgraph os_agnostic_utils.sh\n J[\"is_program_installed()\"]\n K[\"verify_command()\"]\n end\n \n A --> B\n B --> C\n C -- 사용 --> J\n C -- 아니요 --> D\n C -- 예 --> L[성공 로그 기록 및 종료]\n D --> E\n E -- 아니요 --> F\n E -- 예 --> M['이미 설치됨' 로그 기록]\n F --> G\n G --> H\n H -- 사용 --> K\n H --> I\n I -- 예 --> L\n I -- 아니요 --> N[치명적 오류 로그 기록 및 중단]\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3장에 있습니다.\n\n- [ ] 멱등성 있는 `install_with_brew` 함수.\n- [ ] 핵심 설치 로직을 위한 내부 `_install_with_brew` 헬퍼.\n- [ ] 치명적 및 비치명적 도구를 관리하기 위한 포괄적인 `install_and_verify_tool` 함수.\n- [ ] OS에 독립적인 유틸리티 소싱.\n- [ ] 신뢰할 수 있는 스크립트 디렉터리 확인.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 스크립트 기반 오케스트레이션\n- **관련 주요 구성 요소**:\n - **`macos/scripts`**: 이 작업은 이 구성 요소 내에 새로운 핵심 유틸리티 파일인 `common_utils.sh`를 생성하는 것을 포함합니다. 이 파일은 다른 모든 macOS 전용 설치 스크립트를 위한 기반이 되는 공유 라이브러리 역할을 하여 Homebrew 로직을 중앙 집중화합니다.\n - **`common/scripts`**: 새로운 macOS 유틸리티 스크립트는 이 구성 요소의 `os_agnostic_utils.sh`를 `source`하고 의존하게 됩니다. 이를 통해 로깅(`log_info`, `log_error`) 및 검증(`is_program_installed`, `verify_command`)을 위한 공유 함수를 활용하여 코드 재사용성과 일관성을 높일 수 있습니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `scripts/cpp_development_environment/macos/common_utils.sh`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 멱등성 있는 `install_with_brew` 함수\n\n#### 1. 멱등성 검사 구현\n\n이 함수는 패키지 설치를 위한 기본 공개 인터페이스 역할을 합니다. 주요 책임은 재설치를 방지하는 것입니다. `brew list --formula` 또는 `brew list --cask`를 사용하여 Homebrew에 설치된 패키지를 먼저 조회함으로써 멱등성을 달성합니다. 패키지가 발견되면 함수는 성공 메시지를 기록하고 종료하여 불필요한 `brew install` 명령을 피합니다. 발견되지 않으면 실제 설치를 `_install_with_brew` 헬퍼 함수에 위임합니다.\n\n**파일**: `scripts/cpp_development_environment/macos/common_utils.sh`\n\n```shell\n# Homebrew를 사용하여 패키지를 설치하며, 이미 설치되었는지 확인합니다.\n# 사용법: install_with_brew <패키지_이름> [brew_list용_패키지_이름] <설치_유형>\n# <설치_유형>은 \"formula\" 또는 \"cask\"가 될 수 있습니다.\n# brew_list용_패키지_이름이 비어 있거나 제공되지 않으면 패키지_이름이 사용됩니다.\ninstall_with_brew() {\n local package_name=\"$1\"\n local list_name=\"$2\"\n local install_type=\"$3\" # \"formula\" 또는 \"cask\"\n\n if [[ -z \"$list_name\" ]]; then\n list_name=\"$package_name\"\n fi\n\n local list_command=\"brew list --formula\"\n if [[ \"$install_type\" == \"cask\" ]]; then\n list_command=\"brew list --cask\"\n fi\n\n log_info \"$package_name($install_type)이(가) 설치되었는지 확인 중...\"\n if $list_command | grep -q \"^${list_name}$\"; then\n log_info \"✅ $package_name이(가) 이미 설치되었습니다.\"\n return 0\n fi\n\n # 설치되지 않은 경우, 내부 설치 프로그램을 호출합니다.\n _install_with_brew \"$package_name\" \"$install_type\"\n}\n```\n\n---\n\n### 단계 2: 핵심 설치 로직을 위한 내부 `_install_with_brew` 헬퍼\n\n#### 1. 핵심 Homebrew 설치 명령어 구현\n\n이 내부 헬퍼 함수는 실제 `brew install` 명령을 캡슐화합니다. 다른 설치 스크립트에서 직접 호출하도록 의도되지 않았습니다. 그 목적은 설치 작업과 멱등성 검사를 분리하는 것입니다. 셸 배열(`brew_args`)을 사용하여 `brew` 명령을 구성하는데, 이는 특수 문자를 포함할 수 있는 패키지 이름을 견고하게 처리하는 방법입니다. 그런 다음 명령을 실행하고 성공 또는 실패에 대한 명확한 로깅을 제공합니다.\n\n**파일**: `scripts/cpp_development_environment/macos/common_utils.sh`\n\n```shell\n# Homebrew를 사용하여 패키지를 설치하는 내부 헬퍼입니다.\n# 이 함수는 설치 스크립트에서 직접 호출하도록 의도되지 않았습니다.\n# 사용법: _install_with_brew <패키지_이름> <설치_유형>\n_install_with_brew() {\n local package_name=\"$1\"\n local install_type=\"$2\" # \"formula\" 또는 \"cask\"\n\n log_info \"Homebrew로 $package_name($install_type)을(를) 설치 중...\"\n\n # 패키지 이름을 더 안전하게 처리하기 위해 brew 인수에 배열을 사용합니다.\n local brew_args=(\"install\" \"$package_name\")\n if [[ \"$install_type\" == \"cask\" ]]; then\n brew_args=(\"install\" \"--cask\" \"$package_name\")\n fi\n\n if brew \"${brew_args[@]}\"; then\n log_info \"✅ $package_name 설치를 성공적으로 시작했습니다.\"\n return 0\n else\n log_error \"❌ '$package_name' 설치에 실패했습니다. Homebrew 로그를 확인해주세요.\"\n return 1\n fi\n}\n```\n\n---\n\n### 단계 3: 치명적 및 비치명적 도구를 관리하기 위한 포괄적인 `install_and_verify_tool` 함수\n\n#### 1. 상위 수준 오케스트레이션 함수 구현\n\n이것은 다른 설치 스크립트가 호출해야 하는 주 함수입니다. 확인, 설치, 검증의 전체 과정을 조율합니다. 먼저 `os_agnostic_utils.sh`의 헬퍼를 사용하여 프로그램이 이미 설치되어 `PATH`에서 사용 가능한지 확인합니다. 그렇다면 조기에 종료합니다. 그렇지 않다면 `_install_with_brew` 함수를 호출하여 진행합니다. 핵심 기능은 `is_critical` 매개변수로, 실패 시 스크립트의 동작을 결정합니다.\n\n**파일**: `scripts/cpp_development_environment/macos/common_utils.sh`\n\n```shell\n# Homebrew를 사용하여 도구를 설치하고 검증하는 헬퍼 함수입니다.\n# 치명적 및 비치명적 도구를 모두 처리합니다.\n# 로직은 먼저 완료 여부를 확인한 다음, 설치 및 검증을 시도하고 치명적인 실패는 종료하여 처리하도록 구성됩니다.\n# 사용법: install_and_verify_tool <프로그램_이름> <패키지_이름> <설치_유형> <치명적_여부>\ninstall_and_verify_tool() {\n local program_name=\"$1\"\n local package_name=\"$2\"\n local install_type=\"$3\" # \"formula\" 또는 \"cask\"\n local is_critical=\"$4\" # \"true\" 또는 \"false\"\n\n log_info \"--- $program_name 처리 중 ---\"\n\n if is_program_installed \"$program_name\" && verify_command \"$program_name\"; then\n log_info \"✅ $program_name이(가) 이미 설치되고 검증되었습니다.\"\n return 0\n fi\n...\n```\n\n#### 2. 중요도 처리를 포함한 설치 및 검증 로직 추가\n\n초기 확인 후, 함수는 설치를 시도합니다. 설치가 실패하면 `is_critical` 플래그를 확인합니다. `true`인 경우 치명적인 오류를 기록하고 전체 설정 프로세스를 중단합니다(`exit 1`). `false`인 경우 경고를 기록하고 설정이 계속되도록 허용합니다. 동일한 로직이 최종 검증 단계에도 적용되며, 이는 설치 후 도구가 실행 가능한지 확인하기 위해 실행됩니다. 이를 통해 환경이 견고하고 필수 종속성에 대해 신속하게 실패하도록 보장합니다.\n\n**파일**: `scripts/cpp_development_environment/macos/common_utils.sh`\n\n```shell\n...\n # --- 설치 ---\n if ! _install_with_brew \"$package_name\" \"$install_type\"; then\n if [[ \"$is_critical\" == \"true\" ]]; then\n log_error \"치명적인 도구 '$package_name' 설치에 실패했습니다. 중단합니다.\"\n exit 1\n else\n log_warning \"비치명적인 도구 '$package_name' 설치에 실패했습니다.\"\n return 1\n fi\n fi\n\n # --- 최종 검증 ---\n if ! verify_command \"$program_name\"; then\n if [[ \"$is_critical\" == \"true\" ]]; then\n log_error \"설치 후 치명적인 도구 '$program_name' 검증에 실패했습니다. 중단합니다.\"\n exit 1\n else\n log_warning \"설치 후 비치명적인 도구 '$program_name' 검증에 실패했습니다.\"\n return 1\n fi\n fi\n\n log_info \"✅ $program_name을(를) 성공적으로 설치하고 검증했습니다.\"\n return 0\n}\n```\n\n---\n\n### 단계 4: OS에 독립적인 유틸리티 소싱\n\n#### 1. `os_agnostic_utils.sh`를 위한 source 명령어 추가\n\n`log_info` 및 `verify_command`와 같은 공통 함수를 사용하려면 이 스크립트는 `os_agnostic_utils.sh` 파일을 명시적으로 소싱해야 합니다. 이는 상대 경로와 함께 `source` 명령어를 사용하여 수행됩니다. `shellcheck` 지시문은 정적 분석 도구가 이 종속성을 이해하고 스크립트를 올바르게 검증하는 데 도움이 되는 모범 사례로 포함됩니다.\n\n**파일**: `scripts/cpp_development_environment/macos/common_utils.sh`\n\n```shell\n...\n# OS에 독립적인 유틸리티(로깅, 안전 옵션) 소싱\n# shellcheck source=../common/os_agnostic_utils.sh\nsource \"$MACOS_COMMON_UTILITIES_DIRECTORY/../common/os_agnostic_utils.sh\"\n...\n```\n\n---\n\n### 단계 5: 신뢰할 수 있는 스크립트 디렉터리 확인\n\n#### 1. 견고한 디렉터리 경로 확인 구현\n\n`source` 명령어가 안정적으로 작동하려면 스크립트는 자신의 절대 경로를 먼저 결정해야 합니다. 이는 스크립트가 어떤 작업 디렉터리에서든 실행될 수 있기 때문에 매우 중요합니다. `MACOS_COMMON_UTILITIES_DIRECTORY` 변수는 스크립트의 실제 위치를 확인하기 위해 표준적이고 견고한 셸 패턴(`cd \"$(dirname ...)\" && pwd`)을 사용하여 정의되며, 이를 통해 `os_agnostic_utils.sh`에 대한 상대 경로가 항상 정확하도록 보장합니다. 이 코드는 `source` 명령어 앞에 와야 합니다.\n\n**파일**: `scripts/cpp_development_environment/macos/common_utils.sh`\n\n```shell\n#!/bin/bash\n\nset -euo pipefail\n\n# macOS 설치 스크립트를 위한 공통 유틸리티 함수\n\n# 현재 실행 중인 스크립트의 디렉터리를 가져옵니다\n# os_agnostic_utils.sh를 안정적으로 소싱하기 위해 필요합니다\nMACOS_COMMON_UTILITIES_DIRECTORY=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\n\n# OS에 독립적인 유틸리티(로깅, 안전 옵션) 소싱\n...\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n구현을 검증하기 위해 임시 테스트 스크립트를 생성하고 실행합니다. 이 테스트는 간단하고 비치명적인 Homebrew formula를 설치하려고 시도합니다.\n\n1. `scripts/cpp_development_environment/macos` 디렉터리에 `test_utils.sh`라는 임시 테스트 파일을 생성합니다.\n2. `test_utils.sh`에 다음 내용을 추가합니다. 이 스크립트는 새로운 유틸리티 파일을 소싱하고 가벼운 명령줄 JSON 프로세서인 `jq`를 설치하려고 시도합니다.\n\n```bash\n#!/bin/bash\n\nset -euo pipefail\n\n# 테스트할 유틸리티 소싱\nsource \"$(dirname \"$0\")/common_utils.sh\"\n\n# 비치명적인 formula로 주 설치 함수 테스트\n# 첫 실행은 설치, 두 번째 실행은 \"이미 설치됨\" 보고\ninstall_and_verify_tool \"jq\" \"jq\" \"formula\" \"false\"\n\n# 실패 사례 테스트 (존재하지 않는 패키지 사용)\necho -e \"\\n--- 예상된 실패 테스트 ---\"\nif install_and_verify_tool \"nonexistent\" \"nonexistent\" \"formula\" \"false\"; then\n log_error \"테스트 실패: 존재하지 않는 패키지는 성공적으로 설치되어서는 안 됩니다.\"\n exit 1\nelse\n log_info \"테스트 통과: 존재하지 않는 패키지에 대한 비치명적 실패를 올바르게 처리했습니다.\"\nfi\n```\n\n3. 테스트 스크립트를 실행 가능하게 만들고 프로젝트의 루트에서 실행합니다.\n\n```bash\nchmod +x scripts/cpp_development_environment/macos/test_utils.sh\n./scripts/cpp_development_environment/macos/test_utils.sh\n```\n\n4. 스크립트를 두 번째로 실행하여 멱등성을 확인합니다.\n\n```bash\n./scripts/cpp_development_environment/macos/test_utils.sh\n```\n\n### 4.2. 예상 결과\n\n- **첫 실행**: 출력은 `jq`를 확인, 설치 및 검증하는 로그를 보여줍니다. 스크립트는 `jq`를 성공적으로 설치할 것입니다. 그런 다음 \"nonexistent\" 패키지를 설치하려고 시도하고 실패에 대한 경고를 기록한 다음, 테스트가 통과했다고 보고합니다.\n- **두 번째 실행**: 출력은 즉시 `✅ jq가 이미 설치되고 검증되었습니다.`라는 로그를 보여주어 멱등성 검사가 올바르게 작동하고 있음을 증명합니다. 나머지 출력은 동일합니다.\n- 두 실행 모두 종료 코드 `0`으로 종료되어야 합니다.","Homebrew formula와 cask를 모두 설치하고 검증하는 함수를 포함한 유틸리티 스크립트",[557,559,561,563,565],{"_24":558,"_83":39,"_84":91,"_85":61},"멱등성을 가진 `install_with_brew` 함수.",{"_24":560,"_83":39,"_84":91,"_85":88},"핵심 설치 로직을 위한 내부 헬퍼 `_install_with_brew`.",{"_24":562,"_83":39,"_84":91,"_85":91},"중요 및 비중요 도구를 관리하기 위한 포괄적인 `install_and_verify_tool` 함수.",{"_24":564,"_83":39,"_84":91,"_85":94},"OS에 구애받지 않는 유틸리티 소싱.",{"_24":566,"_83":39,"_84":91,"_85":97},"신뢰할 수 있는 스크립트 디렉터리 확인.","멱등성 패키지 설치를 보장하기 위한 Homebrew 작업의 추상화 계층",{"_22":569,"_24":570,"_75":571,"_77":572,"_79":573,"_51":584,"_42":99},"task-1751000707304","Linux 설치 유틸리티 스크립트 (APT)","# 작업: Linux 설치 유틸리티 스크립트 (APT)\n\n> **에픽**: 플랫폼별 설치 추상화\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 일관된 패키지 설치를 보장하기 위한 APT 작업 추상화 계층.\n- **근거**: `apt` 패키지 관리자와의 모든 상호작용을 단일 재사용 가능 스크립트로 중앙 집중화합니다. 이 접근 방식은 (핵심 프로젝트 목표인) 멱등성을 강제하고, 모든 Linux 패키지 설치에 대한 로깅 및 오류 처리를 표준화하며, 고수준 유틸리티 함수를 제공하여 개별 도구 설치 스크립트를 단순화합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: APT 캐시 업데이트 및 패키지 설치/검증 기능을 갖춘 유틸리티 스크립트.\n- **사양**: 최종 스크립트는 다음 Bash 함수를 제공합니다.\n - `update_apt_cache()`: 로컬 `apt` 패키지 목록을 업데이트합니다.\n - `install_with_apt(package_name)`: 단일 데비안 패키지를 멱등성 있게 설치합니다.\n - `install_packages(package1, package2, ...)`: 단일 트랜잭션으로 여러 데비안 패키지를 설치합니다.\n - `install_and_verify_tool(program_name, package_name, is_critical)`: 패키지를 설치하고 해당 명령어의 사용 가능성을 검증하는 포괄적인 래퍼 함수입니다.\n- **결과 파일 구조**\n\n```bash\n# ./scripts/cpp_development_environment/\n# └── linux/\n# └── common_utils.sh <-- 수정됨\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 상위 수준 설치 스크립트(예: `install_cmake.sh`)가 `common_utils.sh` 내의 함수를 활용하여 작업을 수행하는 방법을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n A[\"개별 설치 스크립트
(예: install_cmake.sh)\"] -- 소싱 --> B[\"linux/common_utils.sh\"];\n A -- \"파라미터로 호출: 'cmake', 'cmake', 'true'\" --> C[\"install_and_verify_tool\"];\n subgraph \"common_utils.sh 로직\"\n C --> D{\"is_program_installed 'cmake' 실행?\"};\n D -- \"아니요\" --> E[\"install_with_apt 'cmake'\"];\n E -- \"dpkg -s로 확인\" --> F[\"패키지 설치됨?\"];\n F -- \"아니요\" --> G[\"sudo apt-get install -y cmake\"];\n G --> H[\"verify_command 'cmake'\"];\n D -- \"예\" --> H;\n H -- \"성공/실패\" --> I{중요?};\n I -- \"예 + 실패\" --> J[종료 1];\n I -- \"성공 또는 중요하지 않은 실패\" --> K[호출자로 복귀];\n end\n K --> A;\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료된 것으로 표시하기 위해 다음 항목을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] OS 독립적 유틸리티 소싱.\n- [ ] APT 캐시를 업데이트하는 함수 (`update_apt_cache`).\n- [ ] 멱등성 있는 패키지 설치를 위한 함수 (`install_with_apt`).\n- [ ] 다중 패키지 설치 함수 (`install_packages`).\n- [ ] Linux를 위한 포괄적인 `install_and_verify_tool` 함수.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 스크립트 기반 오케스트레이션\n- **관련 주요 구성 요소**:\n - `linux/scripts`: 이 작업은 `linux/scripts` 디렉토리 내의 다른 모든 설치 스크립트에서 소싱하여 사용할 핵심 유틸리티 스크립트인 `common_utils.sh`를 생성합니다. 이는 Linux별 설치 로직의 기반이 됩니다.\n - `common/scripts`: 이 유틸리티 스크립트는 OS 독립적 유틸리티(`os_agnostic_utils.sh`)에 직접적인 의존성을 가집니다. 이 파일을 소싱하여 `log_info`, `log_error`, `verify_command`와 같은 공통 함수에 접근함으로써 플랫폼 간 일관된 로깅과 동작을 보장합니다.\n - `setup.sh`: 메인 오케스트레이터는 이 스크립트를 직접 호출하지 않습니다. 대신, 특정 도구 설치 스크립트(예: `install_clang.sh`)를 호출하며, 이들은 이 작업의 결과물에 정의된 함수에 의존하고 사용합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `scripts/cpp_development_environment/linux/common_utils.sh`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공합니다.\n\n---\n\n### 단계 1: OS 독립적 유틸리티 소싱\n\n#### 1. OS 독립적 의존성 추가\n\n이 작업은 Linux 전용 유틸리티와 공통 OS 독립적 유틸리티 간의 연결을 설정합니다. `os_agnostic_utils.sh`를 소싱함으로써 로깅(`log_info`, `log_error`) 및 검증(`is_program_installed`, `verify_command`)을 위한 공유 함수를 가져옵니다. 이는 코드 중복을 피하고 전체 시스템에 걸쳐 일관된 출력 형식을 보장합니다. 이 코드는 모든 후속 함수에서 유틸리티를 사용할 수 있도록 스크립트의 첫 번째 실행 코드가 되어야 합니다.\n\n**파일**: `scripts/cpp_development_environment/linux/common_utils.sh`\n\n```shell\n#!/bin/bash\n\nset -euo pipefail\n\n# Linux 설치 스크립트를 위한 공통 유틸리티 함수\n\nLINUX_COMMON_UTILITIES_DIRECTORY=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\n# shellcheck source=../common/os_agnostic_utils.sh\nsource \"$LINUX_COMMON_UTILITIES_DIRECTORY/../common/os_agnostic_utils.sh\"\n\n# --- Linux 전용 프로그램 및 패키지 관리자 유틸리티 ---\n...\n```\n\n---\n\n### 단계 2: APT 캐시를 업데이트하는 함수 (`update_apt_cache`)\n\n#### 1. APT 캐시 업데이트 함수 구현\n\n이 작업은 `sudo apt-get update`를 실행하는 전용 함수를 생성합니다. 데비안 기반 시스템에서는 로컬 패키지 인덱스가 오래되어 새 패키지나 업데이트된 패키지의 설치 실패로 이어질 수 있습니다. 이 명령을 표준화된 로깅을 포함하는 함수로 캡슐화하면 사용자에게 현재 진행 상황에 대한 명확한 피드백을 제공하고, 이에 의존하는 모든 스크립트의 견고성을 향상시킵니다.\n\n**파일**: `scripts/cpp_development_environment/linux/common_utils.sh`\n\n```shell\n...\n# apt 패키지 캐시를 업데이트합니다.\n# 사용법: update_apt_cache\nupdate_apt_cache() {\n log_info \"apt 패키지 캐시를 업데이트하는 중입니다 (sudo apt-get update)...\"\n if sudo apt-get update -y; then\n log_info \"✅ apt 패키지 캐시가 성공적으로 업데이트되었습니다.\"\n return 0\n else\n log_error \"❌ apt 패키지 캐시 업데이트에 실패했습니다. 권한과 네트워크를 확인해주세요.\"\n return 1\n fi\n}\n...\n```\n\n---\n\n### 단계 3: 멱등성 있는 패키지 설치를 위한 함수 (`install_with_apt`)\n\n#### 1. 멱등성 있는 단일 패키지 설치기 구현\n\n이 작업은 멱등성 있는 패키지 설치를 보장하는 핵심 함수 `install_with_apt`를 생성합니다. `dpkg -s`를 사용하여 설치를 시도하기 전에 패키지가 이미 설치되었는지 안정적으로 확인합니다. 이 확인은 안전하게 재실행 가능한 스크립트를 갖추려는 프로젝트 목표에 매우 중요합니다. 패키지가 존재하면 함수는 성공 메시지를 기록하고 종료합니다. 그렇지 않으면 `sudo apt-get install`을 진행하며 성공 및 실패 사례 모두에 대해 명확한 로깅을 제공합니다.\n\n**파일**: `scripts/cpp_development_environment/linux/common_utils.sh`\n\n```shell\n...\n# apt-get을 사용하여 패키지를 설치합니다.\n# 사용법: install_with_apt \"package_name\"\ninstall_with_apt() {\n local package_to_install=\"$1\"\n local package_display_name=\"$package_to_install\"\n\n log_info \"$package_display_name 설치 여부를 확인 중...\"\n if dpkg -s \"$package_to_install\" &>/dev/null; then\n log_info \"✅ $package_display_name 은(는) 이미 설치되어 있습니다.\"\n return 0\n fi\n\n log_info \"apt-get으로 $package_display_name 을(를) 설치 중...\"\n if sudo apt-get install -y \"$package_to_install\"; then\n log_info \"✅ $package_display_name 이(가) 성공적으로 설치되었습니다.\"\n return 0\n else\n log_error \"❌ $package_display_name 설치에 실패했습니다. apt-get 로그를 확인해주세요.\"\n return 1\n fi\n}\n...\n```\n\n---\n\n### 단계 4: 다중 패키지 설치 함수 (`install_packages`)\n\n#### 1. 대량 패키지 설치기 구현\n\n이 작업은 여러 패키지를 한 번에 효율적으로 설치하는 방법을 제공하기 위해 `install_packages` 함수를 추가합니다. 패키지 목록과 함께 `apt-get install`을 호출하는 것은 각 패키지에 대해 루프에서 개별적으로 호출하는 것보다 성능이 더 좋습니다. 이 함수는 패키지 이름 배열을 받아 단일 `sudo apt-get install` 명령에 모두 전달함으로써 여러 종속성을 설치해야 하는 호출 스크립트를 단순화합니다.\n\n**파일**: `scripts/cpp_development_environment/linux/common_utils.sh`\n\n```shell\n...\n# apt-get을 사용하여 여러 패키지를 설치합니다.\n# 사용법: install_packages \"package1\" \"package2\" ...\ninstall_packages() {\n local packages_to_install=(\"$@\")\n if [ ${#packages_to_install[@]} -eq 0 ]; then\n log_warning \"설치할 패키지가 지정되지 않았습니다.\"\n return 0\n fi\n\n log_info \"패키지 설치 중: ${packages_to_install[*]}...\"\n # apt가 이미 설치된 패키지를 정상적으로 처리하므로, 사전 확인은 하지 않습니다.\n if sudo apt-get install -y \"${packages_to_install[@]}\"; then\n log_info \"✅ 패키지가 성공적으로 설치되었습니다.\"\n return 0\n else\n log_error \"❌ 하나 이상의 패키지 설치에 실패했습니다. apt-get 로그를 확인해주세요.\"\n return 1\n fi\n}\n...\n```\n\n---\n\n### 단계 5: Linux를 위한 포괄적인 `install_and_verify_tool` 함수\n\n#### 1. 고수준 도구 설치 래퍼 구현\n\n이 작업은 다른 설치 스크립트를 위한 기본 인터페이스인 `install_and_verify_tool`을 구현합니다. 이 함수는 도구 설정의 전체 라이프사이클을 조율합니다: 프로그램 존재 여부를 확인하고, 필요한 경우 `install_with_apt`를 사용하여 해당 패키지를 설치하며, 마지막으로 명령어가 실행 가능하고 `PATH`에 있는지 확인합니다. 결정적으로, `is_critical` 플래그를 받습니다. 중요한 도구의 설치 또는 확인이 실패하면, 함수는 `exit 1`을 호출하여 전체 설정 프로세스를 중단시켜 부분적으로 손상된 환경을 방지합니다.\n\n**파일**: `scripts/cpp_development_environment/linux/common_utils.sh`\n\n```shell\n...\n# 도구를 설치하고 확인하는 헬퍼 함수입니다.\n# 중요 및 비중요 도구를 모두 처리합니다.\n# 사용법: install_and_verify_tool \ninstall_and_verify_tool() {\n local program_name=\"$1\"\n local package_name=\"$2\"\n local is_critical=\"$3\" # \"true\" 또는 \"false\"\n\n log_info \"--- $program_name 처리 중 ---\"\n\n if is_program_installed \"$program_name\"; then\n log_info \"✅ $program_name 은(는) 이미 설치되어 있습니다. 확인 중...\"\n if verify_command \"$program_name\"; then\n log_info \"✅ $program_name 확인 성공.\"\n return 0\n fi\n\n log_warning \"설치된 $program_name 확인에 실패했습니다. 재설치를 시도합니다.\"\n else\n log_info \"$program_name 이(가) 설치되지 않았습니다. 설치를 진행합니다.\"\n fi\n\n # 설치/재설치\n if ! install_with_apt \"$package_name\"; then\n log_warning \"$package_name 설치에 실패했습니다.\"\n if [[ \"$is_critical\" == \"true\" ]]; then\n log_error \"중요 도구 $package_name 설치에 실패했습니다. 중단합니다.\"\n exit 1\n fi\n return 1 # 중요하지 않은 실패\n fi\n\n # 최종 확인\n if ! verify_command \"$program_name\"; then\n log_warning \"$program_name 설치 후 확인에 실패했습니다.\"\n if [[ \"$is_critical\" == \"true\" ]]; then\n log_error \"중요 도구 $program_name 확인에 실패했습니다. 중단합니다.\"\n exit 1\n fi\n return 1 # 중요하지 않은 실패\n fi\n\n log_info \"✅ $program_name 을(를) 성공적으로 설치하고 확인했습니다.\"\n return 0\n}\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n`common_utils.sh`의 기능을 검증하려면, 이를 소싱하고 핵심 함수를 실행하는 임시 테스트 스크립트를 생성합니다. 이 테스트는 `sudo` 권한이 있는 Linux 환경에서 실행해야 합니다.\n\n1. **테스트 스크립트 `test_linux_utils.sh` 생성:**\n\n ```bash\n #!/bin/bash\n set -euo pipefail\n\n # 테스트할 유틸리티 스크립트를 소싱합니다.\n source ./scripts/cpp_development_environment/linux/common_utils.sh\n\n echo \"--- 테스트 1: update_apt_cache ---\"\n update_apt_cache\n\n echo -e \"\\n--- 테스트 2: install_and_verify_tool (중요하지 않음, 이미 설치됨: curl) ---\"\n install_and_verify_tool \"curl\" \"curl\" \"false\"\n\n echo -e \"\\n--- 테스트 3: install_and_verify_tool (중요하지 않음, 설치 예정: jq) ---\"\n # 먼저 jq가 설치되지 않았는지 확인: sudo apt-get remove -y jq\n install_and_verify_tool \"jq\" \"jq\" \"false\"\n\n echo -e \"\\n--- 테스트 4: install_packages (여러 도구) ---\"\n install_packages \"tree\" \"htop\"\n\n echo -e \"\\n--- 모든 테스트 통과 ---\"\n ```\n\n2. **테스트 스크립트 실행:**\n\n ```bash\n bash test_linux_utils.sh\n ```\n\n### 4.2. 예상 결과\n\n스크립트는 오류 없이 실행되어야 합니다 (`exit 0`). 콘솔 출력에는 유틸리티 함수의 로그 메시지가 표시되어 각 단계를 확인합니다. 출력은 다음과 유사해야 합니다 (타임스탬프와 패키지 버전은 다를 수 있습니다):\n\n```\n--- 테스트 1: update_apt_cache ---\n[INFO] apt 패키지 캐시를 업데이트하는 중입니다 (sudo apt-get update)...\n... (apt-get update 출력) ...\n[INFO] ✅ apt 패키지 캐시가 성공적으로 업데이트되었습니다.\n\n--- 테스트 2: install_and_verify_tool (중요하지 않음, 이미 설치됨: curl) ---\n[INFO] --- curl 처리 중 ---\n[INFO] ✅ curl 은(는) 이미 설치되어 있습니다. 확인 중...\n[INFO] 명령어 확인 중: curl --version\n[INFO] ✅ curl 확인 성공.\n\n--- 테스트 3: install_and_verify_tool (중요하지 않음, 설치 예정: jq) ---\n[INFO] --- jq 처리 중 ---\n[INFO] jq 이(가) 설치되지 않았습니다. 설치를 진행합니다.\n[INFO] jq 설치 여부를 확인 중...\n[INFO] apt-get으로 jq 을(를) 설치 중...\n... (apt-get install jq 출력) ...\n[INFO] ✅ jq 이(가) 성공적으로 설치되었습니다.\n[INFO] 명령어 확인 중: jq --version\n[INFO] ✅ jq 확인 성공.\n[INFO] ✅ jq 을(를) 성공적으로 설치하고 확인했습니다.\n\n--- 테스트 4: install_packages (여러 도구) ---\n[INFO] 패키지 설치 중: tree htop...\n... (apt-get install tree htop 출력) ...\n[INFO] ✅ 패키지가 성공적으로 설치되었습니다.\n\n--- 모든 테스트 통과 ---\n```","APT 캐시를 업데이트하고 패키지를 설치/검증하는 함수가 포함된 유틸리티 스크립트",[574,576,578,580,582],{"_24":575,"_83":39,"_84":94,"_85":61},"APT 캐시를 업데이트하는 함수 (`update_apt_cache`)",{"_24":577,"_83":39,"_84":94,"_85":88},"멱등성 패키지 설치를 위한 함수 (`install_with_apt`)",{"_24":579,"_83":39,"_84":94,"_85":91},"Linux를 위한 포괄적인 `install_and_verify_tool` 함수",{"_24":581,"_83":39,"_84":94,"_85":94},"다중 패키지 설치 프로그램 (`install_packages`)",{"_24":583,"_83":39,"_84":94,"_85":97},"OS에 구애받지 않는 유틸리티 소싱","일관된 패키지 설치를 보장하기 위한 APT 작업의 추상화 계층",{"_22":586,"_24":587,"_75":588,"_77":589,"_79":590,"_51":599,"_42":99},"task-1751000762007","크로스 플랫폼 Clang 제품군 설치","# 작업: 크로스 플랫폼 Clang 스위트 설치\n\n> **에픽**: C++ 빌드 툴체인 설치\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: Clang 컴파일러와 관련 도구(clangd, clang-tidy, lldb)의 자동화된 설치.\n- **근거**: macOS와 Linux 양쪽에서 완전하고 표준화된 C++ 툴체인을 구축하기 위함. 이는 개발자에게 컴파일(`clang`), 언어 서버 지원(`clangd`), 정적 분석(`clang-tidy`), 디버깅(`lldb`)에 필수적인 도구를 제공하며, 이는 프로젝트의 핵심 목표에 명시된 현대적인 C++ 개발 환경의 기반이 됨.\n\n### 1.2. 결과물\n\n- **예상 결과**: 전체 Clang 툴체인을 설치하고 검증하는 macOS 및 Linux용 스크립트 한 쌍.\n- **사양**:\n - **macOS**: `clangd`, `clang-tidy`, `lldb`를 제공하기 위해 `llvm` Homebrew 포뮬러가 설치될 것. 각 도구에 대해 `$(brew --prefix)/bin`에 심볼릭 링크가 생성될 것.\n - **Linux**: `clang`, `clangd`, `clang-tidy`, `lldb` 패키지가 `apt`를 통해 설치될 것.\n - 두 스크립트는 모두 멱등성을 가져야 하며, 각 도구가 시스템 `PATH`에서 접근 가능한지 확인하는 검증 단계를 포함해야 함.\n- **결과 파일 구조**\n\n```bash\n# ./scripts/cpp_development_environment/\n# ├── linux/\n# │ └── install_clang.sh <-- 수정됨\n# └── macos/\n# └── install_clang.sh <-- 수정됨\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph 오케스트레이션\n SetupSH[\"setup.sh\"]\n end\n subgraph 플랫폼별 설치\n DetectOS[\"OS 감지\"]\n InstallClangMacOS[\"macos/install_clang.sh\"]\n InstallClangLinux[\"linux/install_clang.sh\"]\n end\n subgraph 패키지 관리자\n Homebrew[\"Homebrew\"]\n APT[\"APT\"]\n end\n\n SetupSH --> DetectOS\n DetectOS -- \"macOS\" --> InstallClangMacOS\n DetectOS -- \"Linux\" --> InstallClangLinux\n InstallClangMacOS --> Homebrew[\"'llvm' 패키지 설치\"]\n InstallClangLinux --> APT[\"'clang', 'clangd' 등 설치\"]\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 개략적인 체크리스트이며, 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] Homebrew를 사용하여 'llvm' 패키지를 설치하는 macOS 스크립트.\n- [ ] LLVM 도구에 필요한 심볼릭 링크를 생성하는 macOS 스크립트 내 함수.\n- [ ] APT를 사용하여 `clang`, `clangd`, `clang-tidy`, `lldb` 패키지를 설치하는 Linux 스크립트.\n- [ ] 두 스크립트 모두에서 설치된 모든 도구에 대한 검증 단계.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 스크립트 기반 오케스트레이션\n- **관련 주요 구성 요소**:\n - **`setup.sh`**: 메인 오케스트레이션 스크립트. 운영 체제를 감지하고 올바른 플랫폼별 설치 스크립트(`install_clang.sh`)를 호출하는 역할을 합니다. 이 작업은 오케스트레이터가 호출하는 핵심 모듈 중 하나를 제공합니다.\n - **`macos/scripts`**: 이 디렉터리는 macOS별 설치 로직을 포함합니다. `macos/install_clang.sh` 스크립트는 Homebrew를 사용하여 LLVM 툴체인을 설치하도록 수정될 것입니다.\n - **`linux/scripts`**: 이 디렉터리는 Linux별 설치 로직을 포함합니다. `linux/install_clang.sh` 스크립트는 `apt`를 사용하여 필요한 Clang 패키지를 설치하도록 수정될 것입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `scripts/cpp_development_environment/macos/install_clang.sh`\n- `scripts/cpp_development_environment/linux/install_clang.sh`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공할 것입니다.\n\n---\n\n### 단계 1: Homebrew를 사용하여 'llvm' 패키지를 설치하는 macOS 스크립트\n\n이 단계는 macOS에 대한 2단계 및 4단계와 함께 macOS 스크립트에 대한 단일 수정을 통해 완료될 것입니다. 디버깅에 필수적인 `lldb` 도구가 필요한 LLVM 헬퍼 도구 목록에 추가되어야 합니다. 이를 통해 `llvm` 패키지를 통해 설치되고, 다른 도구들과 함께 심볼릭 링크가 생성되고 검증되도록 보장합니다.\n\n#### 1. 관리되는 LLVM 도구 목록에 `lldb` 추가\n\n`LLVM_HELPER_TOOLS` 배열을 수정하여 `lldb`를 포함시킵니다. 이 변경은 스크립트의 기존 설치, 심볼릭 링크 생성 및 검증 로직이 이제 `lldb`에도 적용되도록 하여 macOS에서의 Clang 툴체인 설정을 완료합니다.\n\n**파일**: `scripts/cpp_development_environment/macos/install_clang.sh`\n\n```bash\n# ... (코드 생략)\n\n# 2. 필요한 LLVM 헬퍼 도구 정의 및 확인\nLLVM_HELPER_TOOLS=(\"clangd\" \"clang-format\" \"clang-tidy\" \"lldb\")\nlog_info \"--- LLVM 헬퍼 도구(clangd, clang-format, clang-tidy, lldb) 검증 ---\"\n\nif check_if_all_tools_are_installed \"${LLVM_HELPER_TOOLS[@]}\"; then\n# ... (코드 생략)\n```\n\n---\n\n### 단계 2: LLVM 도구에 필요한 심볼릭 링크를 생성하는 macOS 스크립트 내 함수\n\n`create_llvm_symlinks` 함수는 이미 존재하며 올바르게 구현되어 있습니다. 1단계의 조치로 `lldb`가 `LLVM_HELPER_TOOLS` 배열에 포함되었으며, 이 배열은 이 함수에 전달됩니다. 이 단계를 위해 더 이상의 변경은 필요하지 않습니다.\n\n---\n\n### 단계 3: APT를 사용하여 `clang`, `clangd`, `clang-tidy`, `lldb` 패키지를 설치하는 Linux 스크립트\n\n기존 Linux 스크립트에는 이미 `install_and_verify_tool` 헬퍼 함수를 사용하여 필요한 모든 패키지를 설치하는 데 필요한 로직이 포함되어 있습니다. 구현은 설치할 패키지를 올바르게 지정합니다.\n\n#### 1. Clang 툴체인 설치 로직 확인\n\n`install_and_verify_tool`이 `clang`, `clangd`, `clang-tidy`, `lldb`에 대해 호출되는지 확인합니다. 기존 코드는 이 요구 사항을 충족합니다.\n\n**파일**: `scripts/cpp_development_environment/linux/install_clang.sh`\n\n```bash\n# ... (코드 생략)\n\n# --- 도구 설치 및 검증 ---\ninstall_and_verify_tool \"clang\" \"clang\" \"true\"\ninstall_and_verify_tool \"clangd\" \"clangd\" \"true\"\ninstall_and_verify_tool \"clang-tidy\" \"clang-tidy\" \"false\"\ninstall_and_verify_tool \"clang-format\" \"clang-format\" \"false\"\ninstall_and_verify_tool \"lldb\" \"lldb\" \"true\"\n\nlog_info \"Clang 및 관련 도구 설치 스크립트가 성공적으로 완료되었습니다.\"\n```\n\n---\n\n### 단계 4: 두 스크립트 모두에서 설치된 모든 도구에 대한 검증 단계\n\n검증 로직은 두 스크립트에 내장되어 있으며 설치할 도구 목록에 따라 구동됩니다.\n\n#### 1. macOS 검증 로직 확인\n\n1단계에서 취한 조치(`lldb`를 `LLVM_HELPER_TOOLS` 배열에 추가)로 충분합니다. `macos/install_clang.sh`의 기존 \"최종 검증\" 루프는 이 배열을 순회하며, 이제 설치 후 `lldb`를 자동으로 검증할 것입니다. 추가 코드는 필요하지 않습니다.\n\n#### 2. Linux 검증 로직 확인\n\n기존 `linux/install_clang.sh` 스크립트에서 사용된 `install_and_verify_tool` 헬퍼 함수는 설치와 후속 검증을 모두 처리합니다. 스크립트는 필요한 모든 도구에 대해 이 함수를 올바르게 호출하여 검증 요구 사항을 충족합니다. 변경이 필요하지 않습니다.\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 구현을 검증하려면, 각 스크립트를 해당 대상 플랫폼에서 실행하십시오.\n\n**macOS에서:**\n\n```bash\n# 스크립트 디렉터리로 이동\ncd scripts/cpp_development_environment/macos\n\n# 스크립트를 실행 가능하게 만듦\nchmod +x install_clang.sh\n\n# 스크립트 실행\n./install_clang.sh\n\n# 모든 도구가 PATH에 있는지 수동으로 확인\ncommand -v clangd && clangd --version\ncommand -v clang-tidy && clang-tidy --version\ncommand -v lldb && lldb --version\n```\n\n**Linux에서:**\n\n```bash\n# 스크립트 디렉터리로 이동\ncd scripts/cpp_development_environment/linux\n\n# 스크립트를 실행 가능하게 만듦\nchmod +x install_clang.sh\n\n# 스크립트 실행\n./install_clang.sh\n\n# 모든 도구가 PATH에 있는지 수동으로 확인\ncommand -v clang && clang --version\ncommand -v clangd && clangd --version\ncommand -v clang-tidy && clang-tidy --version\ncommand -v lldb && lldb --version\n```\n\n### 4.2. 예상 결과\n\n- 스크립트 실행은 macOS에서는 `✅ All LLVM helper tools are now installed and verified.` 또는 Linux에서는 `Clang and related tools installation script finished successfully.`와 같은 최종 성공 메시지와 함께 완료되어야 합니다.\n- 출력에 오류 메시지가 없어야 합니다.\n- 각 수동 `command -v ` 및 ` --version` 확인은 성공적으로 실행되어야 하며, 각 도구의 버전 정보를 출력하여 `PATH`에 올바르게 설치되고 접근 가능한지 확인해야 합니다.","전체 Clang 툴체인을 설치하고 검증하는 macOS 및 Linux용 스크립트 한 쌍",[591,593,595,597],{"_24":592,"_83":39,"_84":97,"_85":61},"Homebrew를 사용하여 'llvm' 패키지를 설치하는 macOS 스크립트",{"_24":594,"_83":39,"_84":97,"_85":88},"LLVM 도구에 필요한 심볼릭 링크를 생성하는 macOS 스크립트 내 함수",{"_24":596,"_83":39,"_84":97,"_85":91},"APT를 사용하여 `clang`, `clangd`, `clang-tidy`, `lldb` 패키지를 설치하는 Linux 스크립트",{"_24":598,"_83":39,"_84":97,"_85":94},"두 스크립트 모두에서 설치된 모든 도구에 대한 검증 단계","Clang 컴파일러 및 관련 도구(clangd, clang-tidy, lldb)의 자동화된 설치",{"_22":601,"_24":602,"_75":603,"_77":604,"_79":605,"_51":614,"_42":99},"task-1751000830180","크로스 플랫폼 CMake 설치","# 작업: 크로스플랫폼 CMake 설치\n\n> **에픽**: C++ 빌드 툴체인 설치\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: CMake 빌드 시스템 생성기의 자동 설치.\n- **근거**: CMake는 C++ 빌드 툴체인의 핵심 구성 요소입니다. 소스 코드 구성으로부터 빌드 파일(예: Makefiles, Ninja 파일) 생성을 자동화하여 샘플 프로젝트 및 이후의 모든 C++ 개발을 컴파일하는 데 필수적입니다. CMake 설치는 완전히 자동화된 크로스플랫폼 C++ 환경이라는 프로젝트 목표를 달성하기 위한 중요한 단계입니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: macOS 및 Linux용 스크립트로, CMake를 핵심 종속성으로 설치하고 검증합니다.\n- **사양**:\n - 인수로 `\"cmake\"`, `\"cmake\"`, `\"formula\"`, `\"true\"`를 사용하여 `install_and_verify_tool` 함수를 호출하는 macOS 셸 스크립트.\n - 인수로 `\"cmake\"`, `\"cmake\"`, `\"true\"`를 사용하여 `install_and_verify_tool` 함수를 호출하는 Linux 셸 스크립트.\n - 두 스크립트 모두 헬퍼 함수를 사용할 수 있도록 필요한 유틸리티 스크립트를 소싱해야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── scripts/\n# └── cpp_development_environment/\n# ├── linux/\n# │ └── install_cmake.sh <-- Modified\n# └── macos/\n# └── install_cmake.sh <-- Modified\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph 오케스트레이터\n SetupSH[\"setup.sh\"]\n end\n subgraph \"플랫폼 스크립트\"\n DetectOS[\"OS 감지\"]\n InstallCMakeMacOS[\"macos/install_cmake.sh\"]\n InstallCMakeLinux[\"linux/install_cmake.sh\"]\n end\n subgraph \"패키지 관리자\"\n Homebrew[\"Homebrew\"]\n APT[\"APT\"]\n end\n\n SetupSH --> DetectOS;\n DetectOS -- \"macOS\" --> InstallCMakeMacOS;\n DetectOS -- \"Linux\" --> InstallCMakeLinux;\n InstallCMakeMacOS --> Homebrew;\n InstallCMakeLinux --> APT;\n\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] 'cmake' formula에 대해 `install_and_verify_tool` 헬퍼를 사용하는 macOS 스크립트.\n- [ ] 'cmake' 패키지에 대해 `install_and_verify_tool` 헬퍼를 사용하는 Linux 스크립트.\n- [ ] 플랫폼별 유틸리티 스크립트의 올바른 소싱.\n- [ ] 설치 로직에서 CMake를 핵심 도구로 지정.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 스크립트 기반 오케스트레이션\n- **관련 주요 구성 요소**:\n - **`setup.sh`**: 감지된 운영 체제에 따라 이러한 플랫폼별 설치 스크립트를 호출할 메인 오케스트레이터 스크립트.\n - **`macos/scripts`**: macOS용 플랫폼별 스크립트를 포함하는 디렉터리. 이 작업은 이 구성 요소에 `install_cmake.sh` 스크립트를 추가합니다.\n - **`linux/scripts`**: Linux용 플랫폼별 스크립트를 포함하는 디렉터리. 이 작업은 이 구성 요소에 `install_cmake.sh` 스크립트를 추가합니다.\n - **`common/scripts`**: 이 구성 요소는 `log_info` 및 `install_and_verify_tool`과 같은 헬퍼 함수를 정의하는 OS에 구애받지 않는 유틸리티 스크립트(예: `common_utils.sh`)를 포함합니다. 이 작업에서 생성된 스크립트는 이러한 헬퍼에 의존합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정됩니다.\n\n- `scripts/cpp_development_environment/macos/install_cmake.sh`\n- `scripts/cpp_development_environment/linux/install_cmake.sh`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공하게 됩니다.\n\n---\n\n### 단계 1: 'cmake' formula에 대해 `install_and_verify_tool` 헬퍼를 사용하는 macOS 스크립트\n\n#### 1. macOS 설치 로직 구현\n\n이 액션은 macOS 스크립트의 주 로직을 생성하는 것을 포함합니다. CMake의 프로그램 및 패키지 이름을 정의한 다음 `install_and_verify_tool` 헬퍼 함수를 호출합니다. 공통 유틸리티 스크립트에서 제공되는 이 함수는 Homebrew를 통한 멱등성 설치를 처리하고 `PATH`에 존재하는지 확인합니다.\n\n**파일**: `scripts/cpp_development_environment/macos/install_cmake.sh`\n\n```bash\n#!/bin/bash\n...\n# --- 스크립트 주 로직 ---\nlog_info \"🧩 CMake 설치 중 (macOS)...\"\n\n# 프로그램 및 패키지 이름 정의\nCMAKE_PROGRAM_NAME=\"cmake\"\nCMAKE_PACKAGE_NAME=\"cmake\"\n\n# 공유 헬퍼 함수를 사용하여 CMake 설치 및 검증.\n# CMake는 핵심 빌드 도구이므로 네 번째 인수는 \"true\"입니다.\ninstall_and_verify_tool \"$CMAKE_PROGRAM_NAME\" \"$CMAKE_PACKAGE_NAME\" \"formula\" \"true\"\n\nlog_info \"CMake 설치 스크립트가 성공적으로 완료되었습니다.\"\n```\n\n---\n\n### 단계 2: 'cmake' 패키지에 대해 `install_and_verify_tool` 헬퍼를 사용하는 Linux 스크립트\n\n#### 1. Linux 설치 로직 구현\n\n이 액션은 Linux 스크립트의 주 로직을 생성하는 것을 포함합니다. 설치를 시도하기 전에 `apt` 패키지 캐시를 업데이트하여 패키지 정보가 최신인지 확인하는 것이 중요합니다. 업데이트 후, CMake의 프로그램 및 패키지 이름을 정의하고 `install_and_verify_tool` 헬퍼 함수를 호출하여 `apt`를 통해 설치를 수행합니다.\n\n**파일**: `scripts/cpp_development_environment/linux/install_cmake.sh`\n\n```bash\n#!/bin/bash\n...\n# --- 스크립트 주 로직 ---\nlog_info \"🧩 CMake 설치 중 (Linux)...\"\n\n# apt 캐시 업데이트 (패키지 설치 전 중요)\nif ! update_apt_cache; then\n log_error \"apt 캐시 업데이트에 실패했습니다. CMake 설치를 중단합니다.\"\n exit 1\nfi\n\n# 프로그램 및 패키지 이름 정의\nCMAKE_PROGRAM_NAME=\"cmake\"\nCMAKE_PACKAGE_NAME=\"cmake\"\n\n# 공유 헬퍼 함수를 사용하여 CMake 설치 및 검증\n# CMake는 빌드에 핵심적이므로 세 번째 인수는 \"true\"입니다\ninstall_and_verify_tool \"$CMAKE_PROGRAM_NAME\" \"$CMAKE_PACKAGE_NAME\" \"true\"\n\nlog_info \"CMake 설치 스크립트가 성공적으로 완료되었습니다.\"\n```\n\n---\n\n### 단계 3: 플랫폼별 유틸리티 스크립트의 올바른 소싱\n\n#### 1. macOS 스크립트에 유틸리티 소싱 추가\n\n`log_info` 및 `install_and_verify_tool`과 같은 헬퍼 함수를 사용 가능하게 하려면, 스크립트가 공통 유틸리티 스크립트를 소싱해야 합니다. 이는 먼저 스크립트 자체의 디렉터리를 확인한 다음 유틸리티 스크립트(예: `common_utils.sh`)에 대한 상대 경로를 구성하여, 스크립트가 자체 포함되고 어떤 위치에서든 실행 가능하도록 보장합니다.\n\n**파일**: `scripts/cpp_development_environment/macos/install_cmake.sh`\n\n```bash\n#!/bin/bash\n\nset -euo pipefail\n\n# 현재 실행 중인 스크립트의 디렉터리 가져오기\nINSTALL_CMAKE_MACOS_DIRECTORY=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\n# 공통 유틸리티 소싱\n# shellcheck source=./common_utils.sh\nsource \"$INSTALL_CMAKE_MACOS_DIRECTORY/common_utils.sh\"\n\n# --- 스크립트 주 로직 ---\n...\n```\n\n#### 2. Linux 스크립트에 유틸리티 소싱 추가\n\n마찬가지로, Linux 스크립트도 동일한 헬퍼 함수 세트에 접근해야 합니다. 스크립트의 디렉터리를 확인하고 공통 유틸리티 스크립트를 `source`하는 표준 상용구를 추가하여 공유 로직을 실행할 수 있도록 만듭니다.\n\n**파일**: `scripts/cpp_development_environment/linux/install_cmake.sh`\n\n```bash\n#!/bin/bash\n\nset -euo pipefail\n\n# 현재 실행 중인 스크립트의 디렉터리 가져오기\nINSTALL_CMAKE_LINUX_DIRECTORY=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\n\n# 공통 유틸리티 소싱\n# shellcheck source=./common_utils.sh\nsource \"$INSTALL_CMAKE_LINUX_DIRECTORY/common_utils.sh\"\n\n# --- 스크립트 주 로직 ---\n...\n```\n\n---\n\n### 단계 4: 설치 로직에서 CMake를 핵심 도구로 지정\n\n#### 1. macOS 스크립트에서 중요도 플래그 설정\n\n`install_and_verify_tool` 함수는 도구를 \"핵심\"으로 지정하기 위해 마지막 불리언 인수를 받습니다. CMake의 경우, 이 값은 `\"true\"`로 설정되어야 합니다. 이는 CMake의 설치 또는 검증이 실패할 경우, 헬퍼 함수가 0이 아닌 상태 코드로 종료되어 전체 `setup.sh` 오케스트레이터가 `set -e`로 인해 즉시 중단되도록 보장합니다.\n\n**파일**: `scripts/cpp_development_environment/macos/install_cmake.sh`\n\n```bash\n...\n# 네 번째 인수 \"true\"는 이것을 핵심 종속성으로 표시합니다.\ninstall_and_verify_tool \"$CMAKE_PROGRAM_NAME\" \"$CMAKE_PACKAGE_NAME\" \"formula\" \"true\"\n...\n```\n\n#### 2. Linux 스크립트에서 중요도 플래그 설정\n\n`install_and_verify_tool` 호출의 Linux 버전도 중요도 플래그가 필요합니다. 마지막 인수를 `\"true\"`로 설정하여 CMake 설치 실패 시 전체 설정 프로세스가 중지되도록 강제합니다. 이는 두 플랫폼에서 일관된 오류 처리 동작을 유지합니다.\n\n**파일**: `scripts/cpp_development_environment/linux/install_cmake.sh`\n\n```bash\n...\n# 세 번째 인수 \"true\"는 이것을 핵심 종속성으로 표시합니다.\ninstall_and_verify_tool \"$CMAKE_PROGRAM_NAME\" \"$CMAKE_PACKAGE_NAME\" \"true\"\n...\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 구현을 검증하려면 각 스크립트를 해당 대상 OS에서 개별적으로 실행합니다. 실행 후, `cmake` 명령어가 시스템 `PATH`에서 사용 가능하고 버전을 보고하는지 확인합니다.\n\n**macOS에서:**\n\n```bash\n# 1. macOS 설치 스크립트 실행\nbash scripts/cpp_development_environment/macos/install_cmake.sh\n\n# 2. 명령어가 사용 가능한지 확인\ncommand -v cmake\n\n# 3. 설치된 버전 확인\ncmake --version\n```\n\n**Linux에서:**\n\n```bash\n# 1. Linux 설치 스크립트 실행\nbash scripts/cpp_development_environment/linux/install_cmake.sh\n\n# 2. 명령어가 사용 가능한지 확인\ncommand -v cmake\n\n# 3. 설치된 버전 확인\ncmake --version\n```\n\n### 4.2. 예상 결과\n\n- 스크립트를 실행하면 설치의 시작과 성공적인 완료를 나타내는 정보 메시지가 기록됩니다.\n- `command -v cmake` 명령어는 `cmake` 실행 파일의 절대 경로(예: `/usr/local/bin/cmake` 또는 `/usr/bin/cmake`)를 출력합니다.\n- `cmake --version` 명령어는 오류 없이 버전 정보를 출력합니다.\n\n**예상 출력:**\n\n```\n$ command -v cmake\n/usr/local/bin/cmake\n\n$ cmake --version\ncmake version 3.28.1\n\nCMake suite maintained and supported by Kitware (kitware.com/cmake).\n```","중요한 의존성으로 CMake를 설치하고 검증하는 macOS 및 Linux용 스크립트",[606,608,610,612],{"_24":607,"_83":39,"_84":176,"_85":61},"'cmake' formula에 `install_and_verify_tool` 헬퍼를 사용하는 macOS 스크립트",{"_24":609,"_83":39,"_84":176,"_85":88},"'cmake' 패키지에 `install_and_verify_tool` 헬퍼를 사용하는 Linux 스크립트",{"_24":611,"_83":39,"_84":176,"_85":91},"플랫폼별 유틸리티 스크립트의 적절한 소싱",{"_24":613,"_83":39,"_84":176,"_85":94},"설치 로직에서 CMake를 중요 도구로 지정","CMake 빌드 시스템 생성기의 자동화된 설치",{"_22":616,"_24":617,"_75":618,"_77":619,"_79":620,"_51":628,"_42":99},"task-1751000895711","크로스 플랫폼 Ninja 설치","# 작업: 크로스플랫폼 Ninja 설치\n\n> **에픽**: C++ 빌드 툴체인 설치\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: Ninja 빌드 시스템의 자동화된 설치.\n- **근거**: Ninja는 작고, 목적에 집중하며, 매우 빠른 빌드 시스템입니다. 이는 CMake를 사용하는 현대 C++ 프로젝트의 핵심 의존성이며, 전통적인 Makefile에 비해 컴파일 단계를 크게 가속화합니다. Ninja를 통합하는 것은 프로젝트의 핵심 목표에 명시된 고성능 C++ 개발 환경을 제공하는 데 필수적입니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: Ninja를 핵심 의존성으로 설치하고 검증하는 macOS 및 Linux용 스크립트.\n- **명세**:\n - `\"ninja\"`, `\"ninja\"`, `\"formula\"`, `\"true\"` 인자와 함께 플랫폼 유틸리티 함수 `install_and_verify_tool`을 활용하는 macOS 스크립트 `macos/install_ninja.sh`.\n - `\"ninja\"`, `\"ninja-build\"`, `\"true\"` 인자와 함께 플랫폼 유틸리티 함수 `install_and_verify_tool`을 활용하는 Linux 스크립트 `linux/install_ninja.sh`.\n - 두 스크립트 모두 헬퍼 함수에 접근하기 위해 필요한 유틸리티 스크립트를 올바르게 소싱(source)해야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./scripts/cpp_development_environment/\n# ├── linux/\n# │ └── install_ninja.sh <-- 수정됨\n# └── macos/\n# └── install_ninja.sh <-- 수정됨\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph 오케스트레이션\n SetupSH[\"setup.sh\"]\n end\n subgraph \"플랫폼별 설치 (이번 작업)\"\n DetectOS{\"OS 감지\"}\n InstallNinjaMacOS[\"macos/install_ninja.sh\"]\n InstallNinjaLinux[\"linux/install_ninja.sh\"]\n UtilityMacOS[\"macOS 유틸리티
(install_and_verify_tool)\"]\n UtilityLinux[\"Linux 유틸리티
(install_and_verify_tool)\"]\n Homebrew[\"Homebrew로 'ninja' 설치\"]\n Apt[\"apt로 'ninja-build' 설치\"]\n end\n\n SetupSH --> DetectOS\n DetectOS -->|macOS| InstallNinjaMacOS\n DetectOS -->|Linux| InstallNinjaLinux\n InstallNinjaMacOS --> UtilityMacOS\n InstallNinjaLinux --> UtilityLinux\n UtilityMacOS --> Homebrew\n UtilityLinux --> Apt\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] 'ninja' 포뮬러에 대해 `install_and_verify_tool` 헬퍼를 활용하는 macOS 스크립트.\n- [ ] 'ninja-build' 패키지에 대해 `install_and_verify_tool` 헬퍼를 활용하는 Linux 스크립트.\n- [ ] 플랫폼별 유틸리티 스크립트의 적절한 소싱(sourcing).\n- [ ] 설치 로직에서 Ninja를 핵심 도구로 지정.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 스크립트 기반 오케스트레이션\n- **관련된 주요 구성 요소**:\n - `setup.sh`: 이 메인 오케스트레이터는 감지된 운영 체제에 따라 플랫폼별 Ninja 설치 스크립트를 호출합니다.\n - `macos/scripts`: 이 구성 요소는 패키지 관리를 위해 Homebrew를 활용하는 macOS 전용 `install_ninja.sh` 스크립트를 포함합니다. 이 작업은 이 구성 요소 내의 스크립트를 수정합니다.\n - `linux/scripts`: 이 구성 요소는 패키지 관리를 위해 `apt`를 활용하는 Linux 전용 `install_ninja.sh` 스크립트를 포함합니다. 이 작업은 이 구성 요소 내의 스크립트를 수정합니다.\n - `common/scripts`: 설치 스크립트는 각 플랫폼의 유틸리티 스크립트(`common_utils.sh`)를 소싱하여 로깅 및 멱등성 있는 도구 설치와 같은 공유 기능을 제공하며, 모듈식 설계를 강제합니다.\n\n### 2.2. 영향을 받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `scripts/cpp_development_environment/macos/install_ninja.sh`\n- `scripts/cpp_development_environment/linux/install_ninja.sh`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계(Step)`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `조치(Action)`로 나뉩니다. 각 `조치`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 'ninja' 포뮬러에 대해 `install_and_verify_tool` 헬퍼를 활용하는 macOS 스크립트\n\n#### 1. macOS에서 Ninja 설치 정의 및 실행\n\n이 조치는 macOS 설치 스크립트를 채웁니다. 스크립트는 프로그램 이름(`ninja`)과 해당 Homebrew 패키지 이름(`ninja`)을 정의합니다. 그런 다음 공유 헬퍼 함수 `install_and_verify_tool`을 호출하여 Homebrew를 통한 멱등성 있는 설치 및 후속 검증을 처리합니다. 이 추상화는 다른 도구들이 설치되는 방식과의 일관성을 보장합니다.\n\n**파일**: `scripts/cpp_development_environment/macos/install_ninja.sh`\n\n```shell\n...\n# --- Script Main Logic ---\nlog_info \"⚡ Ninja 설치 중 (macOS)...\"\n\n# 프로그램 및 패키지 이름 정의\nNINJA_PROGRAM_NAME=\"ninja\"\nNINJA_PACKAGE_NAME=\"ninja\"\n\n# 공유 헬퍼 함수를 사용하여 Ninja를 설치하고 검증합니다.\n# Ninja는 핵심 빌드 도구이므로 네 번째 인자는 \"true\"입니다.\ninstall_and_verify_tool \"$NINJA_PROGRAM_NAME\" \"$NINJA_PACKAGE_NAME\" \"formula\" \"true\"\n\nlog_info \"Ninja 설치 스크립트가 성공적으로 완료되었습니다.\"\n```\n\n---\n\n### 단계 2: 'ninja-build' 패키지에 대해 `install_and_verify_tool` 헬퍼를 활용하는 Linux 스크립트\n\n#### 1. Linux에서 Ninja 설치 정의 및 실행\n\n이 조치는 Linux 설치 스크립트를 채웁니다. 먼저 `apt` 캐시가 업데이트되었는지 확인합니다. 그런 다음 프로그램 이름(`ninja`)과 macOS 패키지 이름과 다른 해당 `apt` 패키지 이름(`ninja-build`)을 정의합니다. `install_and_verify_tool` 헬퍼 함수를 호출하여 멱등성 있는 설치를 수행하며, 이는 `apt` 명령어 로직을 캡슐화하고 스크립트의 목적을 명확하고 선언적으로 만듭니다.\n\n**파일**: `scripts/cpp_development_environment/linux/install_ninja.sh`\n\n```shell\n...\n# --- Script Main Logic ---\nlog_info \"Linux용 Ninja 설치 스크립트를 시작합니다...\"\n\n# 패키지를 설치하기 전에 apt 캐시를 업데이트합니다. 이 함수에는 캐시가 이미\n# 최신 상태일 경우 중복 업데이트를 방지하는 내장 확인 기능이 있습니다.\nupdate_apt_cache\n\n# 프로그램 및 패키지 이름 정의\nNINJA_PROGRAM_NAME=\"ninja\"\nNINJA_PACKAGE_NAME=\"ninja-build\"\n\n# 공유 헬퍼 함수를 사용하여 Ninja를 설치하고 검증합니다.\n# Ninja는 핵심 빌드 도구이므로 세 번째 인자는 \"true\"입니다.\ninstall_and_verify_tool \"$NINJA_PROGRAM_NAME\" \"$NINJA_PACKAGE_NAME\" \"true\"\n\nlog_info \"Ninja 설치 스크립트가 성공적으로 완료되었습니다.\"\n```\n\n---\n\n### 단계 3: 플랫폼별 유틸리티 스크립트의 적절한 소싱\n\n#### 1. macOS 설치 프로그램에서 유틸리티 스크립트 소싱\n\n`log_info` 및 `install_and_verify_tool`과 같은 헬퍼 함수를 사용하려면 macOS 스크립트는 먼저 `common_utils.sh` 스크립트를 소싱해야 합니다. 이 조치는 스크립트가 자신의 디렉토리를 먼저 결정하여 유틸리티를 찾고 로드할 수 있도록 보장하며, 소스 명령어를 견고하고 위치에 독립적으로 만듭니다. 이는 프로젝트의 모듈식 아키텍처의 기본입니다.\n\n**파일**: `scripts/cpp_development_environment/macos/install_ninja.sh`\n\n```shell\n#!/bin/bash\n\nset -euo pipefail\n\n# 현재 실행 중인 스크립트의 디렉토리를 가져옵니다\nINSTALL_NINJA_MACOS_DIRECTORY=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\n# 공용 유틸리티를 소싱합니다\n# shellcheck source=./common_utils.sh\nsource \"$INSTALL_NINJA_MACOS_DIRECTORY/common_utils.sh\"\n\n# --- Script Main Logic ---\n...\n```\n\n#### 2. Linux 설치 프로그램에서 유틸리티 스크립트 소싱\n\n마찬가지로, Linux 스크립트는 Linux 전용 헬퍼 함수에 액세스하기 위해 해당 `common_utils.sh`를 소싱해야 합니다. 이 조치는 Linux 스크립트의 상단에 필요한 상용구를 추가하여 필요한 셸 함수를 사용하기 전에 액세스할 수 있도록 보장합니다.\n\n**파일**: `scripts/cpp_development_environment/linux/install_ninja.sh`\n\n```shell\n#!/bin/bash\n\nset -euo pipefail\n\n# 현재 실행 중인 스크립트의 디렉토리를 가져옵니다\nINSTALL_NINJA_LINUX_DIRECTORY=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\n\n# 공용 유틸리티를 소싱합니다\n# shellcheck source=./common_utils.sh\nsource \"$INSTALL_NINJA_LINUX_DIRECTORY/common_utils.sh\"\n\n# --- Script Main Logic ---\n...\n```\n\n---\n\n### 단계 4: 설치 로직에서 Ninja를 핵심 도구로 지정\n\n#### 1. macOS 스크립트에서 핵심 플래그 설정\n\n이 조치는 Ninja 설치가 필수 단계로 처리되도록 보장합니다. `install_and_verify_tool` 함수의 마지막 인자는 핵심 여부를 나타내는 불리언 플래그입니다. 이것을 `\"true\"`로 설정함으로써, 만약 Ninja 설치에 실패하거나 설치 후 `PATH`에서 찾을 수 없는 경우, 헬퍼 함수는 전체 `setup.sh` 오케스트레이터를 오류와 함께 종료하도록 지시받습니다. 이는 부분적으로 작동하는 환경을 방지합니다.\n\n**파일**: `scripts/cpp_development_environment/macos/install_ninja.sh`\n\n```shell\n...\n# 공유 헬퍼 함수를 사용하여 Ninja를 설치하고 검증합니다.\n# Ninja는 핵심 빌드 도구이므로 네 번째 인자는 \"true\"입니다.\ninstall_and_verify_tool \"ninja\" \"ninja\" \"formula\" \"true\"\n...\n```\n\n#### 2. Linux 스크립트에서 핵심 플래그 설정\n\n이 조치는 동일한 핵심 의존성 로직을 Linux 스크립트에 적용합니다. `install_and_verify_tool`의 Linux 버전에서 세 번째 인자가 핵심 플래그 역할을 합니다. 이것을 `\"true\"`로 설정하면 설정 프로세스가 실패 시 중단되어 두 플랫폼 모두에서 전체 설치 프로세스의 견고성을 유지합니다.\n\n**파일**: `scripts/cpp_development_environment/linux/install_ninja.sh`\n\n```shell\n...\n# 공유 헬퍼 함수를 사용하여 Ninja를 설치하고 검증합니다.\n# Ninja는 핵심 빌드 도구이므로 세 번째 인자는 \"true\"입니다.\ninstall_and_verify_tool \"ninja\" \"ninja-build\" \"true\"\n...\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 개발자는 각 스크립트를 대상 OS에서 개별적으로 실행한 다음 도구의 가용성과 버전을 확인하여 구현을 검증할 수 있습니다.\n\n```bash\n# macOS에서:\nbash scripts/cpp_development_environment/macos/install_ninja.sh\n\n# Linux에서:\nbash scripts/cpp_development_environment/linux/install_ninja.sh\n\n# 두 플랫폼 중 하나에서 성공적으로 실행한 후, 다음을 실행합니다:\nwhich ninja\nninja --version\n```\n\n### 4.2. 예상 결과\n\n- 스크립트 실행은 성공을 나타내는 로그 메시지와 함께 오류 코드 없이 완료되어야 합니다.\n- `which ninja` 명령어는 `ninja` 실행 파일의 경로(예: Apple Silicon의 경우 `/opt/homebrew/bin/ninja` 또는 Linux의 경우 `/usr/bin/ninja`)를 출력해야 합니다.\n- `ninja --version` 명령어는 설치된 Ninja의 버전 번호(예: `1.11.1`)를 표준 출력으로 출력해야 합니다.","중요한 의존성으로 Ninja를 설치하고 검증하는 macOS 및 Linux용 스크립트",[621,623,625,626],{"_24":622,"_83":39,"_84":192,"_85":61},"'ninja' formula에 `install_and_verify_tool` 헬퍼를 사용하는 macOS 스크립트",{"_24":624,"_83":39,"_84":192,"_85":88},"'ninja-build' 패키지에 `install_and_verify_tool` 헬퍼를 사용하는 Linux 스크립트",{"_24":611,"_83":39,"_84":192,"_85":91},{"_24":627,"_83":39,"_84":192,"_85":94},"설치 로직에서 Ninja를 중요 도구로 지정","Ninja 빌드 시스템의 자동화된 설치",{"_22":630,"_24":631,"_75":632,"_77":633,"_79":634,"_51":641,"_42":99},"task-1751002035859","크로스 플랫폼 Git 설치","# 작업: 크로스 플랫폼 Git 설치\n\n> **에픽**: 개발자 생산성 도구 설치\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: Git 버전 관리 시스템의 자동화된 설치.\n- **근거**: Git은 최신 소프트웨어 개발의 기본 도구로서 필수적인 버전 관리 기능을 제공합니다. Git 설치는 프로젝트의 소스 코드를 관리하고, 팀원과 협업하며, CI/CD 파이프라인(GitHub Actions)과 통합하기 위한 전제 조건입니다. 이 작업은 지원되는 모든 플랫폼에서 일관되고 안정적인 Git 설치를 보장합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: Git을 핵심 의존성으로 설치하고 검증하는 macOS 및 Linux용 스크립트.\n- **명세**:\n - 다음과 같은 유효 호출로 헬퍼 함수를 호출하는 macOS 스크립트: `install_and_verify_tool \"git\" \"git\" \"formula\" \"true\"`.\n - 다음과 같은 유효 호출로 헬퍼 함수를 호출하는 Linux 스크립트: `install_and_verify_tool \"git\" \"git\" \"true\"`.\n - 두 스크립트 모두 Git을 핵심 의존성으로 취급해야 하며, Git 설치가 실패할 경우 기본 설정 프로세스가 실패하도록 보장해야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./scripts/cpp_development_environment/\n# ├── linux/\n# │ └── install_git.sh <-- 신규\n# └── macos/\n# └── install_git.sh <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 주 오케스트레이터(`setup.sh`)가 이 작업에서 생성된 플랫폼별 스크립트에 Git 설치를 위임하는 방법을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n Orchestrator[\"setup.sh: 설치 단계 실행\"] --> DetectOS{\"운영 체제 감지\"};\n DetectOS -->|macOS| RunMacOSScript[\"macos/install_git.sh
소싱 및 실행\"];\n DetectOS -->|Linux| RunLinuxScript[\"linux/install_git.sh
소싱 및 실행\"];\n RunMacOSScript --> Continue[\"오케스트레이션 계속\"];\n RunLinuxScript --> Continue[\"오케스트레이션 계속\"];\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 개략적인 체크리스트이며, 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] 'git'을 위해 `install_and_verify_tool` 헬퍼를 사용하는 macOS 스크립트.\n- [ ] 'git'을 위해 `install_and_verify_tool` 헬퍼를 사용하는 Linux 스크립트.\n- [ ] 설치 로직에서 Git을 핵심 도구로 지정.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 스크립트 기반 오케스트레이션\n- **관련 주요 구성 요소**:\n - **`macos/scripts`**: 이 디렉터리에는 macOS 전용 설치 로직이 포함됩니다. 새로운 `install_git.sh` 스크립트는 여기에 위치하며 플랫폼별 헬퍼 함수를 통해 Homebrew를 활용합니다.\n - **`linux/scripts`**: 이 디렉터리에는 Linux 전용 설치 로직이 포함됩니다. 새로운 `install_git.sh` 스크립트는 여기에 위치하며 플랫폼별 헬퍼 함수를 통해 `apt`를 활용합니다.\n - **`setup.sh` (오케스트레이터)**: 이 작업에서 수정되지는 않지만, 이 구성 요소는 생성되는 스크립트의 소비자입니다. 전체 환경 설정의 일부로 최종적으로 이 스크립트들을 소싱하고 실행하게 됩니다.\n - **플랫폼별 유틸리티 스크립트 (`common_utils.sh`)**: 각 플랫폼 디렉터리(`macos/`, `linux/`)에는 `install_and_verify_tool`과 같은 헬퍼 함수를 제공하는 유틸리티 스크립트가 포함되어 있습니다. 새로운 설치 스크립트는 이 유틸리티를 소싱하여 멱등성을 유지하며 작업을 수행합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `scripts/cpp_development_environment/macos/install_git.sh`\n- `scripts/cpp_development_environment/linux/install_git.sh`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을', '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 'git'을 위해 `install_and_verify_tool` 헬퍼를 사용하는 macOS 스크립트\n\n#### 1. macOS Git 설치 스크립트 생성\n\n이 작업은 macOS에 Git을 설치하는 새로운 셸 스크립트를 생성하는 것을 포함합니다. 스크립트는 셔뱅(shebang)으로 시작해야 하며 엄격한 오류 처리(`set -euo pipefail`)를 설정해야 합니다. 플랫폼별 `common_utils.sh`를 소싱하여 `install_and_verify_tool` 헬퍼 함수에 접근합니다. 스크립트의 핵심은 이 함수를 호출하는 부분으로, 프로그램 및 패키지 이름으로 `git`을, Homebrew 설치 유형으로 `formula`를, 그리고 핵심 의존성으로 지정하기 위해 `true`를 전달합니다. 이 중요도 플래그는 필수적입니다. 이 기본 도구를 설치할 수 없는 경우 기본 `setup.sh` 오케스트레이터가 중단되도록 보장합니다.\n\n**파일**: `scripts/cpp_development_environment/macos/install_git.sh`\n\n```bash\n#!/bin/bash\n\nset -euo pipefail\n\n# 현재 실행 중인 스크립트의 디렉터리 가져오기\nINSTALL_GIT_MACOS_DIRECTORY=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\n# 공통 유틸리티 소싱\n# shellcheck source=./common_utils.sh\nsource \"$INSTALL_GIT_MACOS_DIRECTORY/common_utils.sh\"\n\n# --- 스크립트 주요 로직 ---\nlog_info \"🔧 Git 설치 중 (macOS)...\"\n\n# 프로그램 및 패키지 이름 정의\nGIT_PROGRAM_NAME=\"git\"\nGIT_PACKAGE_NAME=\"git\"\n\n# 공유 헬퍼 함수를 사용하여 Git 설치 및 검증.\n# Git은 핵심 개발 도구이므로 네 번째 인수는 \"true\"입니다.\ninstall_and_verify_tool \"$GIT_PROGRAM_NAME\" \"$GIT_PACKAGE_NAME\" \"formula\" \"true\"\n\nlog_info \"Git 설치 스크립트가 성공적으로 완료되었습니다.\"\n```\n\n---\n\n### 단계 2: 'git'을 위해 `install_and_verify_tool` 헬퍼를 사용하는 Linux 스크립트\n\n#### 1. Linux Git 설치 스크립트 생성\n\n이 작업은 Linux용 설치 스크립트를 생성하는 것을 포함합니다. macOS 버전과 유사하게, 엄격한 오류 처리를 포함한 bash 스크립트가 될 것입니다. Linux 전용 `common_utils.sh`를 소싱합니다. 스크립트는 먼저 `update_apt_cache` 헬퍼를 호출하여 로컬 패키지 인덱스가 최신 상태인지 확인하는데, 이는 `apt`로 패키지를 설치하기 전의 모범 사례입니다. 그 다음 `install_and_verify_tool` 함수를 호출합니다. Linux의 경우 이 함수는 프로그램 이름, 패키지 이름, 그리고 중요도 플래그(`true`)를 필요로 합니다. Git을 핵심으로 표시하면 설치 실패 시 전체 설정 프로세스가 중단되도록 보장합니다.\n\n**파일**: `scripts/cpp_development_environment/linux/install_git.sh`\n\n```bash\n#!/bin/bash\n\nset -euo pipefail\n\n# 현재 실행 중인 스크립트의 디렉터리 가져오기\nINSTALL_GIT_LINUX_DIRECTORY=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\n\n# 공통 유틸리티 소싱\n# shellcheck source=./common_utils.sh\nsource \"$INSTALL_GIT_LINUX_DIRECTORY/common_utils.sh\"\n\n# --- 스크립트 주요 로직 ---\nlog_info \"🔧 Git 설치 중 (Linux)...\"\n\n# 패키지를 설치하기 전에 apt 캐시를 업데이트합니다.\nif ! update_apt_cache; then\n log_error \"apt 캐시 업데이트에 실패했습니다. Git 설치를 중단합니다.\"\n exit 1\nfi\n\n# 프로그램 및 패키지 이름 정의\nGIT_PROGRAM_NAME=\"git\"\nGIT_PACKAGE_NAME=\"git\"\n\n# 공유 헬퍼 함수를 사용하여 Git 설치 및 검증.\n# Git은 개발에 필수적이므로 세 번째 인수는 \"true\"입니다.\ninstall_and_verify_tool \"$GIT_PROGRAM_NAME\" \"$GIT_PACKAGE_NAME\" \"true\"\n\nlog_info \"Git 설치 스크립트가 성공적으로 완료되었습니다.\"\n```\n\n---\n\n### 단계 3: 설치 로직에서 Git을 핵심 도구로 지정\n\n이 인수 조건은 단계 1과 단계 2의 구현으로 충족됩니다. macOS와 Linux 스크립트 모두에서 `install_and_verify_tool` 함수 호출의 마지막 불리언 인수(`\"true\"`)가 바로 이 목적을 수행합니다. 이는 헬퍼 함수에 Git이 개발 환경의 필수 구성 요소임을 알립니다. 헬퍼 함수의 구현(별도의 작업에서 정의됨)은 설치 실패 시 0이 아닌 상태 코드로 스크립트를 종료시켜 주 `setup.sh` 오케스트레이션을 중단함으로써 이 플래그를 처리할 것으로 예상됩니다. 이 단계를 위해 추가 코드는 필요하지 않습니다.\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n이 스크립트들의 올바른 구현을 검증하려면, 각각의 대상 운영 체제에서 개별적으로 실행하십시오.\n\n**macOS에서:**\n\n```bash\n# 1. 스크립트 디렉터리로 이동\ncd scripts/cpp_development_environment/macos\n\n# 2. 스크립트를 실행 가능하게 만듦\nchmod +x install_git.sh\n\n# 3. 스크립트 실행 (common_utils.sh가 있다고 가정)\n./install_git.sh\n\n# 4. 'git' 명령어가 PATH에 있는지 확인\ncommand -v git\n```\n\n**Linux에서:**\n\n```bash\n# 1. 스크립트 디렉터리로 이동\ncd scripts/cpp_development_environment/linux\n\n# 2. 스크립트를 실행 가능하게 만듦\nchmod +x install_git.sh\n\n# 3. 스크립트 실행 (common_utils.sh가 있다고 가정)\n./install_git.sh\n\n# 4. 'git' 명령어가 PATH에 있는지 확인\ncommand -v git\n```\n\n### 4.2. 예상 결과\n\n- 각 스크립트는 오류 없이 실행되고 상태 코드 `0`으로 종료되어야 합니다.\n- 표준 출력에는 `🔧 Git 설치 중...` 및 `Git 설치 스크립트가 성공적으로 완료되었습니다.`와 같은 정보 로그가 표시되어야 합니다.\n- `command -v git` 명령어는 Git 실행 파일의 절대 경로(예: macOS의 `/usr/local/bin/git` 또는 Linux의 `/usr/bin/git`)를 출력해야 합니다.","중요한 의존성으로 Git을 설치하고 검증하는 macOS 및 Linux용 스크립트",[635,637,639],{"_24":636,"_83":39,"_84":212,"_85":61},"'git'에 `install_and_verify_tool` 헬퍼를 사용하는 macOS 스크립트",{"_24":638,"_83":39,"_84":212,"_85":88},"'git'에 `install_and_verify_tool` 헬퍼를 사용하는 Linux 스크립트",{"_24":640,"_83":39,"_84":212,"_85":91},"설치 로직에서 Git을 중요 도구로 지정","Git 버전 관리 시스템의 자동화된 설치",{"_22":643,"_24":644,"_75":645,"_77":646,"_79":647,"_51":656,"_42":99},"task-1751002092139","크로스 플랫폼 GitHub CLI 설치","# 작업: 크로스플랫폼 GitHub CLI 설치\n\n> **에픽**: 개발자 생산성 도구 설치\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: GitHub 커맨드라인 인터페이스의 자동화된 설치.\n- **근거**: GitHub CLI (`gh`)는 GitHub와 통합된 현대적인 개발 워크플로우의 기본 도구입니다. 설치를 자동화하면 환경 설정 프로세스를 간소화하고, 수동 구성 오류를 줄이며, 단일 명령으로 포괄적인 개발자 환경을 설정한다는 프로젝트의 핵심 목표를 직접적으로 지원합니다. 이를 통해 개발자들은 커맨드 라인에서 리포지토리 관리 및 CI/CD 도구에 즉시 접근할 수 있습니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: macOS 및 Linux용 'gh' 도구 설치 스크립트. Linux에서는 사용자 정의 리포지토리를 처리해야 함.\n- **사양**:\n - `scripts/cpp_development_environment/macos/install_github_cli.sh` 생성.\n - `scripts/cpp_development_environment/linux/install_github_cli.sh` 생성.\n - 두 스크립트는 모두 멱등성을 가져야 합니다. 즉, 여러 번 실행해도 최초의 성공적인 설치 이후에는 오류를 발생시키거나 시스템 상태를 변경하지 않아야 합니다.\n - Linux 스크립트는 설치를 시도하기 전에 공식 GitHub APT 리포지토리와 해당 GPG 키를 정확하게 추가해야 합니다.\n - 두 스크립트 모두 공통 유틸리티의 `install_and_verify_tool` 헬퍼 함수를 활용하여 일관된 설치 및 검증 로직을 보장해야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./scripts/cpp_development_environment/\n# ├── linux/\n# │ └── install_github_cli.sh <-- 신규\n# └── macos/\n# └── install_github_cli.sh <-- 신규\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph Z[\"setup.sh 오케스트레이션\"]\n A[\"main()\"] --> B{OS 감지};\n B -- \"macOS\" --> C[\"macos/install_github_cli.sh 소싱\"];\n B -- \"Linux\" --> D[\"linux/install_github_cli.sh 소싱\"];\n end\n subgraph X[\"linux/install_github_cli.sh\"]\n D --> E{\"is_program_installed \"gh\"\"}\n E -- 아니요 --> F[GitHub APT 리포지토리 추가]\n F --> G[APT 캐시 업데이트]\n G --> H[\"install_and_verify_tool gh\"]\n E -- 예 --> I[\"이미 설치됨 로그 기록\"]\n end\n subgraph V[\"macos/install_github_cli.sh\"]\n C --> J[\"install_and_verify_tool gh\"]\n end\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] 'gh'용 `install_and_verify_tool` 헬퍼를 사용하는 macOS 스크립트.\n- [ ] 공식 GitHub CLI APT 리포지토리를 추가하는 기능이 있는 Linux 스크립트.\n- [ ] Linux 스크립트 내 APT 캐시 업데이트 및 설치 단계.\n- [ ] `gh`가 이미 존재할 경우 설치를 건너뛰는 멱등성 검사.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 스크립트 기반 오케스트레이션\n- **관련된 주요 구성 요소**:\n - `setup.sh`: 호스트 운영 체제를 파악한 후 플랫폼별 `install_github_cli.sh` 스크립트를 호출할 메인 오케스트레이터입니다. 이 작업은 `setup.sh`가 호출할 모듈식 구성 요소를 제공합니다.\n - `macos/scripts`: 이 디렉토리는 macOS 전용 설치 스크립트를 포함합니다. 스크립트는 `common/macos/utils.sh` 헬퍼 함수를 통해 Homebrew를 활용합니다.\n - `linux/scripts`: 이 디렉토리는 Linux 전용 설치 스크립트를 포함합니다. 스크립트는 `apt`를 사용하며, 사용자 정의 GitHub CLI 리포지토리에 대한 특별한 처리가 필요하며, 이는 `common/linux/utils.sh`를 통해 관리됩니다.\n - `common/scripts`: OS에 구애받지 않는 유틸리티로, `log_info`, `is_program_installed`, 그리고 핵심 `install_and_verify_tool`과 같은 공유 함수를 제공합니다. 이는 일관성을 보장하고 코드 중복을 줄이기 위해 이 새로운 스크립트들의 중요한 의존성입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `scripts/cpp_development_environment/macos/install_github_cli.sh`\n- `scripts/cpp_development_environment/linux/install_github_cli.sh`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 'gh'용 `install_and_verify_tool` 헬퍼를 사용하는 macOS 스크립트\n\n#### 1. macOS 설치 스크립트 구현\n\n이 작업은 GitHub CLI 설치를 처리하기 위해 `install_and_verify_tool` 헬퍼 함수만을 사용하는 스크립트를 만드는 것을 포함합니다. 이 접근 방식은 패키지 관리 로직을 재사용 가능한 유틸리티 함수로 추상화하는 우리의 아키텍처 원칙과 일치합니다. 스크립트는 프로그램 및 패키지 이름을 정의한 다음 헬퍼를 호출합니다. 이 핵심 생산성 도구를 설치할 수 없는 경우 설정 프로세스가 실패하도록 하여 환경 일관성을 유지하기 위해 설치는 중요(`true`)로 표시됩니다.\n\n**File**: `scripts/cpp_development_environment/macos/install_github_cli.sh`\n\n```shell\n#!/bin/bash\n\nset -euo pipefail\n\n# 현재 실행 중인 스크립트의 디렉토리를 가져옵니다\nINSTALL_GITHUB_CLI_MACOS_DIRECTORY=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\n# 부모 디렉토리의 common/macos 폴더에서 공통 유틸리티를 소싱합니다\n# shellcheck source=../common/macos/utils.sh\nsource \"$INSTALL_GITHUB_CLI_MACOS_DIRECTORY/../common/macos/utils.sh\"\n\n# --- 스크립트 메인 로직 ---\nlog_info \"🚀 GitHub CLI 설치 중 (macOS)...\"\n\n# 프로그램 및 패키지 이름 정의\nGH_PROGRAM_NAME=\"gh\"\nGH_PACKAGE_NAME=\"gh\"\n\n# 공유 헬퍼 함수를 사용하여 GitHub CLI를 설치하고 검증합니다.\n# 이 도구는 개발 환경에 필수적인 것으로 간주됩니다.\ninstall_and_verify_tool \"$GH_PROGRAM_NAME\" \"$GH_PACKAGE_NAME\" \"formula\" \"true\"\n\nlog_info \"✅ GitHub CLI 설치 스크립트가 성공적으로 완료되었습니다.\"\n```\n\n---\n\n### 단계 2: 공식 GitHub CLI APT 리포지토리를 추가하는 기능이 있는 Linux 스크립트\n\n#### 1. 리포지토리 추가 함수 생성\n\n이 작업은 GitHub CLI의 사용자 정의 APT 리포지토리를 추가하는 데 필요한 특정 명령을 캡슐화하기 위해 전용 함수 `add_github_cli_repository`를 생성합니다. `gh`는 표준 Debian/Ubuntu 리포지토리에서 사용할 수 없기 때문에 이러한 단계는 필수적입니다. 이 로직을 함수로 캡슐화하면 메인 스크립트의 가독성이 향상되고 복잡하고 권한이 필요한 작업을 격리할 수 있습니다. 이 함수는 공식 GitHub CLI 문서에 명시된 대로 GPG 키를 다운로드하고 `sources.list.d` 항목을 생성합니다.\n\n**File**: `scripts/cpp_development_environment/linux/install_github_cli.sh`\n\n```shell\n#!/bin/bash\n\nset -euo pipefail\n...\n# --- 헬퍼 함수 ---\n\n# 시스템에 공식 GitHub CLI apt 리포지토리를 추가합니다.\n# 이 함수는 sudo 권한이 필요합니다.\nadd_github_cli_repository() {\n log_info \"📦 GitHub CLI apt 리포지토리를 추가하는 중...\"\n\n # 명확한 오류 메시지를 제공하기 위해 초기에 sudo 권한을 확인합니다.\n if ! sudo -v; then\n log_error \"apt 리포지토리를 추가하려면 sudo 권한이 필요합니다. sudo로 실행하거나 root로 실행해 주세요.\"\n exit 1\n fi\n\n curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg\n sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg\n echo \"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main\" | sudo tee /etc/apt/sources.list.d/github-cli.list >/dev/null\n\n log_info \"✅ GitHub CLI apt 리포지토리가 성공적으로 추가되었습니다.\"\n}\n...\n```\n\n---\n\n### 단계 3: Linux 스크립트 내 APT 캐시 업데이트 및 설치 단계\n\n#### 1. Linux 설치 로직 오케스트레이션\n\n이 작업은 Linux 스크립트의 주요 실행 흐름을 정의합니다. 사용자 정의 리포지토리를 추가한 후에는 패키지 관리자가 `gh` 패키지를 인식할 수 있도록 `apt` 캐시를 업데이트하는 것이 중요합니다. 스크립트는 먼저 전제 조건으로 `curl`을 설치한 다음, `add_github_cli_repository`를 호출하고, 그 다음 명시적으로 `update_apt_cache`를 호출합니다. 이러한 준비 단계가 성공적으로 완료된 후에야 `install_and_verify_tool`을 호출하여 `gh`를 설치합니다. 이 순서는 모든 의존성과 시스템 상태가 올바르게 관리되도록 보장합니다.\n\n**File**: `scripts/cpp_development_environment/linux/install_github_cli.sh`\n\n```shell\n...\n# --- 스크립트 메인 로직 ---\nlog_info \"🚀 GitHub CLI 설치 중 (Linux)...\"\n\n# gh가 이미 설치되고 검증되었다면 스크립트는 즉시 종료됩니다.\nif is_program_installed \"gh\" && verify_command \"gh\"; then\n log_info \"✅ GitHub CLI가 이미 설치되고 검증되었습니다.\"\n exit 0\nfi\n\n# 1. 전제 조건 설치 (curl)\n# curl은 리포지토리 추가에 필수적입니다.\ninstall_and_verify_tool \"curl\" \"curl\" \"true\"\n\n# 2. GitHub CLI용 사용자 정의 리포지토리 추가\nadd_github_cli_repository\n\n# 3. 새 리포지토리를 인식하도록 apt 캐시 업데이트\nlog_info \"새 리포지토리를 추가한 후 apt 캐시를 업데이트하는 중...\"\nif ! update_apt_cache; then\n log_error \"GitHub CLI 리포지토리를 추가한 후 apt 캐시 업데이트에 실패했습니다. 중단합니다.\"\n exit 1\nfi\n\n# 4. 헬퍼 함수를 사용하여 GitHub CLI 설치\n# gh는 이 개발 환경에 필수적인 도구로 간주됩니다.\ninstall_and_verify_tool \"gh\" \"gh\" \"true\"\n\nlog_info \"✅ GitHub CLI 설치 스크립트가 성공적으로 완료되었습니다.\"\n```\n\n---\n\n### 단계 4: `gh`가 이미 존재할 경우 설치를 건너뛰는 멱등성 검사\n\n#### 1. Linux 스크립트에 명시적 멱등성 검사 구현\n\n이 작업은 Linux 스크립트의 메인 로직 맨 처음에 `gh`가 이미 설치되어 `PATH`에서 사용 가능한지 확인하는 검사를 추가합니다. 이것은 멱등성 요구 사항의 중요한 구현입니다. 도구가 존재할 경우 조기 종료함으로써, 스크립트는 중복되고 잠재적으로 방해가 될 수 있는 작업(리포지토리 재추가 또는 패키지 재설치 등)을 피하며, 메인 `setup.sh` 오케스트레이터의 후속 실행을 더 빠르고 안전하게 만듭니다.\n\n**File**: `scripts/cpp_development_environment/linux/install_github_cli.sh`\n\n```shell\n...\n# --- 스크립트 메인 로직 ---\nlog_info \"🚀 GitHub CLI 설치 중 (Linux)...\"\n\n# gh가 이미 설치되고 검증되었다면 스크립트는 즉시 종료됩니다.\nif is_program_installed \"gh\" && verify_command \"gh\"; then\n log_info \"✅ GitHub CLI가 이미 설치되고 검증되었습니다.\"\n exit 0\nfi\n\n# 1. 전제 조건 설치 (curl)\n...\n```\n\n#### 2. macOS 스크립트에서 암시적 멱등성 확인\n\nmacOS 스크립트는 Homebrew의 기본 동작에 의존하는 `install_and_verify_tool` 헬퍼 함수를 통해 암시적으로 멱등성을 달성합니다. Homebrew의 `install` 명령은 formula가 이미 존재하고 최신 버전인 경우 다시 설치하지 않습니다. 따라서 기본 도구가 이미 필요한 멱등성을 제공하므로 macOS 스크립트 자체에는 명시적인 `if` 블록이 필요하지 않습니다. 이 작업은 스크립트가 이 아키텍처적 특징에 의존함을 확인하기 위한 것입니다.\n\n**File**: `scripts/cpp_development_environment/macos/install_github_cli.sh`\n\n```shell\n...\n# --- 스크립트 메인 로직 ---\nlog_info \"🚀 GitHub CLI 설치 중 (macOS)...\"\n\n# 프로그램 및 패키지 이름 정의\nGH_PROGRAM_NAME=\"gh\"\nGH_PACKAGE_NAME=\"gh\"\n\n# 공유 헬퍼 함수를 사용하여 GitHub CLI를 설치하고 검증합니다.\n# 헬퍼는 Homebrew가 제공하는 멱등성 검사를 추상화합니다.\ninstall_and_verify_tool \"$GH_PROGRAM_NAME\" \"$GH_PACKAGE_NAME\" \"formula\" \"true\"\n...\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n1. 코어 스크립트 디렉토리로 이동합니다: `cd scripts/cpp_development_environment`.\n2. 새 스크립트가 실행 가능한지 확인합니다:\n\n ```bash\n chmod +x macos/install_github_cli.sh\n chmod +x linux/install_github_cli.sh\n ```\n\n3. 대상 머신(macOS 또는 Linux)에서 메인 설정 스크립트를 실행합니다:\n\n ```bash\n bash setup.sh\n ```\n\n4. 스크립트가 완료된 후, 검증 스크립트를 실행합니다:\n\n ```bash\n bash verify.sh\n ```\n\n5. `gh` 명령이 사용 가능하고 작동하는지 수동으로 확인합니다:\n\n ```bash\n gh --version\n ```\n\n### 4.2. 예상 결과\n\n- `setup.sh` 스크립트가 실행되고 \"GitHub CLI\" 설치와 관련된 로그를 표시하며 성공 메시지와 함께 종료되어야 합니다.\n- `verify.sh` 스크립트가 실행되고 종료 코드 0으로 종료되어야 하며, 이는 `gh` 실행 파일이 시스템 `PATH`에서 발견되었음을 나타냅니다.\n- `gh --version`의 출력은 설치된 GitHub CLI 버전을 표시해야 합니다. 예:\n\n ```\n gh version 2.4.0 (2021-09-21)\n https://github.com/cli/cli/releases/tag/v2.4.0\n ```\n","'gh' 도구를 설치하는 macOS 및 Linux용 스크립트",[648,650,652,654],{"_24":649,"_83":39,"_84":230,"_85":61},"'gh'에 `install_and_verify_tool` 헬퍼를 사용하는 macOS 스크립트",{"_24":651,"_83":39,"_84":230,"_85":88},"공식 GitHub CLI APT 리포지토리를 추가하는 기능이 있는 Linux 스크립트",{"_24":653,"_83":39,"_84":230,"_85":91},"Linux 스크립트 내 APT 캐시 업데이트 및 설치 단계",{"_24":655,"_83":39,"_84":230,"_85":94},"`gh`가 이미 존재하는 경우 설치를 건너뛰는 멱등성 검사","GitHub 커맨드 라인 인터페이스의 자동화된 설치",{"_22":658,"_24":659,"_75":660,"_77":661,"_79":662,"_51":671,"_42":99},"task-1751002167995","크로스 플랫폼 Visual Studio Code 설치","# 작업: 크로스플랫폼 Visual Studio Code 설치\n\n> **에픽**: 개발자 생산성 도구 설치\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: Visual Studio Code 편집기의 자동화된 설치.\n- **근거**: 모든 개발자 머신에 일관되고 표준화된 통합 개발 환경(IDE)을 보장하여, 단일 명령으로 설정을 완료한다는 프로젝트의 핵심 목표에 부합하기 위함입니다. 이 자동화는 수동 설치 단계를 제거하고, 추후 VS Code 내에서 C++ 환경을 자동으로 구성하기 위한 기본 구성 요소를 제공합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: macOS 및 Linux용 VS Code 설치 스크립트. 시스템별 패키지 유형(cask, deb)을 처리해야 함.\n- **사양**:\n - `scripts/cpp_development_environment/macos/install_vscode.sh`: Homebrew를 사용하여 `visual-studio-code` cask를 설치하는 실행 가능한 셸 스크립트. 애플리케이션 번들과 `code` CLI 도구를 확인하여 설치를 검증해야 함.\n - `scripts/cpp_development_environment/linux/install_vscode.sh`: 공식 Microsoft APT 저장소를 추가하고, 필요한 의존성을 설치하며, `code` 패키지를 설치하는 실행 가능한 셸 스크립트. `code` CLI 도구가 시스템 `PATH`에서 사용 가능한지 검증해야 함.\n- **결과 파일 구조**\n\n```bash\n# ./scripts/cpp_development_environment/\n# ├── linux/\n# │ └── install_vscode.sh <-- 신규\n# └── macos/\n# └── install_vscode.sh <-- 신규\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n Setup[\"setup.sh\"] --> DetectOS{\"OS 감지\"};\n DetectOS --> |macOS| CallMacOSInstall[\"macos/install_vscode.sh 호출\"];\n DetectOS --> |Linux| CallLinuxInstall[\"linux/install_vscode.sh 호출\"];\n CallMacOSInstall --> BrewInstall[\"Homebrew를 사용하여 'visual-studio-code' cask 설치\"];\n CallLinuxInstall --> AddRepo[\"Microsoft APT 저장소 추가\"];\n AddRepo --> AptInstall[\"APT를 사용하여 'code' 패키지 설치\"];\n BrewInstall --> VerifyMacOS[\"Verifies .app 번들 및 'code' CLI 확인\"];\n AptInstall --> VerifyLinux[\"'code' CLI 확인\"];\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] `install_with_brew`를 사용하여 'visual-studio-code' cask를 설치하는 macOS 스크립트.\n- [ ] Microsoft APT 저장소를 추가하는 함수가 포함된 Linux 스크립트.\n- [ ] Linux에서 `wget` 및 `gpg`와 같은 의존성 설치.\n- [ ] 애플리케이션 번들과 `code` CLI 명령 모두 검증.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 스크립트 기반 오케스트레이션\n- **주요 관련 구성 요소**:\n - **`setup.sh`**: 메인 오케스트레이터. 호스트 운영 체제를 감지한 후 플랫폼별 `install_vscode.sh` 스크립트를 호출합니다.\n - **`macos/scripts`**: macOS별 설치 로직을 담고 있는 디렉토리. 이 작업은 이 구성 요소에 `install_vscode.sh`를 추가합니다.\n - **`linux/scripts`**: Linux별 설치 로직을 담고 있는 디렉토리. 이 작업은 이 구성 요소에 `install_vscode.sh`를 추가합니다.\n - **`Homebrew`**: macOS용 패키지 관리자. macOS 스크립트는 이를 활용하여 VS Code cask를 설치합니다.\n - **`apt`**: Debian 기반 Linux 배포판용 패키지 관리자. Linux 스크립트는 적절한 저장소를 구성한 후 이를 사용하여 VS Code를 설치합니다.\n\n### 2.2. 영향을 받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `scripts/cpp_development_environment/macos/install_vscode.sh`\n- `scripts/cpp_development_environment/linux/install_vscode.sh`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을', '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `install_with_brew`를 사용하여 'visual-studio-code' cask를 설치하는 macOS 스크립트\n\n#### 1. VS Code Cask 설치 구현\n\n이 액션은 macOS 스크립트의 주요 로직을 생성합니다. 기존 유틸리티 함수인 `install_with_brew`를 활용하는 `install_and_verify_vscode` 함수를 정의합니다. `install_with_brew`가 패키지가 이미 설치되었는지 확인하는 작업을 처리하므로 이 추상화는 멱등성을 보장합니다. VS Code는 macOS에서 GUI 애플리케이션이므로 패키지 유형은 \"cask\"로 지정됩니다.\n\n**파일**: `scripts/cpp_development_environment/macos/install_vscode.sh`\n\n```shell\n#!/bin/bash\n\nset -euo pipefail\n\n# 현재 실행 중인 스크립트의 디렉토리 가져오기\nINSTALL_VSCODE_MACOS_DIRECTORY=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\n# 공통 유틸리티 소스 가져오기\n# shellcheck source=./common_utils.sh\nsource \"$INSTALL_VSCODE_MACOS_DIRECTORY/common_utils.sh\"\n\n# --- 상수 ---\nVSCODE_PACKAGE_NAME=\"visual-studio-code\"\n...\n\n# --- 헬퍼 함수 ---\n\n# Visual Studio Code를 설치하고 검증합니다.\ninstall_and_verify_vscode() {\n # install_with_brew가 cask가 이미 설치되었는지 확인하는 작업을 처리합니다.\n if ! install_with_brew \"$VSCODE_PACKAGE_NAME\" \"\" \"cask\"; then\n log_error \"❌ Homebrew를 통한 Visual Studio Code 설치에 실패했습니다.\"\n # VS Code는 중요하지 않은 것으로 간주되므로 종료하지 않습니다.\n return 1\n fi\n...\n}\n\n# --- 스크립트 메인 로직 ---\nlog_info \"🖥️ Visual Studio Code 설치 중 (macOS)...\"\ninstall_and_verify_vscode\nlog_info \"Visual Studio Code 설치 스크립트가 성공적으로 완료되었습니다.\"\n```\n\n---\n\n### 단계 2: Microsoft APT 저장소를 추가하는 함수가 포함된 Linux 스크립트\n\n#### 1. APT 저장소 구성 구현\n\n이 액션은 Linux 스크립트에 `add_vscode_repository` 함수를 구현합니다. 저장소 관리를 자동화하는 것은 기본 시스템 소스에서 사용할 수 없는 소프트웨어를 설치하는 데 중요합니다. 이 함수는 Microsoft의 GPG 키를 다운로드하여 패키지 진위성을 확인한 다음, 공식 VS Code 저장소를 시스템의 APT 소스 목록에 추가하여 `apt`가 `code` 패키지를 찾고 설치할 수 있도록 보장합니다.\n\n**파일**: `scripts/cpp_development_environment/linux/install_vscode.sh`\n\n```shell\n...\n# 공식 Microsoft VS Code apt 저장소를 시스템에 추가합니다.\n# 이 함수는 sudo 권한이 필요합니다.\nadd_vscode_repository() {\n log_info \"📦 Microsoft VS Code apt 저장소 추가 중...\"\n\n # sudo 권한을 미리 확인합니다\n if ! sudo -v; then\n log_error \"apt 저장소를 추가하려면 Sudo 권한이 필요합니다.\"\n exit 1\n fi\n\n # Microsoft GPG 키를 다운로드하고, dearmor 처리하여 keyrings 디렉토리에 저장합니다\n wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor | sudo tee /etc/apt/keyrings/packages.microsoft.gpg >/dev/null\n\n # VS Code 저장소를 소스 목록에 추가합니다\n echo \"deb [arch=amd64,arm64,armhf signed-by=/etc/apt/keyrings/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main\" | sudo tee /etc/apt/sources.list.d/vscode.list >/dev/null\n\n log_info \"✅ Microsoft VS Code apt 저장소가 성공적으로 추가되었습니다.\"\n}\n...\n```\n\n---\n\n### 단계 3: Linux에서 `wget` 및 `gpg`와 같은 의존성 설치\n\n#### 1. 전제 조건 설치 구현\n\n이 액션은 `install_dependencies` 함수를 구현합니다. 새로운 APT 저장소를 추가하기 전에, 스크립트는 필요한 도구들(GPG 키 다운로드를 위한 `wget`, dearmor 처리를 위한 `gpg`)이 시스템에 있는지 확인해야 합니다. 이 함수는 공통 `install_packages` 유틸리티를 호출하여 이러한 의존성들이 멱등성 있게 설치되도록 보장합니다.\n\n**파일**: `scripts/cpp_development_environment/linux/install_vscode.sh`\n\n```shell\n...\n# --- 헬퍼 함수 ---\n\n# VS Code 저장소를 추가하는 데 필요한 전제 조건 패키지를 설치합니다.\ninstall_dependencies() {\n log_info \"의존성 설치 중: wget, gpg, apt-transport-https\"\n install_packages \"wget\" \"gpg\" \"apt-transport-https\"\n}\n...\n\n# --- 스크립트 메인 로직 ---\n...\n# 1. 저장소 추가를 위한 전제 조건을 설치합니다.\ninstall_dependencies\n# 2. VS Code용 커스텀 저장소를 추가합니다.\nadd_vscode_repository\n# 3. 새 저장소를 인식하도록 apt 캐시를 업데이트합니다.\nlog_info \"새 저장소 추가 후 apt 캐시 업데이트 중...\"\nupdate_apt_cache\n# 4. Visual Studio Code 자체를 설치합니다.\ninstall_and_verify_tool \"code\" \"code\" \"false\"\n...\n```\n\n---\n\n### 단계 4: 애플리케이션 번들과 `code` CLI 명령 모두 검증\n\n#### 1. macOS에서 검증 로직 구현\n\n이 액션은 macOS 스크립트의 `install_and_verify_vscode` 함수에 검증 로직을 추가합니다. 성공적인 설치는 두 가지 확인을 통해 검증됩니다. 첫째, `/Applications/Visual Studio Code.app`에 애플리케이션 번들이 존재하는지 확인합니다. 둘째, `is_program_installed` 유틸리티를 사용하여 `code` CLI 명령이 `PATH`에서 사용 가능한지 확인하고, 그렇지 않은 경우 사용자에게 안내를 제공합니다.\n\n**파일**: `scripts/cpp_development_environment/macos/install_vscode.sh`\n\n```shell\n...\n# --- 상수 ---\nVSCODE_PROGRAM_NAME=\"code\"\nVSCODE_APP_PATH=\"/Applications/Visual Studio Code.app\"\n\n# --- 헬퍼 함수 ---\ninstall_and_verify_vscode() {\n ...\n log_info \"VS Code 설치 검증 중...\"\n\n # 주요 검증: 애플리케이션 번들을 확인합니다.\n if [ -d \"$VSCODE_APP_PATH\" ]; then\n log_info \"✅ '$VSCODE_APP_PATH'에서 Visual Studio Code 애플리케이션 번들을 찾았습니다.\"\n else\n log_warning \"⚠️ '$VSCODE_APP_PATH'에서 Visual Studio Code 애플리케이션 번들을 찾을 수 없습니다. 설치가 불완전할 수 있습니다.\"\n fi\n\n # 부가 검증: 'code' 커맨드 라인 도구를 확인합니다.\n if is_program_installed \"$VSCODE_PROGRAM_NAME\"; then\n log_info \"✅ '$VSCODE_PROGRAM_NAME' 명령을 사용할 수 있습니다.\"\n else\n log_warning \"⚠️ '$VSCODE_PROGRAM_NAME' 명령을 찾을 수 없습니다. 이는 새로 설치한 후 종종 예상되는 상황입니다.\"\n log_info \"👉 'code' 명령을 활성화하려면, VS Code를 열고 Cmd+Shift+P를 누른 다음, 'Shell Command: Install \\\\'code\\\\' command in PATH'를 입력하여 선택하세요.\"\n fi\n}\n...\n```\n\n#### 2. Linux에서 검증 로직 구현\n\n이 액션은 Linux 스크립트의 메인 로직 내에 있는 기존 `install_and_verify_tool` 유틸리티 함수에 의존합니다. 이 함수는 지정된 패키지(`code`)를 먼저 설치한 다음, 해당 명령(`code`)이 시스템의 `PATH`에서 사용 가능한지 즉시 확인하는 래퍼(wrapper)입니다. 이는 설치 후 검증 패턴을 캡슐화하여 메인 스크립트 흐름을 단순화합니다.\n\n**파일**: `scripts/cpp_development_environment/linux/install_vscode.sh`\n\n```shell\n...\n# --- 스크립트 메인 로직 ---\nlog_info \"🖥️ Visual Studio Code 설치 중 (Linux)...\"\n\n# VS Code가 이미 설치되고 검증되었다면 일찍 종료합니다.\nif is_program_installed \"code\" && verify_command \"code\"; then\n log_info \"✅ Visual Studio Code가 이미 설치되고 검증되었습니다.\"\n exit 0\nfi\n...\n# 4. Visual Studio Code 자체를 설치합니다.\n# 'false' 플래그는 이 설치가 메인 설정 성공에 중요하지 않음을 나타냅니다.\n# 이는 GUI 애플리케이션이 필요하지 않을 수 있는 CI와 같은 환경에서 유용합니다.\ninstall_and_verify_tool \"code\" \"code\" \"false\"\n\nlog_info \"Visual Studio Code 설치 스크립트가 완료되었습니다.\"\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n개발자는 플랫폼별 스크립트를 실행한 다음 애플리케이션과 CLI 도구의 존재 여부를 확인하여 올바른 구현을 검증할 수 있습니다.\n\n**macOS에서:**\n\n```bash\n# 1. 스크립트 디렉토리로 이동합니다\ncd scripts/cpp_development_environment/macos\n\n# 2. 설치 스크립트를 실행합니다\nbash install_vscode.sh\n\n# 3. 애플리케이션 번들이 존재하는지 확인합니다\nls -d \"/Applications/Visual Studio Code.app\"\n\n# 4. CLI 도구가 사용 가능한지 확인합니다 (스크립트 출력에 설명된 수동 단계가 필요할 수 있음)\ncommand -v code\n```\n\n**Linux에서:**\n\n```bash\n# 1. 스크립트 디렉토리로 이동합니다\ncd scripts/cpp_development_environment/linux\n\n# 2. 설치 스크립트를 실행합니다\nbash install_vscode.sh\n\n# 3. CLI 도구가 사용 가능한지 확인합니다\ncommand -v code\n```\n\n### 4.2. 예상 결과\n\n스크립트를 실행한 후, 콘솔 출력에는 설치 및 검증 단계를 나타내는 일련의 정보 로그가 표시되고 성공 메시지로 끝나야 합니다.\n\n**macOS 스크립트 출력 예시:**\n\n```\n🖥️ Visual Studio Code 설치 중 (macOS)...\n...\nVS Code 설치 검증 중...\n✅ '/Applications/Visual Studio Code.app'에서 Visual Studio Code 애플리케이션 번들을 찾았습니다.\n✅ 'code' 명령을 사용할 수 있습니다.\nVisual Studio Code 설치 스크립트가 성공적으로 완료되었습니다.\n```\n\n**Linux 스크립트 출력 예시:**\n\n```\n🖥️ Visual Studio Code 설치 중 (Linux)...\n의존성 설치 중: wget, gpg, apt-transport-https\n...\n📦 Microsoft VS Code apt 저장소 추가 중...\n✅ Microsoft VS Code apt 저장소가 성공적으로 추가되었습니다.\n새 저장소 추가 후 apt 캐시 업데이트 중...\n...\n[INSTALL] code 설치 중...\n[VERIFY] ✅ 'code' 명령이 PATH에 있습니다.\nVisual Studio Code 설치 스크립트가 완료되었습니다.\n```\n\n**수동 검증 명령 출력:**\n`ls -d` 및 `command -v` 명령은 애플리케이션/실행 파일의 경로를 출력하고 상태 코드 0으로 종료되어야 합니다.\n\n```\n# macOS\n/Applications/Visual Studio Code.app\n/usr/local/bin/code\n\n# Linux\n/usr/bin/code\n```\n","시스템별 패키지 유형(cask, deb)을 처리하며 VS Code를 설치하는 macOS 및 Linux용 스크립트",[663,665,667,669],{"_24":664,"_83":39,"_84":248,"_85":61},"`install_with_brew`를 사용하여 'visual-studio-code' cask를 설치하는 macOS 스크립트",{"_24":666,"_83":39,"_84":248,"_85":88},"Microsoft APT 리포지토리를 추가하는 기능이 있는 Linux 스크립트",{"_24":668,"_83":39,"_84":248,"_85":91},"Linux에서 `wget` 및 `gpg`와 같은 의존성 설치",{"_24":670,"_83":39,"_84":248,"_85":94},"애플리케이션 번들과 `code` CLI 명령어 모두 검증","Visual Studio Code 편집기의 자동화된 설치",{"_22":673,"_24":674,"_75":675,"_77":676,"_79":677,"_51":686,"_42":99},"task-1751002216395","크로스 플랫폼 Fira Code 글꼴 설치","# 과제: 크로스 플랫폼 Fira Code 글꼴 설치\n\n> **에픽**: 개발자 생산성 도구 설치\n\n## 1. 과제 정의\n\n### 1.1. 목표\n\n- **목표**: Fira Code 프로그래밍 글꼴의 자동 설치.\n- **근거**: 합자(ligature)를 지원하는 표준적이고 가독성 높은 프로그래밍 글꼴을 제공하여 개발자 경험을 향상시키기 위함입니다. 설치를 자동화하면 모든 개발자 환경에서 일관성을 보장하고, 단일 명령어 설정을 목표로 하는 프로젝트의 방향과 일치합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: macOS와 Linux 모두에 Fira Code 글꼴을 설치하는 스크립트.\n- **명세**:\n - 스크립트는 멱등성(idempotent)을 가져야 하며, 글꼴이 이미 존재할 경우 재설치를 방지해야 합니다.\n - macOS 스크립트는 공식 GitHub 릴리스에서 글꼴을 수동으로 다운로드하고, 압축을 풀고, `.ttf` 파일들을 사용자의 `~/Library/Fonts` 디렉토리로 복사합니다.\n - Linux 스크립트는 `apt` 패키지 관리자를 사용하여 `fonts-firacode` 패키지를 설치합니다.\n - macOS 스크립트는 성공적으로 완료되거나 실패했을 때 다운로드한 `.zip` 아카이브와 같은 모든 임시 파일을 정리해야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── scripts/\n# └── cpp_development_environment/\n# ├── linux/\n# │ └── install_coding_font.sh <-- 신규\n# └── macos/\n# └── install_coding_font.sh <-- 신규\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n Setup[\"setup.sh 오케스트레이터\"]\n DetectOS[\"OS 감지\"]\n IsMacOS{\"OS가 macOS인가?\"}\n IsLinux{\"OS가 Linux인가?\"}\n InstallMacOS[\"macos/install_coding_font.sh 실행\"]\n InstallLinux[\"linux/install_coding_font.sh 실행\"]\n\n Setup --> DetectOS\n DetectOS --> IsMacOS\n DetectOS --> IsLinux\n IsMacOS --\"예\"--> InstallMacOS\n IsLinux --\"예\"--> InstallLinux\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 과제를 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 개괄적인 체크리스트입니다. 각 항목에 대한 자세한 구현은 3장에 있습니다.\n\n- [ ] 글꼴 파일을 다운로드, 압축 해제하고 `~/Library/Fonts`로 복사하는 macOS 스크립트.\n- [ ] 임시 파일을 정리하기 위한 `trap` 정리 함수를 포함한 macOS 스크립트.\n- [ ] APT를 사용하여 `fonts-firacode` 패키지를 설치하는 Linux 스크립트.\n- [ ] 두 플랫폼 모두에서 재설치를 방지하기 위한 멱등성 검사.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 스크립트 기반 오케스트레이션\n- **관련된 주요 구성 요소**:\n - **`macos/scripts`**: 이 디렉토리는 macOS 전용 설치 로직을 담고 있습니다. macOS에서 필요한 수동 글꼴 설치 프로세스를 처리하기 위해 `install_coding_font.sh` 스크립트가 여기에 생성될 것입니다.\n - **`linux/scripts`**: 이 디렉토리는 Linux 전용 설치 스크립트를 포함합니다. 시스템 네이티브 설치를 위해 `apt` 패키지 관리자를 활용하는 `install_coding_font.sh` 스크립트가 여기에 생성될 것입니다.\n - **`setup.sh`**: (오케스트레이터 - 이 과제에서는 수정되지 않음). 이 메인 스크립트는 운영 체제를 감지하고 올바른 플랫폼별 스크립트(`macos/install_coding_font.sh` 또는 `linux/install_coding_font.sh`)를 호출하는 역할을 합니다.\n\n### 2.2. 영향을 받는 파일\n\n이 과제를 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `scripts/cpp_development_environment/macos/install_coding_font.sh`\n- `scripts/cpp_development_environment/linux/install_coding_font.sh`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 여러 개의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 글꼴 파일을 다운로드, 압축 해제하고 ~/Library/Fonts로 복사하는 macOS 스크립트\n\n#### 1. 스크립트 상수 정의\n\n이 액션은 글꼴 이름, 버전, 다운로드 URL과 같은 설정을 스크립트 상단에 중앙화합니다. 이렇게 하면 나중에 스크립트 로직을 뒤지지 않고도 글꼴 버전을 쉽게 업데이트할 수 있어 유지보수성이 향상됩니다.\n\n**파일**: `scripts/cpp_development_environment/macos/install_coding_font.sh`\n\n```shell\n# --- 상수 ---\nFONT_NAME=\"Fira Code\"\nFONT_VERSION=\"6.2\"\nFONT_PRESENCE_CHECK_FILE=\"$HOME/Library/Fonts/FiraCode-Bold.ttf\"\nFONT_DIRECTORY=\"$HOME/Library/Fonts\"\nDOWNLOAD_URL=\"https://github.com/tonsky/FiraCode/releases/download/${FONT_VERSION}/Fira_Code_v${FONT_VERSION}.zip\"\nTEMPORARY_DIRECTORY=\"/tmp/FiraCode_install\"\n```\n\n#### 2. 글꼴 다운로드 및 설치 로직 구현\n\n이 액션은 핵심 로직을 캡슐화하는 함수를 만듭니다. 임시 디렉토리를 만들고, `curl`을 사용하여 글꼴 아카이브를 다운로드하고, `unzip`으로 압축을 풀고, `.ttf` 파일들을 시스템의 글꼴 디렉토리로 복사합니다. 이 로직을 함수로 캡슐화하면 스크립트의 가독성과 모듈성이 향상됩니다. 각 단계에 오류 처리를 포함하여 스크립트가 정상적으로 실패하도록 보장합니다.\n\n**파일**: `scripts/cpp_development_environment/macos/install_coding_font.sh`\n\n```shell\n# Fira Code 글꼴을 다운로드하고, 압축을 풀고, 설치합니다.\ndownload_and_install_fira_code() {\n local temporary_zip_file=\"$TEMPORARY_DIRECTORY/FiraCode.zip\"\n\n log_info \"📥 $FONT_NAME 다운로드 및 설치 중...\"\n mkdir -p \"$TEMPORARY_DIRECTORY\"\n\n log_info \"$DOWNLOAD_URL 에서 다운로드 중...\"\n if ! curl -f -L -o \"$temporary_zip_file\" \"$DOWNLOAD_URL\"; then\n log_error \"Fira Code 글꼴 다운로드에 실패했습니다. URL이나 네트워크 연결을 확인해주세요.\"\n return 1\n fi\n\n log_info \"📦 글꼴 압축 해제 중...\"\n # 파일 목록은 숨기고 오류는 표시하기 위해 stdout만 /dev/null로 리디렉션합니다.\n if ! unzip -o \"$temporary_zip_file\" -d \"$TEMPORARY_DIRECTORY/extracted_fonts\" >/dev/null; then\n log_error \"글꼴 아카이브의 압축 해제에 실패했습니다. 파일이 손상되었을 수 있습니다.\"\n return 1\n fi\n\n log_info \"📂 글꼴 파일을 $FONT_DIRECTORY 로 복사 중...\"\n mkdir -p \"$FONT_DIRECTORY\"\n if ! cp \"$TEMPORARY_DIRECTORY/extracted_fonts/ttf/\"*.ttf \"$FONT_DIRECTORY/\"; then\n log_error \"글꼴 파일 복사에 실패했습니다. $FONT_DIRECTORY 의 권한을 확인해주세요.\"\n return 1\n fi\n\n log_info \"✅ $FONT_NAME 글꼴이 성공적으로 설치되었습니다.\"\n}\n```\n\n---\n\n### 단계 2: 임시 파일을 위한 macOS 스크립트의 trap 정리 함수\n\n#### 1. 정리 함수 생성\n\n이 액션은 설치 과정에서 생성된 임시 디렉토리를 제거하는 책임을 지는 함수를 정의합니다. 이는 스크립트의 성공 또는 실패 여부와 관계없이 스크립트가 잔여물을 남기지 않도록 하는 데 중요합니다.\n\n**파일**: `scripts/cpp_development_environment/macos/install_coding_font.sh`\n\n```shell\n# 스크립트 종료 시 임시 디렉토리가 정리되도록 보장합니다.\ncleanup() {\n if [ -d \"$TEMPORARY_DIRECTORY\" ]; then\n log_info \"🧹 임시 파일 정리 중...\"\n rm -rf \"$TEMPORARY_DIRECTORY\"\n fi\n}\n```\n\n#### 2. `trap`으로 정리 함수 등록\n\n이 액션은 스크립트가 종료될 때(성공적인 완료나 오류 등 어떤 이유로든) `cleanup` 함수가 자동으로 실행되도록 등록합니다. `trap` 명령어는 리소스 정리를 보장하는 강력한 메커니즘입니다.\n\n**파일**: `scripts/cpp_development_environment/macos/install_coding_font.sh`\n\n```shell\n# --- 스크립트 메인 로직 ---\n\n# 스크립트 종료 시 호출될 정리 함수를 등록합니다.\ntrap cleanup EXIT\n\nlog_info \"✍️ Fira Code 글꼴 설치 중 (macOS)...\"\n...\n```\n\n---\n\n### 단계 3: APT를 사용하여 fonts-firacode 패키지를 설치하는 Linux 스크립트\n\n#### 1. 패키지 기반 설치 구현\n\n이 액션은 Linux용 글꼴 설치를 구현합니다. 이 로직은 데비안 기반 시스템의 표준인 `apt` 패키지 관리자를 활용합니다. 시스템 수준의 설치를 처리하기 위해 (공통 유틸리티 스크립트에서 소싱되어 정의되었다고 가정하는) 헬퍼 함수들(`update_apt_cache` 및 `install_with_apt`)을 사용합니다. 이 접근 방식은 Linux에서 수동으로 설치하는 것보다 더 견고하고 유지보수하기 좋습니다.\n\n**파일**: `scripts/cpp_development_environment/linux/install_coding_font.sh`\n\n```shell\n# --- 설정 ---\nFONT_NAME=\"FiraCode\"\nFONT_PACKAGE_NAME=\"fonts-firacode\"\n\n# --- 메인 로직 ---\nlog_info \"✍️ Linux용 $FONT_NAME 글꼴 설치 중...\"\n\n# ... (다음 단계의 멱등성 검사) ...\n# if fc-list ... ; then\n# ...\n# else\n log_info \"'$FONT_NAME' 글꼴을 찾을 수 없습니다. '$FONT_PACKAGE_NAME' 설치를 진행합니다...\"\n\n # apt-cache를 업데이트하고 글꼴 패키지를 설치합니다.\n # 스크립트는 'set -euo pipefail' 때문에 실패 시 종료됩니다.\n update_apt_cache\n install_with_apt \"$FONT_PACKAGE_NAME\"\n\n log_info \"✅ $FONT_PACKAGE_NAME 패키지가 설치되었습니다. '$FONT_NAME' 글꼴을 사용하려면 애플리케이션을 다시 시작하세요.\"\n# fi\n```\n\n---\n\n### 단계 4: 두 플랫폼 모두에서 재설치를 방지하기 위한 멱등성 검사\n\n#### 1. macOS 멱등성 검사 구현\n\n이 액션은 글꼴이 이미 설치되었는지 확인하기 위해 macOS 스크립트에 검사를 추가합니다. 대상 디렉토리에서 특정 글꼴 파일(`FiraCode-Bold.ttf`)의 존재 여부를 확인하는 방식으로 이를 수행합니다. 이를 통해 중복된 다운로드 및 설치 작업을 방지하여 스크립트를 여러 번 실행해도 안전하게 만듭니다.\n\n**파일**: `scripts/cpp_development_environment/macos/install_coding_font.sh`\n\n```shell\nlog_info \"✍️ Fira Code 글꼴 설치 중 (macOS)...\"\n\nif [ -f \"$FONT_PRESENCE_CHECK_FILE\" ]; then\n log_info \"✅ $FONT_NAME 글꼴이 이미 존재합니다.\"\nelse\n download_and_install_fira_code\n log_info \"📌 새 글꼴을 보려면 터미널, IDE 및 기타 애플리케이션을 다시 시작하세요.\"\nfi\n\nlog_info \"Fira Code 글꼴 설치 스크립트가 완료되었습니다.\"\n```\n\n#### 2. Linux 멱등성 검사 구현\n\n이 액션은 Linux 스크립트에 멱등성 검사를 추가합니다. 표준 fontconfig 유틸리티인 `fc-list` 명령어를 사용하여 \"FiraCode\" 글꼴을 쿼리합니다. 이것은 Linux에서 글꼴 설치를 확인하는 표준적인 방법이며, 불필요한 `apt` 호출을 피할 수 있습니다.\n\n**파일**: `scripts/cpp_development_environment/linux/install_coding_font.sh`\n\n```shell\n# font-config 유틸리티가 사용 가능한지 확인\nif ! command -v fc-list >/dev/null; then\n log_error \"❌ 'fc-list' 명령을 찾을 수 없습니다. 먼저 'fontconfig' 패키지를 설치해주세요.\"\n exit 1\nfi\n\n# 글꼴이 이미 설치되었는지 확인\nif fc-list | grep -i \"$FONT_NAME\" >/dev/null; then\n log_info \"✅ $FONT_NAME 글꼴이 이미 설치되어 있습니다.\"\nelse\n # ... (이전 단계의 설치 로직) ...\nfi\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n1. **macOS에서**:\n - 스크립트를 직접 실행하여 설치를 트리거합니다.\n - 글꼴 파일의 존재 여부를 확인합니다.\n\n ```bash\n # 설치 프로그램 실행\n bash scripts/cpp_development_environment/macos/install_coding_font.sh\n\n # 파일 존재 여부 확인\n ls -l ~/Library/Fonts/FiraCode*.ttf\n ```\n\n2. **Linux에서**:\n - `apt`를 통해 설치를 트리거하기 위해 스크립트를 직접 실행합니다.\n - `fc-list`를 사용하여 글꼴이 시스템에 등록되었는지 확인합니다.\n\n ```bash\n # 설치 프로그램 실행\n bash scripts/cpp_development_environment/linux/install_coding_font.sh\n\n # 글꼴 등록 여부 확인\n fc-list | grep \"FiraCode\"\n ```\n\n### 4.2. 예상 결과\n\n- **첫 실행 시**: 각 OS용 스크립트는 다운로드/설치 진행 상황을 나타내는 메시지를 기록하고 성공 메시지와 함께 종료되어야 합니다. 검증 명령어는 성공해야 합니다.\n- **후속 실행 시**: 각 OS용 스크립트는 `Fira Code 글꼴이 이미 존재합니다.` 또는 `FiraCode 글꼴이 이미 설치되어 있습니다.`와 같은 메시지를 기록하고 빠르게 종료되어야 합니다.\n- **macOS 검증 명령어 출력 (예시)**:\n\n ```\n -rw-r--r--@ 1 user staff 392520 Sep 1 10:00 /Users/user/Library/Fonts/FiraCode-Bold.ttf\n -rw-r--r--@ 1 user staff 403828 Sep 1 10:00 /Users/user/Library/Fonts/FiraCode-Light.ttf\n ... (및 다른 글꼴 변형)\n ```\n\n- **Linux 검증 명령어 출력 (예시)**:\n\n ```\n /usr/share/fonts/truetype/firacode/FiraCode-Bold.ttf: FiraCode:style=Bold\n /usr/share/fonts/truetype/firacode/FiraCode-Regular.ttf: FiraCode:style=Regular\n ... (및 다른 글꼴 변형)\n ```\n","macOS와 Linux 모두에 Fira Code 글꼴을 설치하는 스크립트",[678,680,682,684],{"_24":679,"_83":39,"_84":266,"_85":61},"글꼴 파일을 다운로드, 압축 해제하고 `~/Library/Fonts`에 복사하는 macOS 스크립트",{"_24":681,"_83":39,"_84":266,"_85":88},"임시 파일을 위한 macOS 스크립트의 `trap` 정리 함수",{"_24":683,"_83":39,"_84":266,"_85":91},"APT를 사용하여 `fonts-firacode` 패키지를 설치하는 Linux 스크립트",{"_24":685,"_83":39,"_84":266,"_85":94},"재설치를 피하기 위한 양 플랫폼에서의 멱등성 검사","Fira Code 프로그래밍 글꼴의 자동화된 설치",{"_22":688,"_24":689,"_75":690,"_77":691,"_79":692,"_51":703,"_42":99},"task-1751002270007","VS Code 설정 템플릿","# 작업: VS Code 설정 템플릿\n\n> **에픽**: VS Code 구성\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: VS Code에서 C++ 개발을 위한 표준화된 JSON 구성.\n- **근거**: 설치 스크립트 사용자에게 일관성 있고 설정이 필요 없는(zero-configuration) 개발 경험을 보장하기 위함. 중앙화된 설정 템플릿은 설치 로직에서 구성을 분리하여 설정의 버전 관리, 유지보수 및 멱등성 있는(idempotent) 적용을 더 쉽게 만듭니다. 이는 단일 명령으로 완전히 구성된 환경이라는 프로젝트의 주요 목표를 직접적으로 지원합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: 편집기, 포맷터, clangd 설정이 포함된 JSON 파일.\n- **사양**:\n - `vscode_settings_template.json`이라는 이름의 유효한 JSON 파일.\n - `editor.formatOnSave` 키가 `true`로 설정됨.\n - `editor.fontFamily` 키가 기본 글꼴로 `Fira Code`를 지정함.\n - `C_Cpp.intelliSenseEngine` 키가 `clangd`를 우선적으로 사용하기 위해 `\"disabled\"`로 설정됨.\n - 언어별 설정인 `[cpp]`와 `[c]`에서 `llvm-vs-code-extensions.vscode-clangd`를 기본 포맷터로 지정함.\n - `clangd.arguments` 키에 명령줄 플래그를 위한 문자열 배열이 포함됨.\n- **결과 파일 구조**\n\n```bash\n# ./\n└── assets/\n └── vscode_settings_template.json <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 후속 작업의 일부인 VS Code 구성 스크립트가 설정 템플릿을 어떻게 사용할지 보여줍니다. 템플릿 자체는 정적 자산입니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"오케스트레이션 (setup.sh)\"\n direction LR\n A(\"common/configure_vscode.sh\")\n end\n B[\"assets/vscode_settings_template.json\"]\n C[\"사용자의 VS Code
settings.json\"]\n\n A -- \"1\\. 템플릿 읽기\" --> B\n A -- \"2\\. 설정을 다음에 병합\" --> C\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료된 것으로 표시하기 위해 다음 항목을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] 저장 시 서식 지정 및 글꼴 합자(ligature)를 위한 편집기 설정.\n- [ ] Fira Code를 기본 글꼴로 사용.\n- [ ] clangd를 우선 사용하기 위해 기본 IntelliSense 엔진을 비활성화하는 구성.\n- [ ] C/C++ 파일에 대한 기본 포맷터를 clangd로 연결.\n- [ ] clangd 확장을 위한 명령줄 인수.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 스크립트 기반 오케스트레이션\n- **관련 주요 구성 요소**:\n - **`assets`**: 이 디렉터리의 목적은 정적 구성 템플릿을 저장하는 것입니다. 이 작업은 이 디렉터리 내에 `vscode_settings_template.json` 파일을 생성하는 것을 포함하며, 이는 아키텍처 역할과 완벽하게 일치합니다.\n - **`common/scripts`**: 이 구성 요소는 OS에 구애받지 않는 로직을 담고 있습니다. 이 디렉터리 내의 스크립트(향후 작업에서 생성 예정)가 `vscode_settings_template.json` 파일의 소비자가 되어, 이를 읽고 그 내용을 사용자의 실제 VS Code 구성에 적용하는 역할을 합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `assets/vscode_settings_template.json`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 1단계: 저장 시 서식 지정 및 글꼴 합자를 위한 편집기 설정\n\n#### 1. 핵심 편집기 경험 정의\n\n이 작업은 개발자 생산성을 위한 기본적인 편집기 동작을 설정합니다. `editor.formatOnSave`는 저장 시 구성된 포맷터(`clangd`)로 코드를 자동으로 포맷하여 일관된 스타일을 보장합니다. `files.autoSave`는 짧은 지연 후 자동으로 저장하여 데이터 손실을 방지합니다. `editor.fontLigatures`는 Fira Code 글꼴의 스타일 세트를 지원하여 가독성을 향상시키기 위해 활성화됩니다.\n\n**파일**: `assets/vscode_settings_template.json`\n\n```json\n{\n \"editor.formatOnSave\": true,\n \"files.autoSave\": \"afterDelay\",\n \"editor.fontLigatures\": true,\n ...\n}\n```\n\n---\n\n### 2단계: Fira Code를 기본 글꼴로 사용\n\n#### 1. 편집기 글꼴 패밀리 지정\n\n이 작업은 프로젝트의 \"가독성 높은 코드\" 목표의 핵심 요소인 `Fira Code`를 기본 글꼴로 설정합니다. Fira Code가 올바르게 설치되지 않았을 수 있는 시스템을 위해 표준 글꼴 스택이 대체(fallback)로 제공됩니다. 이 설정은 Fira Code 글꼴을 설치하는 작업과 직접적으로 연결됩니다.\n\n**파일**: `assets/vscode_settings_template.json`\n\n```json\n{\n ...\n \"editor.fontFamily\": \"'Fira Code', Menlo, Monaco, 'Courier New', monospace\",\n ...\n}\n```\n\n---\n\n### 3단계: clangd를 우선 사용하기 위해 기본 IntelliSense 엔진을 비활성화하는 구성\n\n#### 1. IntelliSense 엔진 충돌 방지\n\n이 작업은 `clangd`가 C++의 유일한 언어 서버로 기능하도록 보장하는 데 매우 중요합니다. 기본 Microsoft C/C++ 확장에는 자체 IntelliSense 엔진이 포함되어 있어 `clangd`와 충돌하여 중복된 제안과 성능 문제를 일으킬 수 있습니다. 이 충돌을 방지하기 위해 `C_Cpp.intelliSenseEngine`을 `\"disabled\"`로 설정합니다. `clangd.detectExtensionConflicts`는 `false`로 설정하는데, 이는 우리가 주요 충돌을 수동으로 해결하고 있으므로 `clangd` 확장 자체에서 발생할 수 있는 불필요한 경고를 표시하지 않게 하기 위함입니다.\n\n**파일**: `assets/vscode_settings_template.json`\n\n```json\n{\n ...\n \"C_Cpp.intelliSenseEngine\": \"disabled\",\n \"clangd.detectExtensionConflicts\": false,\n ...\n}\n```\n\n---\n\n### 4단계: C/C++ 파일에 대한 기본 포맷터를 clangd로 연결\n\n#### 1. `clangd`를 기본 C++ 포맷터로 설정\n\n이 작업은 C 계열 언어 전체에 대해 `clangd` 확장을 기본 코드 포맷터로 명시적으로 지정합니다. 이를 통해 서식 지정 작업(예: 저장 시 서식 지정)이 트리거될 때 VS Code가 LLVM 툴체인을 사용하여 프로젝트의 코딩 표준을 일관되게 적용하도록 합니다. 또한 VS Code가 C 및 C++ 헤더 파일을 올바르게 식별하도록 파일 연결을 설정합니다.\n\n**파일**: `assets/vscode_settings_template.json`\n\n```json\n{\n ...\n \"files.associations\": {\n \"*.h\": \"c\",\n \"*.hpp\": \"cpp\"\n },\n \"[c]\": {\n \"editor.defaultFormatter\": \"llvm-vs-code-extensions.vscode-clangd\"\n },\n \"[cpp]\": {\n \"editor.defaultFormatter\": \"llvm-vs-code-extensions.vscode-clangd\"\n },\n \"[objective-c]\": {\n \"editor.defaultFormatter\": \"llvm-vs-code-extensions.vscode-clangd\"\n },\n \"[objective-cpp]\": {\n \"editor.defaultFormatter\": \"llvm-vs-code-extensions.vscode-clangd\"\n }\n}\n```\n\n---\n\n### 5단계: clangd 확장을 위한 명령줄 인수\n\n#### 1. `clangd` 실행 인수 구성\n\n이 작업은 시작 시 `clangd` 언어 서버에 특정 명령줄 인수를 제공하여 강력한 기능들을 활성화합니다.\n\n- `--background-index`: 백그라운드에서 프로젝트 전체의 코드 인덱스를 구축하여 성능을 향상시킵니다.\n- `--clang-tidy`: `clang-tidy` 검사를 통합하여 편집기에서 직접 정적 분석 및 린팅(linting)을 제공합니다.\n- `--completion-style=detailed`: 더 유익한 코드 완성 제안을 제공합니다.\n- `--header-insertion=iwyu`: `include-what-you-use` 로직을 사용하여 누락된 `#include` 지시문을 추가하기 위한 스마트한 제안을 제공합니다.\n\n**파일**: `assets/vscode_settings_template.json`\n\n```json\n{\n ...\n \"clangd.arguments\": [\n \"--background-index\",\n \"--clang-tidy\",\n \"--completion-style=detailed\",\n \"--header-insertion=iwyu\"\n ],\n ...\n}\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n1. **파일 존재 확인**: 파일이 올바른 위치에 생성되었는지 확인합니다.\n\n ```bash\n ls assets/vscode_settings_template.json\n ```\n\n2. **JSON 구문 유효성 검사**: `jq`와 같은 명령줄 JSON 처리기를 사용하여 파일에 유효한 JSON이 포함되어 있는지 확인합니다. 이 명령은 성공하면 출력을 포맷하고, 구문이 유효하지 않으면 오류를 생성합니다.\n\n ```bash\n jq . assets/vscode_settings_template.json\n ```\n\n3. **수동 내용 검사**: 파일의 내용을 표시하여 지정된 모든 키와 값이 있는지 시각적으로 확인합니다.\n\n ```bash\n cat assets/vscode_settings_template.json\n ```\n\n### 4.2. 예상 결과\n\n- `ls` 명령은 오류 없이 파일 경로를 성공적으로 나열해야 합니다.\n- `jq` 명령은 종료 코드 `0`으로 종료되고 색상이 지정된 포맷된 JSON 내용을 표준 출력으로 인쇄해야 합니다.\n- `cat` 명령은 위 단계에서 구현된 JSON 파일의 전체 원본 내용을 표시해야 합니다. 최종 파일은 다음과 같아야 합니다:\n\n```json\n{\n \"editor.formatOnSave\": true,\n \"files.autoSave\": \"afterDelay\",\n \"editor.fontFamily\": \"'Fira Code', Menlo, Monaco, 'Courier New', monospace\",\n \"editor.fontLigatures\": true,\n \"files.associations\": {\n \"*.h\": \"c\",\n \"*.hpp\": \"cpp\"\n },\n \"C_Cpp.intelliSenseEngine\": \"disabled\",\n \"clangd.detectExtensionConflicts\": false,\n \"clangd.arguments\": [\n \"--background-index\",\n \"--clang-tidy\",\n \"--completion-style=detailed\",\n \"--header-insertion=iwyu\"\n ],\n \"[c]\": {\n \"editor.defaultFormatter\": \"llvm-vs-code-extensions.vscode-clangd\"\n },\n \"[cpp]\": {\n \"editor.defaultFormatter\": \"llvm-vs-code-extensions.vscode-clangd\"\n },\n \"[objective-c]\": {\n \"editor.defaultFormatter\": \"llvm-vs-code-extensions.vscode-clangd\"\n },\n \"[objective-cpp]\": {\n \"editor.defaultFormatter\": \"llvm-vs-code-extensions.vscode-clangd\"\n }\n}\n```\n","편집기, 포맷터 및 clangd 설정을 포함하는 JSON 파일",[693,695,697,699,701],{"_24":694,"_83":39,"_84":284,"_85":61},"저장 시 서식 지정 및 글꼴 합자(ligature)를 위한 편집기 설정",{"_24":696,"_83":39,"_84":284,"_85":88},"기본 글꼴로 Fira Code 사용",{"_24":698,"_83":39,"_84":284,"_85":91},"clangd를 위해 기본 IntelliSense 엔진을 비활성화하는 구성",{"_24":700,"_83":39,"_84":284,"_85":94},"C/C++ 파일의 기본 포맷터를 clangd로 연결",{"_24":702,"_83":39,"_84":284,"_85":97},"clangd 확장을 위한 커맨드 라인 인수","VS Code에서의 C++ 개발을 위한 표준화된 JSON 구성",{"_22":705,"_24":706,"_75":707,"_77":708,"_79":709,"_51":720,"_42":99},"task-1751002325762","VS Code 구성 스크립트","# 작업: VS Code 구성 스크립트\n\n> **에픽**: VS Code 구성\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: C++ 환경에 대한 설정을 적용하고 확장 프로그램을 설치하는 스크립트.\n- **근거**: 프로젝트의 모든 개발자를 위해 Visual Studio Code 환경을 자동화하고 표준화합니다. 이를 통해 필수 C++ 도구(예: `clangd`, 디버거, 포맷터), 확장 프로그램 및 편집기 설정이 일관되게 구성되도록 보장하며, 이는 코드 품질 유지, 설정 마찰 감소, 전반적인 개발자 생산성 향상에 매우 중요합니다. 이 작업은 단일 명령으로 완전히 구성된 환경이라는 프로젝트의 핵심 목표를 직접적으로 지원합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 템플릿의 설정을 병합하고 확장 프로그램을 멱등성(idempotently) 있게 설치하는 셸 스크립트.\n- **사양**:\n - 스크립트 이름: `configure_vscode.sh`\n - 핵심 함수: `install_vscode_extensions()`, `apply_vscode_settings()`\n - 주요 로직: 확장 프로그램 관리를 위해 `code` CLI를 사용하고, JSON 구성 파일을 안전하게 병합하기 위해 `jq` 유틸리티를 활용합니다.\n - 멱등성(Idempotency): 스크립트는 여러 번 실행되더라도 기존 확장 프로그램을 다시 설치하거나 오류를 발생시키지 않아야 합니다.\n - 크로스 플랫폼: macOS와 Linux 모두에서 `settings.json` 경로를 정확히 식별하고 사용해야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./scripts/cpp_development_environment/\n# └── common/\n# └── configure_vscode.sh <-- 수정됨\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph configure_vscode.sh\n A[시작] --> B{'code' CLI 사용 가능?};\n B -- 아니요 --> C[경고 로그 후 종료];\n B -- 예 --> D[확장 프로그램 목록 정의];\n D --> E{확장 프로그램 루프};\n E -- 각 확장 프로그램에 대해 --> F{확장 프로그램이 설치되었는가?};\n F -- 아니요 --> G['code --install-extension'으로 설치];\n F -- 예 --> H['이미 설치됨' 로그];\n G --> E;\n H --> E;\n E -- 루프 종료 --> I{'jq'가 설치되었는가?};\n I -- 아니요 --> J['jq' 설치 시도];\n J -- 실패 --> K[경고 로그 후 설정 건너뛰기];\n K --> L[종료];\n J -- 성공 --> M;\n I -- 예 --> M;\n M[OS별 settings.json 경로 가져오기] --> N[템플릿을 settings.json에 병합];\n N --> L;\n end\n \n Orchestrator[\"setup.sh\"] --> A;\n\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] `code` CLI 도구의 사용 가능 여부 확인.\n- [ ] C++, 버전 관리, 코드 품질을 위한 확장 프로그램 목록.\n- [ ] 확장 프로그램이 아직 없는 경우 설치하는 루프.\n- [ ] `jq`를 사용하여 템플릿 설정을 사용자의 `settings.json`에 병합하는 함수.\n- [ ] `settings.json`의 플랫폼별 경로를 처리하는 로직.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 스크립트 기반 오케스트레이션\n- **관련된 주요 구성 요소**:\n - **`common/scripts`**: 이 구성 요소는 OS에 구애받지 않는 스크립트를 보관합니다. VS Code 구성 로직은 사소한 경로 차이를 내부적으로 처리하므로 플랫폼 전반에 걸쳐 거의 동일하기 때문에 `configure_vscode.sh` 스크립트는 여기에 위치합니다.\n - **`setup.sh`**: 메인 오케스트레이터입니다. 핵심 개발자 도구가 설치된 후, 설정 프로세스의 적절한 단계에서 `configure_vscode.sh`를 호출하는 역할을 합니다.\n - **`assets`**: 이 디렉터리는 정적 구성 템플릿을 저장합니다. `configure_vscode.sh` 스크립트는 표준화된 설정을 적용하기 위해 이 디렉터리에서 `vscode_settings_template.json`을 읽습니다.\n - **`os_agnostic_utils.sh`**: 로깅 및 프로그램 검증(`is_program_installed`)을 위한 공통 함수를 제공하는 유틸리티 스크립트로, `configure_vscode.sh`에서 소싱하여 사용합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `scripts/cpp_development_environment/common/configure_vscode.sh`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부적인 `조치`로 나뉩니다. 각 `조치`에 대해 제목, 명확한 서술적 설명('무엇'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `code` CLI 도구의 사용 가능 여부 확인\n\n#### 1. `code` 명령어에 대한 사전 검사 구현\n\n이 조치는 스크립트가 VS Code와 상호 작용할 수 있도록 보장합니다. 확장 프로그램 설치 및 기타 잠재적 구성과 같은 스크립트의 주요 기능은 `code` 명령줄 인터페이스에 의존합니다. 스크립트 시작 시 시스템의 `PATH`에 해당 명령어가 있는지 확인함으로써, 명령어가 없을 경우 유용한 메시지와 함께 정상적으로 실패하여 후속 오류를 방지할 수 있습니다.\n\n**파일**: `scripts/cpp_development_environment/common/configure_vscode.sh`\n\n```shell\n# ... (shebang 및 set 명령어)\n\n# 공통 OS 비종속 유틸리티 소싱.\nsource \"./common/os_agnostic_utils.sh\"\n\nlog_info \"⚙️ Visual Studio Code를 구성 중입니다...\"\n\n# 'code' 명령어가 PATH에 있는지 확인\nif ! command -v code &>/dev/null; then\n log_warning \"⚠️ PATH에서 'code' 명령을 찾을 수 없습니다. VS Code 확장 프로그램 설치를 건너뜁니다.\"\n log_warning \" 활성화하려면 VS Code를 열고 Cmd+Shift+P를 누른 다음 'Shell Command: Install \\'code\\' command in PATH'를 실행하세요.\"\n exit 0\nfi\n\n# ...\n```\n\n---\n\n### 단계 2: C++, 버전 관리, 코드 품질을 위한 확장 프로그램 목록\n\n#### 1. 필요한 확장 프로그램을 배열로 정의\n\n이 조치는 설치할 VS Code 확장 프로그램 목록을 중앙에서 관리합니다. 셸 배열(`extensions_to_install`)을 사용하면 목록을 쉽게 읽고, 관리하고, 업데이트할 수 있습니다. 확장 프로그램은 각 도구의 목적을 명확히 하기 위해 카테고리(C++ Core, Testing, Version Control 등)별로 그룹화되어 있으며, 이는 투명하고 유지보수 가능한 코드베이스를 만들려는 프로젝트의 목표를 따릅니다.\n\n**파일**: `scripts/cpp_development_environment/common/configure_vscode.sh`\n\n```shell\n# ...\n\n# --- 설치할 확장 프로그램 목록 ---\ninstall_vscode_extensions() {\n log_info \"VS Code 확장 프로그램 설치/검증을 준비 중입니다...\"\n local extensions_to_install=(\n # --- C++ 핵심 개발 도구 ---\n \"ms-vscode.cpptools\"\n \"llvm-vs-code-extensions.vscode-clangd\"\n \"ms-vscode.cmake-tools\"\n \"vadimcn.vscode-lldb\"\n \"cschlosser.doxdocgen\"\n \"josetr.cmake-language-support-vscode\"\n\n # --- 테스트 프레임워크 ---\n \"matepek.vscode-catch2-test-adapter\"\n \"fredericbonnet.cmake-test-adapter\"\n\n # --- 버전 관리 및 협업 ---\n \"eamodio.gitlens\"\n \"github.vscode-pull-request-github\"\n \"mhutchie.git-graph\"\n \"ms-vsliveshare.vsliveshare\"\n\n # --- 코드 품질 및 가독성 ---\n \"streetsidesoftware.code-spell-checker\"\n \"shardulm94.trailing-spaces\"\n \"oderwat.indent-rainbow\"\n \"usernamehw.errorlens\"\n \"editorconfig.editorconfig\"\n\n # --- 기타 유용한 유틸리티 ---\n \"christian-kohler.path-intellisense\"\n \"redhat.vscode-yaml\"\n \"docker.docker\"\n )\n # ...\n}\n# ...\n```\n\n---\n\n### 단계 3: 확장 프로그램이 아직 없는 경우 설치하는 루프\n\n#### 1. 멱등성 있는 설치 루프 구현\n\n이 조치는 확장 프로그램을 설치하는 핵심 로직을 구현합니다. 멱등성을 보장하기 위해, 스크립트는 먼저 `code --list-extensions`를 사용하여 현재 설치된 모든 확장 프로그램을 조회합니다. 그런 다음 대상 목록을 순회합니다. 각 확장 프로그램에 대해 대소문자를 구분하지 않는 `grep`을 수행하여 이미 존재하는지 확인합니다. `--install-extension` 명령어는 확장 프로그램이 없는 경우에만 실행되어 중복 다운로드 및 설치를 방지합니다.\n\n**파일**: `scripts/cpp_development_environment/common/configure_vscode.sh`\n\n```shell\n# ... (install_vscode_extensions 함수 내부)\n\n local installed_extensions\n installed_extensions=$(code --list-extensions)\n\n for extension in \"${extensions_to_install[@]}\"; do\n # 확장 프로그램이 이미 설치되었는지 확인 (대소문자 구분 없음)\n if echo \"${installed_extensions}\" | grep -qi \"^${extension}$\"; then\n log_info \"✅ VS Code 확장 프로그램 '${extension}'은(는) 이미 설치되어 있습니다.\"\n else\n log_info \"VS Code 확장 프로그램 설치 중: '${extension}'...\"\n if ! code --install-extension \"${extension}\" --force; then\n log_error \"❌ VS Code 확장 프로그램 설치 실패: '${extension}'.\"\n else\n log_info \"'${extension}'을(를) 성공적으로 설치했습니다.\"\n fi\n fi\n done\n}\n# ...\n```\n\n---\n\n### 단계 4: `jq`를 사용하여 템플릿 설정을 사용자의 `settings.json`에 병합하는 함수\n\n#### 1. `jq` 의존성 검사 구현\n\n이 조치는 JSON 조작에 필수적인 `jq` 유틸리티가 병합을 시도하기 전에 사용 가능한지 확인합니다. `ensure_jq_installed` 함수는 `jq`가 `PATH`에 있는지 확인합니다. 만약 없다면, 적절한 패키지 관리자(`brew` for macOS, `apt` for Linux)를 사용하여 설치를 시도함으로써 이 스크립트의 중요한 의존성을 자동화합니다.\n\n**파일**: `scripts/cpp_development_environment/common/configure_vscode.sh`\n\n```shell\n# ...\n# jq가 설치되었는지 확인하는 함수\nensure_jq_installed() {\n if ! is_program_installed \"jq\"; then\n log_info \"'jq'가 설치되어 있지 않습니다. 설치를 시도합니다...\"\n if [[ \"$(uname)\" == \"Darwin\" ]]; then\n if ! brew install jq; then log_error \"Homebrew를 통한 'jq' 설치에 실패했습니다.\"; return 1; fi\n elif [[ \"$(uname)\" == \"Linux\" ]]; then\n if ! sudo apt-get install -y jq; then log_error \"apt-get을 통한 'jq' 설치에 실패했습니다.\"; return 1; fi\n fi\n fi\n log_info \"✅ 'jq'를 사용할 수 있습니다.\"\n return 0\n}\n# ...\n```\n\n#### 2. 설정 병합 로직 구현\n\n이 조치는 사용자의 개인 구성을 손상시키지 않으면서 프로젝트의 표준 설정을 사용자의 기존 `settings.json` 파일에 병합합니다. `jq`의 깊은 병합 필터(`-s '.[0] * .[1]'`)를 사용하여 사용자의 파일과 템플릿을 결합합니다. 이 접근 방식은 충돌하는 모든 키를 템플릿의 값으로 덮어쓰면서 충돌하지 않는 모든 사용자 설정은 보존합니다. 오류 발생 시 사용자 설정 파일의 손상을 방지하기 위해 이 작업은 먼저 임시 파일에서 수행됩니다.\n\n**파일**: `scripts/cpp_development_environment/common/configure_vscode.sh`\n\n```shell\n# ... (apply_vscode_settings 함수 내부)\n\n # ... (jq 및 설정 파일 경로 확인)\n \n # jq를 사용하여 템플릿 설정을 사용자의 settings.json에 병합\n local temporary_merged_settings_file\n temporary_merged_settings_file=$(mktemp)\n\n if jq -s '.[0] * .[1]' \"$settings_file_path\" \"$settings_template_file\" >\"$temporary_merged_settings_file\"; then\n mv \"$temporary_merged_settings_file\" \"$settings_file_path\"\n log_info \"✅ '$settings_file_path'의 VS Code 설정을 성공적으로 업데이트했습니다.\"\n else\n log_error \"❌ jq를 사용하여 '$settings_file_path'에 설정을 병합하는 데 실패했습니다.\"\n rm -f \"$temporary_merged_settings_file\"\n fi\n}\n# ...\n```\n\n---\n\n### 단계 5: `settings.json`의 플랫폼별 경로를 처리하는 로직\n\n#### 1. 플랫폼을 인식하는 경로 해결 함수 생성\n\n이 조치는 `settings.json` 파일 위치에 대한 플랫폼 간의 차이점을 추상화합니다. `get_vscode_settings_path` 함수는 `uname`을 사용하여 운영 체제(`Darwin` for macOS, `Linux` for Linux)를 감지하고 사용자의 구성 파일에 대한 정확한 절대 경로를 반환합니다. 이 캡슐화는 `apply_vscode_settings` 함수를 OS에 구애받지 않도록 만들고 프로젝트의 크로스 플랫폼 아키텍처의 핵심 요구 사항을 충족하는 데 중요합니다.\n\n**파일**: `scripts/cpp_development_environment/common/configure_vscode.sh`\n\n```shell\n# ...\n# VS Code의 settings.json에 대한 올바른 경로를 가져오는 함수\nget_vscode_settings_path() {\n local settings_path=\"\"\n\n if [[ \"$(uname)\" == \"Darwin\" ]]; then\n settings_path=\"$HOME/Library/Application Support/Code/User/settings.json\"\n elif [[ \"$(uname)\" == \"Linux\" ]]; then\n settings_path=\"$HOME/.config/Code/User/settings.json\"\n else\n log_error \"VS Code 설정 구성에 지원되지 않는 OS입니다.\"\n return 1\n fi\n\n # 경로를 반환하기 전에 디렉터리가 존재하는지 확인\n mkdir -p \"$(dirname \"$settings_path\")\"\n echo \"$settings_path\"\n}\n# ...\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 개발자는 구현의 정확성을 검증하기 위해 다음 단계를 따라야 합니다. VS Code가 설치되어 있고 `code` 명령이 시스템 `PATH`에 추가되었다고 가정합니다.\n\n```bash\n# 1. (선택 사항) 기존 VS Code settings.json 파일을 백업합니다.\n# macOS: cp \"$HOME/Library/Application Support/Code/User/settings.json\" \"$HOME/Library/Application Support/Code/User/settings.json.bak\"\n# Linux: cp \"$HOME/.config/Code/User/settings.json\" \"$HOME/.config/Code/User/settings.json.bak\"\n\n# 2. (선택 사항) 깨끗한 환경이라면, 파일 생성을 테스트하기 위해 빈 설정 파일을 만듭니다.\n# macOS: mkdir -p \"$HOME/Library/Application Support/Code/User\" && echo '{ \"my.personal.setting\": true }' > \"$HOME/Library/Application Support/Code/User/settings.json\"\n# Linux: mkdir -p \"$HOME/.config/Code/User\" && echo '{ \"my.personal.setting\": true }' > \"$HOME/.config/Code/User/settings.json\"\n\n# 3. 메인 스크립트 디렉터리로 이동하여 구성 스크립트를 직접 실행합니다.\ncd scripts/cpp_development_environment\nbash ./common/configure_vscode.sh\n\n# 4. 출력에서 확장 프로그램 설치 및 설정 병합 성공 메시지를 확인합니다.\n# 예시: \"✅ VS Code 확장 프로그램 'ms-vscode.cpptools'은(는) 이미 설치되어 있습니다.\"\n# 예시: \"✅ '.../settings.json'의 VS Code 설정을 성공적으로 업데이트했습니다.\"\n\n# 5. 확장 프로그램이 설치된 것으로 목록에 표시되는지 확인합니다.\ncode --list-extensions | grep \"ms-vscode.cpptools\"\n\n# 6. settings.json 파일을 검사하여 템플릿 설정이 병합되고 개인 설정이 보존되었는지 확인합니다.\n# macOS: cat \"$HOME/Library/Application Support/Code/User/settings.json\"\n# Linux: cat \"$HOME/.config/Code/User/settings.json\"\n\n# 7. 스크립트를 두 번째 실행하여 멱등성을 검증합니다.\nbash ./common/configure_vscode.sh\n```\n\n### 4.2. 예상 결과\n\n- **첫 번째 실행**: 콘솔 출력에 각 새 확장 프로그램의 설치를 나타내는 로그 메시지와 `settings.json`이 성공적으로 업데이트되었음을 확인하는 최종 메시지가 표시됩니다. `settings.json` 파일에는 템플릿 설정과 기존의 모든 사용자 설정이 모두 포함됩니다. `code --list-extensions` 명령은 새로 설치된 확장 프로그램을 보여줍니다.\n- **두 번째 실행**: 콘솔 출력에 모든 필수 확장 프로그램이 \"이미 설치됨\"을 나타내는 로그 메시지가 표시됩니다. 설치 작업은 수행되지 않아야 합니다. 스크립트는 시스템의 상태를 변경하지 않고 성공적으로 완료되어 멱등성을 확인시켜 줍니다.\n","멱등적으로 확장 프로그램을 설치하고 템플릿의 설정을 병합하는 셸 스크립트",[710,712,714,716,718],{"_24":711,"_83":39,"_84":302,"_85":61},"`code` CLI 도구의 사용 가능 여부 확인",{"_24":713,"_83":39,"_84":302,"_85":88},"C++, 버전 관리 및 코드 품질을 위한 확장 프로그램 목록",{"_24":715,"_83":39,"_84":302,"_85":91},"확장 프로그램이 아직 없는 경우 설치하는 루프",{"_24":717,"_83":39,"_84":302,"_85":94},"`jq`를 사용하여 템플릿 설정을 사용자의 `settings.json`에 병합하는 함수",{"_24":719,"_83":39,"_84":302,"_85":97},"`settings.json`에 대한 플랫폼별 경로를 처리하는 로직","C++ 환경에 대한 설정을 적용하고 확장 프로그램을 설치하는 스크립트",{"_22":722,"_24":723,"_75":724,"_77":725,"_79":726,"_51":737,"_42":99},"task-1751002382597","메인 오케스트레이션 스크립트 (`setup.sh`)","# 작업: 메인 오케스트레이션 스크립트 (`setup.sh`)\n\n> **에픽**: 환경 오케스트레이션 및 샘플 프로젝트\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 전체 환경 설정을 자동화하는 단일 진입점 스크립트.\n- **근거**: 기저에 있는 설치 및 설정 모듈의 복잡성을 추상화하는 단일 사용자용 진입점을 제공하기 위함입니다. 이 스크립트는 중앙 오케스트레이터 역할을 하여 여러 운영 체제에서 일관되고 재현 가능한 설정 프로세스를 보장하며, 이는 '단일 명령어 설치'라는 프로젝트의 주요 목표를 직접적으로 충족합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: OS를 감지하고 모든 설치 및 설정 스크립트를 순서대로 실행하는 마스터 스크립트.\n- **명세**:\n - 스크립트는 `bash`로 실행 가능해야 합니다.\n - 견고한 오류 처리를 위해 `set -euo pipefail`로 시작해야 합니다.\n - 공유 유틸리티 함수를 활용하기 위해 `common/os_agnostic_utils.sh`를 소싱해야 합니다.\n - 호스트가 `macos`인지 `linux`인지 결정하는 OS 감지 로직을 포함해야 합니다.\n - 모든 종속 스크립트 모듈을 올바른 실행 순서로 나열하는 `SETUP_STEPS` 배열을 정의해야 합니다.\n - 각 모듈의 실행을 감싸 일관된 로깅과 오류 처리를 제공하는 `run_step` 함수를 포함해야 합니다.\n- **결과 파일 구조**\n\n```bash\n./scripts/cpp_development_environment/\n├── common/\n│ ├── ...\n│ └── setup_sample_project.sh\n├── linux/\n│ └── ...\n├── macos/\n│ └── ...\n└── setup.sh <-- 수정됨\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"setup.sh 실행\"\n direction LR\n A[시작] --> B{\"운영 체제 감지\"};\n B -- \"macOS\" --> C[\"플랫폼별
스크립트 경로 설정: 'macos/'\"];\n B -- \"Linux\" --> D[\"플랫폼별
스크립트 경로 설정: 'linux/'\"];\n C --> E[\"SETUP_STEPS 배열 초기화\"];\n D --> E;\n E --> F{\"SETUP_STEPS 반복\"};\n F -- \"다음 단계\" --> G[\"run_step(script_path)\"];\n G --> H{\"스크립트 실행\"};\n H -- \"성공\" --> F;\n H -- \"실패\" --> I[오류와 함께 종료];\n F -- \"모든 단계 완료\" --> J[종료];\n end\n```\n\n### 1.3. 인수 기준\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 개략적인 체크리스트이며, 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] 대상 플랫폼을 결정하기 위한 OS 감지 로직.\n- [ ] macOS에서 Homebrew에 대한 사전 검사.\n- [ ] 실행될 모든 스크립트를 나열하는 `SETUP_STEPS` 배열 정의.\n- [ ] 일관된 실행 및 로깅을 위한 `run_step` 래퍼 함수.\n- [ ] 어떤 단계라도 실패할 경우 스크립트를 종료하는 오류 처리.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 스크립트 기반 오케스트레이션\n- **관련 주요 구성 요소**:\n - `setup.sh`: 구현 중인 중앙 오케스트레이터. 다른 모든 스크립트의 순서를 정하고 실행하는 책임을 가집니다.\n - `common/os_agnostic_utils.sh`: 로깅(`log_info`, `log_error`), OS 감지(`detect_os`), 프로그램 확인(`is_program_installed`)을 위한 공유 함수를 제공하는 핵심적인 의존성입니다. `setup.sh`는 이러한 함수들을 소싱하여 광범위하게 사용합니다.\n - `macos/scripts/*`: macOS 전용 설치 스크립트 모음. `setup.sh`는 감지된 OS가 `macos`일 때 이 스크립트들을 실행합니다.\n - `linux/scripts/*`: Linux 전용 설치 스크립트 모음. `setup.sh`는 감지된 OS가 `linux`일 때 이 스크립트들을 실행합니다.\n - `common/scripts/*`: OS에 구애받지 않는 설정 스크립트 모음(예: `configure_vscode.sh`, `setup_sample_project.sh`). `setup.sh`는 플랫폼별 설치가 완료된 후 이 스크립트들을 실행합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `scripts/cpp_development_environment/setup.sh`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 기준**의 항목에 해당합니다. 각 `단계`는 일련의 세부적인 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 대상 플랫폼을 결정하기 위한 OS 감지 로직\n\n#### 1. 유틸리티 소싱 및 OS 감지\n\n이 액션은 스크립트의 기초를 설정합니다. 스크립트의 안전을 위해 shebang과 `set -euo pipefail` 명령으로 시작합니다. 그런 다음 재사용 가능한 함수에 접근하기 위해 `os_agnostic_utils.sh` 스크립트를 소싱합니다. `detect_os` 함수를 즉시 호출하여 호스트 운영 체제(`macos` 또는 `linux`)를 식별하고 그 결과를 `DETECTED_OPERATING_SYSTEM` 환경 변수로 내보냅니다. 이 변수는 스크립트 전체에서 사용될 지역 변수에 할당됩니다.\n\n**파일**: `scripts/cpp_development_environment/setup.sh`\n\n```bash\n#!/bin/bash\n\nset -euo pipefail\n\n# 현재 실행 중인 스크립트의 디렉토리를 가져옵니다\nSCRIPT_DIRECTORY=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\n\n# 공통 OS-agnostic 유틸리티를 소싱합니다\n# shellcheck source=./common/os_agnostic_utils.sh\nsource \"$SCRIPT_DIRECTORY/common/os_agnostic_utils.sh\"\n\n# --- OS 감지 및 사전 검사 ---\ndetect_os # 이 명령은 DETECTED_OPERATING_SYSTEM을 내보냅니다\nOPERATING_SYSTEM=$DETECTED_OPERATING_SYSTEM # 스크립트 지역 변수에 할당합니다\n```\n\n---\n\n### 단계 2: macOS에서 Homebrew에 대한 사전 검사\n\n#### 1. macOS 사전 검사 구현\n\n이 액션은 macOS에 특화된 중요한 검증 단계를 추가합니다. Homebrew는 macOS 환경의 지정된 패키지 관리자이므로, 스크립트는 계속 진행하기 전에 그 존재를 확인해야 합니다. 이 검사는 `is_program_installed` 유틸리티 함수를 사용합니다. 만약 시스템 `PATH`에서 `brew`를 찾을 수 없다면, 스크립트는 설명적인 오류 메시지를 기록하고 0이 아닌 상태 코드로 종료하여 부적절하게 구성된 시스템에서의 추가 실행을 방지합니다.\n\n**파일**: `scripts/cpp_development_environment/setup.sh`\n\n```bash\n...\nOPERATING_SYSTEM=$DETECTED_OPERATING_SYSTEM # 스크립트 지역 변수에 할당합니다\n\n# macOS 특정 사전 검사\nif [[ \"$OPERATING_SYSTEM\" == \"macos\" ]]; then\n if ! is_program_installed \"brew\"; then\n log_error \"❌ Homebrew가 설치되어 있지 않습니다. https://brew.sh/ 에서 먼저 설치해주세요.\"\n exit 1\n fi\nfi\n\nlog_info \"🚀 $OPERATING_SYSTEM 용 설정을 시작합니다...\"\n...\n```\n\n---\n\n### 단계 3: 실행될 모든 스크립트를 나열하는 `SETUP_STEPS` 배열 정의\n\n#### 1. 배열로 실행 순서 정의\n\n이 액션은 전체 설정 워크플로우를 `SETUP_STEPS`라는 이름의 관리하기 쉬운 단일 배열로 중앙화합니다. 이 디자인은 오케스트레이션 로직을 특정 설치 모듈로부터 분리합니다. 플랫폼별 경로를 구성하기 위해 `TARGET_DIRECTORY` 변수(`macos` 또는 `linux` 하위 디렉토리로 해석됨)를 사용하며, 공통 스크립트는 `common` 디렉토리에서 직접 참조됩니다. 이를 통해 주 실행 루프를 변경하지 않고도 단계를 쉽게 추가, 제거 또는 재정렬할 수 있습니다.\n\n**파일**: `scripts/cpp_development_environment/setup.sh`\n\n```bash\n...\nTARGET_DIRECTORY=\"$SCRIPT_DIRECTORY/$OPERATING_SYSTEM\"\n\n...\n\n# 실행할 설치 및 설정 스크립트의 순서를 정의합니다.\n# 이 접근 방식은 설정 단계를 관리하고 재정렬하기 쉽게 만듭니다.\ndeclare -a SETUP_STEPS\nSETUP_STEPS=(\n \"$TARGET_DIRECTORY/install_clang.sh\"\n \"$TARGET_DIRECTORY/install_cmake.sh\"\n \"$TARGET_DIRECTORY/install_ninja.sh\"\n \"$TARGET_DIRECTORY/install_git.sh\"\n \"$TARGET_DIRECTORY/install_github_cli.sh\"\n \"$TARGET_DIRECTORY/install_coding_font.sh\"\n \"$TARGET_DIRECTORY/install_vscode.sh\"\n \"$SCRIPT_DIRECTORY/common/configure_vscode.sh\"\n \"$SCRIPT_DIRECTORY/common/setup_sample_project.sh\"\n)\n\n# --- 주 실행 ---\n...\n```\n\n---\n\n### 단계 4: 일관된 실행 및 로깅을 위한 `run_step` 래퍼 함수\n\n#### 1. `run_step` 래퍼 함수 생성\n\n이 액션은 재사용 가능한 함수 `run_step`을 만들어 모든 모듈이 일관된 방식으로 실행되도록 보장합니다. 이 함수는 실행할 스크립트의 경로라는 단일 인자를 받습니다. 각 단계의 시작과 끝을 알리고, 각 모듈의 출력을 구분선으로 시각적으로 분리하여 표준화된 로깅을 제공합니다. 이는 사용자 경험을 개선하고 디버깅을 단순화합니다.\n\n**파일**: `scripts/cpp_development_environment/setup.sh`\n\n```bash\n...\nTARGET_DIRECTORY=\"$SCRIPT_DIRECTORY/$OPERATING_SYSTEM\"\n\nrun_step() {\n local script_path=\"$1\"\n echo \"\"\n log_info \"🔹 실행 중: $(basename \"$script_path\")\"\n echo \"----------------------------------------\"\n if bash \"$script_path\"; then\n log_info \"✅ 완료: $(basename \"$script_path\")\"\n else\n log_error \"❌ 실패: $(basename \"$script_path\")\"\n exit 1 # 단계가 실패하면 종료합니다\n fi\n echo \"----------------------------------------\"\n}\n\n# 실행할 설치 및 설정 스크립트의 순서를 정의합니다.\n...\n```\n\n---\n\n### 단계 5: 어떤 단계라도 실패할 경우 스크립트를 종료하는 오류 처리\n\n#### 1. 오류 처리를 포함한 주 실행 루프 구현\n\n이 액션은 `SETUP_STEPS` 배열과 `run_step` 함수를 결합하여 주 실행 루프를 만듭니다. `for` 루프는 배열에 정의된 각 스크립트 경로를 반복하며 `run_step`에 전달합니다. 오류 처리는 두 가지 방식으로 이루어집니다:\n\n1. **전역적**: 스크립트 상단의 `set -e`는 하위 스크립트 내에서 실패하는 모든 명령이 해당 스크립트를 오류와 함께 종료하도록 보장합니다.\n2. **세부적**: `run_step` 내의 `if bash \"$script_path\"` 검사는 이 0이 아닌 종료 코드를 명시적으로 잡아냅니다. 실패가 감지되면, `run_step`은 오류를 기록하고 즉시 `exit 1`을 호출하여 전체 오케스트레이션 프로세스를 종료합니다.\n\n**파일**: `scripts/cpp_development_environment/setup.sh`\n\n```bash\n...\n)\n\n# --- 주 실행 ---\n# 정의된 단계를 반복하며 순차적으로 실행합니다.\nfor step in \"${SETUP_STEPS[@]}\"; do\n run_step \"$step\"\ndone\n\necho \"\"\nlog_info \"🎉 ✅ 모든 구성 요소가 $OPERATING_SYSTEM에 성공적으로 설치 및 구성되었습니다!\"\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n1. 스크립트 디렉토리로 이동합니다.\n\n ```bash\n cd scripts/cpp_development_environment\n ```\n\n2. 스크립트에 실행 권한이 있는지 확인합니다.\n\n ```bash\n chmod +x setup.sh\n ```\n\n3. 스크립트를 실행합니다.\n\n ```bash\n bash setup.sh\n ```\n\n4. 스크립트가 성공적으로 완료된 후, 검증 스크립트를 실행하여 모든 도구를 사용할 수 있는지 확인합니다.\n\n ```bash\n bash verify.sh\n ```\n\n### 4.2. 예상 결과\n\n- `setup.sh` 스크립트는 `SETUP_STEPS` 배열에 정의된 각 단계의 시작과 성공적인 완료를 나타내는 일련의 로그 메시지를 출력합니다.\n- 스크립트는 최종 성공 메시지 `🎉 ✅ 모든 구성 요소가 [macos|linux]에 성공적으로 설치 및 구성되었습니다!`로 마무리됩니다.\n- 이후 `verify.sh`를 실행하면 각 도구를 확인하고 모두에 대해 성공을 보고하며 상태 코드 0으로 종료됩니다.\n\n`setup.sh`의 부분 출력 예시:\n\n```\n🔹 실행 중: install_clang.sh\n----------------------------------------\n(install_clang.sh의 출력)\n✅ 완료: install_clang.sh\n----------------------------------------\n\n🔹 실행 중: install_cmake.sh\n----------------------------------------\n(install_cmake.sh의 출력)\n✅ 완료: install_cmake.sh\n----------------------------------------\n...\n🎉 ✅ 모든 구성 요소가 macos에 성공적으로 설치 및 구성되었습니다!\n```\n","OS를 감지하고 모든 설치 및 구성 스크립트를 순서대로 실행하는 마스터 스크립트",[727,729,731,733,735],{"_24":728,"_83":39,"_84":320,"_85":61},"대상 플랫폼을 결정하기 위한 OS 감지 로직",{"_24":730,"_83":39,"_84":320,"_85":88},"macOS에서 Homebrew에 대한 사전 검사",{"_24":732,"_83":39,"_84":320,"_85":91},"실행할 모든 스크립트를 나열하는 정의된 배열 `SETUP_STEPS`",{"_24":734,"_83":39,"_84":320,"_85":94},"일관된 실행 및 로깅을 위한 `run_step` 래퍼 함수",{"_24":736,"_83":39,"_84":320,"_85":97},"어떤 단계라도 실패할 경우 스크립트를 종료하는 오류 처리","전체 환경 설정을 자동화하는 단일 진입점 스크립트",{"_22":739,"_24":740,"_75":741,"_77":742,"_79":743,"_51":754,"_42":99},"task-1751002442400","샘플 C++ 프로젝트 스캐폴딩 스크립트","# 작업: 샘플 C++ 프로젝트 스캐폴딩 스크립트\n\n> **에픽**: 환경 오케스트레이션 및 샘플 프로젝트\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 즉각적인 검증을 위해 샘플 C++ 프로젝트를 생성하고 빌드하는 스크립트.\n- **근거**: 설치된 C++ 툴체인에 대한 종단 간 기능 테스트를 제공합니다. CMake를 사용하여 간단한 C++ 프로젝트를 성공적으로 스캐폴딩, 빌드 및 실행함으로써 이 스크립트는 핵심 개발 환경(Clang, CMake, Ninja)이 올바르게 설치되고 구성되었음을 즉각적이고 실질적으로 증명합니다. 이는 메인 `setup.sh` 오케스트레이션 내에서 최종 검증 단계 역할을 합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 완전한 'Hello, World' C++ 프로젝트를 생성하고, CMake로 빌드하며, 실행 파일을 실행하는 스크립트.\n- **사양**:\n - 새로운 셸 스크립트 `setup_sample_project.sh`가 생성됩니다.\n - 스크립트는 `$HOME/cpp-sample`에 프로젝트 디렉터리를 생성합니다.\n - C++20용으로 구성된 `CMakeLists.txt`를 생성합니다.\n - `src/main.cpp` 파일을 생성합니다.\n - `build` 하위 디렉터리에서 프로젝트를 구성하고 빌드하기 위해 `cmake`를 실행합니다.\n - 컴파일된 바이너리를 실행하고 그 출력을 인쇄합니다.\n- **결과 파일 구조**\n\n```bash\n# ./scripts/cpp_development_environment/\n# └── common/\n# └── setup_sample_project.sh <-- 신규\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n Orchestrator[\"setup.sh (오케스트레이터)\"] --> Scaffolder[\"setup_sample_project.sh\"];\n Scaffolder --> CreateDirs[\"디렉터리 생성
(src, build)\"];\n CreateDirs --> CreateCMake[\"CMakeLists.txt 생성\"];\n CreateCMake --> CreateSource[\"main.cpp 생성\"];\n CreateSource --> ConfigureBuild[\"빌드 구성을 위해 cmake 실행\"];\n ConfigureBuild --> BuildProject[\"컴파일을 위해 cmake --build 실행\"];\n BuildProject --> RunExecutable[\"컴파일된 바이너리 실행\"];\n RunExecutable --> DisplayOutput[\"'Hello, World!' 출력 표시\"];\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3장에 있습니다.\n\n- [ ] 프로젝트 디렉터리(`src`, `build`) 생성.\n- [ ] `CMakeLists.txt` 파일 생성.\n- [ ] `main.cpp` 소스 파일 생성.\n- [ ] 프로젝트 구성 및 빌드를 위한 `cmake` 실행.\n- [ ] 성공을 입증하기 위한 컴파일된 바이너리 실행.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 스크립트 기반 오케스트레이션\n- **관련 주요 구성 요소**:\n - **`common/scripts`**: 이 스크립트는 이 디렉터리에 위치한 OS에 구애받지 않는 모듈입니다. 그 목적은 플랫폼별 툴체인이 설치된 후 macOS와 Linux 모두에서 동일한 작업을 수행하는 것입니다.\n - **`setup.sh`**: 메인 오케스트레이터는 사용자에게 실질적으로 작동하는 예제 프로젝트를 제공하기 위해 설정 프로세스의 마지막 단계 중 하나로 이 스크립트를 호출합니다.\n - **`CMake` / `Clang`**: 이 스크립트는 `cmake` 명령줄 도구를 직접 활용하며, 이는 다시 `Clang` C++ 컴파일러를 호출합니다. 이는 실행 순서상 이전 스크립트들에 의해 설치된 도구들의 소비자이자 검증자 역할을 합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정됩니다.\n\n- `scripts/cpp_development_environment/common/setup_sample_project.sh`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 프로젝트 디렉터리(`src`, `build`) 생성\n\n#### 1. 프로젝트 구조 정의 및 디렉터리 생성\n\n이 작업은 깔끔한 소스 외부(out-of-source) CMake 빌드에 필요한 디렉터리 구조를 설정합니다. 프로젝트, 소스, 빌드 디렉터리에 대한 변수를 정의하여 가독성과 유지보수성을 향상시킵니다. 스크립트는 이 디렉터리들을 사용자 홈 디렉터리(`$HOME`) 내에 생성합니다. `mkdir -p`를 사용하면 이 명령이 멱등성을 갖도록 보장합니다. 즉, 디렉터리가 이미 존재하더라도 실패하지 않습니다. 디렉터리가 존재하는 경우 내용이 덮어쓰여질 수 있다는 경고 메시지를 사용자에게 출력하여 알립니다.\n\n**파일**: `scripts/cpp_development_environment/common/setup_sample_project.sh`\n\n```bash\n#!/bin/bash\n\nset -euo pipefail\n\n# 이 스크립트는 사용자 홈 디렉터리에 기본 C++ 샘플 프로젝트를 설정합니다.\n\necho \"📂 샘플 C++ 프로젝트를 생성 중입니다...\"\n\nPROJECT_DIRECTORY=\"$HOME/cpp-sample\"\nSOURCE_DIRECTORY=\"$PROJECT_DIRECTORY/src\"\nBUILD_DIRECTORY=\"$PROJECT_DIRECTORY/build\"\n\nif [[ -d \"$PROJECT_DIRECTORY\" ]]; then\n echo \"⚠️ $PROJECT_DIRECTORY 디렉터리가 이미 존재합니다.\"\n echo \" 내용이 덮어쓰여질 수 있습니다.\"\nfi\n\n# 모든 필요한 디렉터리 생성\nmkdir -p \"$SOURCE_DIRECTORY\"\nmkdir -p \"$BUILD_DIRECTORY\"\n```\n\n---\n\n### 단계 2: `CMakeLists.txt` 파일 생성\n\n#### 1. CMake 빌드 구성 생성\n\n이 작업은 CMake 기반 프로젝트의 핵심인 `CMakeLists.txt` 파일을 생성합니다. `cat <\"$PROJECT_DIRECTORY/CMakeLists.txt\"\ncmake_minimum_required(VERSION 3.20)\nproject(HelloWorld LANGUAGES CXX)\n\nset(CMAKE_CXX_STANDARD 20)\nset(CMAKE_BUILD_TYPE Debug)\nadd_executable(hello_world src/main.cpp)\nEOF\n\n...\n```\n\n---\n\n### 단계 3: `main.cpp` 소스 파일 생성\n\n#### 1. 샘플 C++ 소스 코드 생성\n\n이 작업은 `main.cpp` 소스 파일을 생성합니다. `CMakeLists.txt` 생성과 유사하게, 히어독(heredoc)을 사용하여 간단하지만 현대적인 C++ \"Hello, World!\" 프로그램을 작성합니다. 코드는 `CMakeLists.txt` 파일에 명시된 대로 `src` 디렉터리에 위치합니다. 이것은 C++ 컴파일러가 처리할 실제 코드를 제공하여 빌드 타겟에 유효한 소스 파일이 있도록 보장합니다.\n\n**파일**: `scripts/cpp_development_environment/common/setup_sample_project.sh`\n\n```bash\n...\nset(CMAKE_BUILD_TYPE Debug)\nadd_executable(hello_world src/main.cpp)\nEOF\n\n# 메인 C++ 소스 파일 생성\ncat <\"$SOURCE_DIRECTORY/main.cpp\"\n#include \n#include \n\nauto main() -> int32_t {\n int32_t x = 42;\n int32_t y = x * 2;\n std::cout << \"Hello, Modern C++! y = \" << y << std::endl;\n return 0;\n}\nEOF\n\n...\n```\n\n---\n\n### 단계 4: 프로젝트 구성 및 빌드를 위한 `cmake` 실행\n\n#### 1. 프로젝트 구성 및 빌드\n\n이 작업은 CMake 빌드 프로세스를 실행합니다. 먼저, 프로젝트 루트에서 `cmake -S . -B build`를 호출하여 프로젝트를 구성합니다(`-S` 소스 디렉터리는 프로젝트 루트이고, `-B` 바이너리 디렉터리는 `build`입니다). 이것은 `build` 디렉터리 내에 빌드 시스템 파일(예: Makefiles 또는 Ninja 파일)을 생성합니다. 둘째로, `cmake --build build`를 실행하여 기반 빌드 시스템을 호출하고 코드를 컴파일합니다. 전체 프로세스는 `if` 문으로 감싸져 강력한 오류 처리를 제공하며, 빌드가 실패하면 스크립트를 종료합니다.\n\n**파일**: `scripts/cpp_development_environment/common/setup_sample_project.sh`\n\n```bash\n...\n}\nEOF\n\necho \"🛠️ '$BUILD_DIRECTORY'에서 CMake 구성 및 빌드를 실행 중입니다...\"\n# 소스 디렉터리에서 프로젝트를 구성하고, 빌드 디렉터리에 빌드 시스템을 생성합니다.\n# 그런 다음, 프로젝트를 빌드합니다.\nif cmake -S \"$PROJECT_DIRECTORY\" -B \"$BUILD_DIRECTORY\" && cmake --build \"$BUILD_DIRECTORY\"; then\n echo \"✅ 샘플 프로젝트가 성공적으로 빌드되었습니다!\"\n echo \"\"\n ...\nelse\n echo \"❌ 빌드에 실패했습니다. CMake 및 컴파일러 설치를 확인하십시오.\"\n exit 1\nfi\n```\n\n---\n\n### 단계 5: 성공을 입증하기 위한 컴파일된 바이너리 실행\n\n#### 1. 컴파일된 실행 파일 실행\n\n이 마지막 작업은 컴파일된 바이너리를 실행하여 전체 프로세스가 성공적이었음을 확인합니다. 빌드가 성공한 후, 스크립트는 `build` 디렉터리에 있는 `hello_world` 프로그램을 실행합니다. 그 출력은 콘솔에 인쇄되어 사용자에게 자신의 개발 환경이 소스 코드부터 실행까지 완벽하게 작동한다는 즉각적인 피드백을 제공합니다.\n\n**파일**: `scripts/cpp_development_environment/common/setup_sample_project.sh`\n\n```bash\n...\n# 그런 다음, 프로젝트를 빌드합니다.\nif cmake -S \"$PROJECT_DIRECTORY\" -B \"$BUILD_DIRECTORY\" && cmake --build \"$BUILD_DIRECTORY\"; then\n echo \"✅ 샘플 프로젝트가 성공적으로 빌드되었습니다!\"\n echo \"\"\n echo \"🚀 실행 파일 실행 중:\"\n echo \"------------------------\"\n \"$BUILD_DIRECTORY/hello_world\"\n echo \"------------------------\"\nelse\n echo \"❌ 빌드에 실패했습니다. CMake 및 컴파일러 설치를 확인하십시오.\"\n exit 1\nfi\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 스크립트의 정확성을 검증하려면, 프로젝트의 루트 디렉터리에서 직접 실행하십시오. 실행하기 전에 C++ 툴체인(Clang, CMake, Ninja)이 설치되어 있고 `PATH`에서 사용 가능한지 확인하십시오.\n\n```bash\n# 스크립트 디렉터리로 이동하여 실행 가능하게 만듭니다\nchmod +x scripts/cpp_development_environment/common/setup_sample_project.sh\n\n# 스크립트 실행\nbash scripts/cpp_development_environment/common/setup_sample_project.sh\n```\n\n### 4.2. 예상 결과\n\n- 실행 후, 스크립트는 디렉터리 생성, 빌드 성공, 그리고 최종 프로그램 출력을 나타내는 일련의 상태 메시지를 출력해야 합니다. 터미널 출력은 다음과 유사해야 합니다:\n\n```\n📂 샘플 C++ 프로젝트를 생성 중입니다...\n🛠️ '/Users/user/cpp-sample/build'에서 CMake 구성 및 빌드를 실행 중입니다...\n-- The CXX compiler identification is AppleClang 15.0.0.15000100\n-- Detecting CXX compiler ABI info\n-- Detecting CXX compiler ABI info - done\n-- Check for working CXX compiler: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/c++ - a.k.a. /usr/bin/c++ - done\n-- Detecting CXX compile features\n-- Detecting CXX compile features - done\n-- Configuring done (0.3s)\n-- Generating done (0.0s)\n-- Build files have been written to: /Users/user/cpp-sample/build\n[1/2] Building CXX object CMakeFiles/hello_world.dir/src/main.cpp.o\n[2/2] Linking CXX executable hello_world\n✅ 샘플 프로젝트가 성공적으로 빌드되었습니다!\n\n🚀 실행 파일 실행 중:\n------------------------\nHello, Modern C++! y = 84\n------------------------\n```\n","완전한 'Hello, World' C++ 프로젝트를 생성하고, CMake로 빌드한 후, 실행 파일을 실행하는 스크립트",[744,746,748,750,752],{"_24":745,"_83":39,"_84":338,"_85":61},"프로젝트 디렉터리 (`src`, `build`) 생성",{"_24":747,"_83":39,"_84":338,"_85":88},"`CMakeLists.txt` 파일 생성",{"_24":749,"_83":39,"_84":338,"_85":91},"`main.cpp` 소스 파일 생성",{"_24":751,"_83":39,"_84":338,"_85":94},"프로젝트를 구성하고 빌드하기 위한 `cmake` 실행",{"_24":753,"_83":39,"_84":338,"_85":97},"성공을 입증하기 위해 컴파일된 바이너리 실행","즉각적인 검증을 위해 샘플 C++ 프로젝트를 생성하고 빌드하는 스크립트",{"_22":756,"_24":757,"_75":758,"_77":759,"_79":760,"_51":771,"_42":99},"task-1751002492568","검증 스크립트 (`verify.sh`)","# 작업: 검증 스크립트 (`verify.sh`)\n\n> **에픽**: 설치 검증 스크립트\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 필요한 모든 CLI 도구가 성공적으로 설치되었는지 프로그래밍 방식으로 확인하는 스크립트.\n- **근거**: 이 스크립트는 `setup.sh` 오케스트레이터가 완료된 후 개발 환경의 무결성을 검증하는 결정적이고 자동화 가능한 방법을 제공합니다. 특히 지속적 통합(CI) 파이프라인 내에서 명확한 성공/실패 신호(성공 시 종료 코드 `0`, 실패 시 0이 아닌 값)를 제공하여 최종 성공 기준으로 사용됩니다. 이는 설정 로직과 검증 로직을 분리하여 단일 책임 원칙을 준수합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: 필수 도구의 존재 여부와 실행 가능성을 확인하고, 누락된 도구가 있을 경우 오류와 함께 종료하는 독립 실행형 스크립트.\n- **명세**:\n - 스크립트는 `scripts/cpp_development_environment/verify.sh`에 위치해야 합니다.\n - 실행 가능해야 합니다: `bash verify.sh`.\n - Shebang `#!/bin/bash`를 사용해야 합니다.\n - `set -euo pipefail`로 엄격한 오류 처리를 활성화해야 합니다.\n - 공유 로깅 및 검증 함수를 활용하기 위해 `common/os_agnostic_utils.sh`를 소싱해야 합니다.\n - 모든 도구가 성공적으로 검증되면 상태 코드 `0`으로 종료해야 합니다.\n - 도구를 찾을 수 없거나 검증에 실패하면 상태 코드 `1`로 종료해야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n└── scripts/\n └── cpp_development_environment/\n ├── common/\n │ └── os_agnostic_utils.sh\n ├── linux/\n ├── macos/\n └── verify.sh <-- 수정됨\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n Start[verify.sh 시작] --> SourceUtils[\"os_agnostic_utils.sh 소싱\"];\n SourceUtils --> InitArray[\"COMMANDS_TO_VERIFY 배열 초기화\"];\n InitArray --> LoopStart{\"각 도구에 대해 루프\"};\n LoopStart -- \"다음 도구\" --> VerifyTool[\"도구에 대해 verify_essential_tool 호출\"];\n VerifyTool --> IsInstalled{\"is_program_installed?\"};\n IsInstalled -- \"아니오\" --> LogError[\"log_error 후 종료 코드 1로 종료\"];\n IsInstalled -- \"예\" --> VerifyCommand{\"verify_command (예: --version)?\"};\n VerifyCommand -- \"아니오\" --> LogError;\n VerifyCommand -- \"예\" --> LogSuccess[\"log_info: 도구 검증됨\"];\n LogSuccess --> LoopEnd{\"루프 끝?\"};\n LoopEnd -- \"아니오\" --> LoopStart;\n LoopEnd -- \"예\" --> FinalSuccess[\"log_info: 모든 도구 검증됨\"];\n FinalSuccess --> End[종료 코드 0으로 종료];\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이는 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] 모든 필수 도구를 나열하는 배열 `COMMANDS_TO_VERIFY`.\n- [ ] `verify_essential_tool` 헬퍼 함수.\n- [ ] 목록의 각 도구를 순회하며 검증하는 루프.\n- [ ] 공유 유틸리티의 `is_program_installed` 및 `verify_command` 사용.\n- [ ] 각 도구의 검증 상태에 대한 명확한 로깅.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 스크립트 기반 오케스트레이션\n- **관련 주요 구성 요소**:\n - **`verify.sh`**: 구현 중인 주요 구성 요소. 역할은 설정 후 검증으로, 주 `setup.sh` 스크립트와 독립적으로 작동하여 환경의 무결성을 확인합니다.\n - **`common/os_agnostic_utils.sh`**: 이 스크립트는 중요한 의존성입니다. `verify.sh`가 사용해야 하는 로깅(`log_info`, `log_error`) 및 명령어 검증(`is_program_installed`, `verify_command`)을 위한 재사용 가능하고 OS에 구애받지 않는 함수를 제공합니다.\n - **`.github/workflows/ci.yml`**: CI 워크플로는 `verify.sh`의 주요 소비자입니다. macOS와 Linux 러너 모두에서 설정이 성공했는지 프로그래밍 방식으로 확인하기 위해 테스트 매트릭스의 마지막 단계로 이 스크립트를 실행할 것입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `scripts/cpp_development_environment/verify.sh`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 모든 필수 도구를 나열하는 배열 `COMMANDS_TO_VERIFY`\n\n#### 1. 검증 목록 정의\n\n이 작업은 성공적인 설정 후에 존재해야 하는 모든 명령줄 도구의 목록을 중앙에서 관리합니다. Bash 배열(`COMMANDS_TO_VERIFY`)을 사용하면 새 도구가 추가되거나 제거될 때 스크립트를 유지 관리하고 업데이트하기 쉬워집니다. 이 목록은 검증 루프의 신뢰할 수 있는 단일 출처(source of truth)입니다. GUI 애플리케이션(VS Code)과 글꼴은 터미널 전용 CI 환경에서 검증이 복잡하고 신뢰할 수 없으므로 의도적으로 제외되었습니다.\n\n**파일**: `scripts/cpp_development_environment/verify.sh`\n\n```bash\n...\nlog_info \"🚀 설치된 도구들의 검증을 시작합니다...\"\n\n# 검증할 필수 명령어 목록.\n# 참고: 글꼴 설치는 CI 환경에서 검증하기 어려워 생략합니다.\n# VS Code도 GUI 애플리케이션이므로 생략합니다.\nCOMMANDS_TO_VERIFY=(\n \"clang\"\n \"clangd\"\n \"clang-tidy\"\n \"clang-format\"\n \"lldb\"\n \"cmake\"\n \"ninja\"\n \"git\"\n \"gh\"\n)\n...\n```\n\n---\n\n### 단계 2: `verify_essential_tool` 헬퍼 함수\n\n#### 1. 도구 검증 래퍼 구현\n\n이 작업은 단일 도구를 검증하는 로직을 캡슐화하기 위해 `verify_essential_tool`이라는 전용 함수를 만듭니다. 이러한 모듈식 접근 방식은 가독성을 향상시키고 주 실행 루프를 단순화합니다. 이 함수는 단일 인수(도구 이름)를 받고, 확인 중인 특정 도구에 대한 명확한 로깅을 제공하며, 성공 및 실패에 대한 핵심 조건부 로직을 포함합니다.\n\n**파일**: `scripts/cpp_development_environment/verify.sh`\n\n```bash\n...\n# --- 헬퍼 함수 ---\n\n# 단일 필수 도구를 검증합니다. 검증 실패 시 오류와 함께 종료합니다.\nverify_essential_tool() {\n local tool_name=\"$1\"\n echo\n log_info \"--- '$tool_name' 검증 중 ---\"\n\n if ! is_program_installed \"$tool_name\"; then\n log_error \"❌ '$tool_name'이(가) 설치되지 않았거나 PATH에 없습니다. 설정 스크립트를 실행해 주세요.\"\n exit 1\n fi\n\n if ! verify_command \"$tool_name\"; then\n log_error \"❌ '$tool_name'을(를) 찾았지만, 검증(예: --version)에 실패했습니다.\"\n exit 1\n fi\n\n log_info \"✅ '$tool_name'이(가) 설치 및 검증되었습니다.\"\n}\n...\n```\n\n---\n\n### 단계 3: 목록의 각 도구를 순회하며 검증하는 루프\n\n#### 1. 주 검증 루프 구현\n\n이 작업은 스크립트의 주 실행 블록을 생성합니다. `for` 루프는 단계 1에서 정의된 `COMMANDS_TO_VERIFY` 배열의 각 요소를 순회합니다. 각 반복에서 `verify_essential_tool` 헬퍼 함수를 호출하여 현재 도구의 이름을 인수로 전달합니다. 이를 통해 필요한 모든 도구가 순차적으로 확인됩니다.\n\n**파일**: `scripts/cpp_development_environment/verify.sh`\n\n```bash\n...\n# --- 주 검증 로직 ---\n\nfor tool in \"${COMMANDS_TO_VERIFY[@]}\"; do\n verify_essential_tool \"$tool\"\ndone\n\necho\nlog_info \"🎉 모든 필수 도구가 성공적으로 설치 및 검증되었습니다!\"\n```\n\n---\n\n### 단계 4: 공유 유틸리티의 `is_program_installed` 및 `verify_command` 사용\n\n#### 1. 공유 유틸리티 스크립트 소싱\n\n헬퍼 함수를 사용하려면 스크립트가 먼저 `os_agnostic_utils.sh` 파일을 소싱해야 합니다. 이는 `verify.sh` 내에서 함수를 사용할 수 있게 만드는 기본 단계입니다. 스크립트 경로는 `verify.sh` 스크립트 자체의 위치를 기준으로 구성되어 어디서 호출되든 작동하도록 보장합니다.\n\n**파일**: `scripts/cpp_development_environment/verify.sh`\n\n```bash\n#!/bin/bash\n...\n# 현재 실행 중인 스크립트의 디렉터리를 가져옵니다\nSCRIPT_DIRECTORY=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\n\n# 공통 OS 무관 유틸리티를 소싱합니다\n# shellcheck source=./common/os_agnostic_utils.sh\nsource \"$SCRIPT_DIRECTORY/common/os_agnostic_utils.sh\"\n...\n```\n\n#### 2. 검증을 위한 유틸리티 함수 호출\n\n이 작업은 `verify_essential_tool` 헬퍼 내에서 공유 유틸리티 함수를 호출하는 부분을 구현합니다. 먼저 `is_program_installed \"$tool_name\"`을 호출하여 명령어가 시스템의 `PATH`에 있는지 확인합니다. 명령어가 존재하면 `verify_command \"$tool_name\"`을 호출하여 바이너리가 실행 가능하고 손상되지 않았는지 더 강력하게 확인합니다(일반적으로 `tool --version` 실행). 둘 중 하나의 확인이 실패하면 스크립트는 오류를 기록하고 `set -e`로 인해 즉시 종료됩니다.\n\n**파일**: `scripts/cpp_development_environment/verify.sh`\n\n```bash\n...\nverify_essential_tool() {\n local tool_name=\"$1\"\n ...\n if ! is_program_installed \"$tool_name\"; then\n log_error \"❌ '$tool_name'이(가) 설치되지 않았거나 PATH에 없습니다. 설정 스크립트를 실행해 주세요.\"\n exit 1\n fi\n\n if ! verify_command \"$tool_name\"; then\n log_error \"❌ '$tool_name'을(를) 찾았지만, 검증(예: --version)에 실패했습니다.\"\n exit 1\n fi\n ...\n}\n...\n```\n\n---\n\n### 단계 5: 각 도구의 검증 상태에 대한 명확한 로깅\n\n#### 1. 세분화된 및 최종 로깅 구현\n\n이 작업은 스크립트가 사용자에게 명확하고 실행 가능한 피드백을 제공하도록 보장합니다. `verify_essential_tool` 내부에서 `log_info`와 `log_error`를 사용하여 각 개별 도구의 상태를 보고합니다. 빈 `echo`는 가독성을 높이기 위해 간격을 두는 데 사용됩니다. 루프가 성공적으로 완료된 후, 전체 검증 프로세스가 통과했음을 확인하는 최종 요약 `log_info` 메시지가 출력됩니다.\n\n**파일**: `scripts/cpp_development_environment/verify.sh`\n\n```bash\n...\nverify_essential_tool() {\n local tool_name=\"$1\"\n echo\n log_info \"--- '$tool_name' 검증 중 ---\"\n ...\n log_info \"✅ '$tool_name'이(가) 설치 및 검증되었습니다.\"\n}\n\n# --- 주 검증 로직 ---\n\nfor tool in \"${COMMANDS_TO_VERIFY[@]}\"; do\n verify_essential_tool \"$tool\"\ndone\n\necho\nlog_info \"🎉 모든 필수 도구가 성공적으로 설치 및 검증되었습니다!\"\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n1. **성공 사례 검증**: 모든 도구가 설치되었는지 확인하기 위해 `setup.sh` 스크립트를 실행한 후, 검증 스크립트를 직접 실행합니다.\n\n ```bash\n # 스크립트 디렉터리로 이동\n cd scripts/cpp_development_environment\n\n # 검증 스크립트 실행\n bash verify.sh\n ```\n\n2. **실패 사례 검증**: 스크립트의 오류 처리를 확인하려면 도구가 없는 상황을 시뮬레이션합니다. 예를 들어, `git` 바이너리의 이름을 일시적으로 변경하고, 검증 스크립트를 실행한 다음, 다시 복원합니다.\n\n ```bash\n # 이 명령어는 sudo 권한이 필요합니다\n # git 바이너리를 일시적으로 숨김\n sudo mv /usr/bin/git /usr/bin/git_bak\n\n # 검증 스크립트를 실행하고 실패를 관찰\n bash scripts/cpp_development_environment/verify.sh\n\n # git 바이너리를 복원\n sudo mv /usr/bin/git_bak /usr/bin/git\n ```\n\n### 4.2. 예상 결과\n\n- **성공 사례**: 스크립트는 각 도구에 대한 일련의 성공 메시지를 출력하고 종료 코드 `0`으로 종료됩니다.\n\n ```\n --- 'clang' 검증 중 ---\n ✅ 'clang'이(가) 설치 및 검증되었습니다.\n\n --- 'clangd' 검증 중 ---\n ✅ 'clangd'이(가) 설치 및 검증되었습니다.\n \n ... (다른 모든 도구에 대한 출력) ...\n\n --- 'gh' 검증 중 ---\n ✅ 'gh'이(가) 설치 및 검증되었습니다.\n\n 🎉 모든 필수 도구가 성공적으로 설치 및 검증되었습니다!\n ```\n\n- **실패 사례**: 스크립트는 찾은 도구에 대한 성공 메시지를 출력한 다음, 첫 번째로 누락된 도구에 대한 오류 메시지를 출력하고 즉시 0이 아닌 종료 코드(예: `1`)로 종료됩니다.\n\n ```\n ...\n --- 'ninja' 검증 중 ---\n ✅ 'ninja'이(가) 설치 및 검증되었습니다.\n\n --- 'git' 검증 중 ---\n ❌ 'git'이(가) 설치되지 않았거나 PATH에 없습니다. 설정 스크립트를 실행해 주세요.\n ```\n","필수 도구의 존재 여부와 실행 가능성을 확인하고, 누락된 것이 있으면 오류를 내고 종료하는 독립 실행형 스크립트",[761,763,765,767,769],{"_24":762,"_83":39,"_84":356,"_85":61},"모든 필수 도구를 나열하는 배열 `COMMANDS_TO_VERIFY`",{"_24":764,"_83":39,"_84":356,"_85":88},"`verify_essential_tool` 헬퍼 함수",{"_24":766,"_83":39,"_84":356,"_85":91},"목록의 각 도구를 순회하며 검증하는 루프",{"_24":768,"_83":39,"_84":356,"_85":94},"공유 유틸리티의 `is_program_installed` 및 `verify_command` 사용",{"_24":770,"_83":39,"_84":356,"_85":97},"각 도구의 검증 상태에 대한 명확한 로깅","모든 필수 CLI 도구의 성공적인 설치를 프로그래밍 방식으로 확인하는 스크립트",{"_22":773,"_24":774,"_75":775,"_77":776,"_79":777,"_51":786,"_42":99},"task-1751002555324","GitHub Actions CI 워크플로","# 작업: GitHub Actions CI 워크플로\n\n> **에픽**: 지속적 통합 워크플로\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: macOS와 Linux에서 설정 스크립트 테스트를 자동화하는 CI 파이프라인.\n- **근거**: 프로젝트의 핵심 목표인 크로스플랫폼 호환성이 지속적으로 검증되도록 보장합니다. 이 워크플로는 모든 코드 변경 시 `setup.sh`와 `verify.sh`의 실행을 자동화하여, 회귀를 방지하고 두 대상 운영 체제 모두에서 환경 설정 프로세스의 무결성을 보장합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: 두 운영 체제를 위한 작업을 포함하는 GitHub Actions 워크플로를 정의하는 `ci.yml` 파일.\n- **명세**:\n - 워크플로 이름: `CI 검증`\n - 워크플로 트리거: `push` (main 브랜치), `pull_request` (main 브랜치), `workflow_dispatch`\n - 작업:\n - `verify-macos`: `macos-latest`에서 실행\n - `verify-linux`: `ubuntu-latest`에서 실행\n - 작업별 핵심 단계: `actions/checkout@v4`, `setup.sh` 실행, `verify.sh` 실행\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── .github/\n# └── workflows/\n# └── ci.yml <-- 신규\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n A[트리거: Push / PR / 수동] --> B{GitHub Actions Runner};\n B --> C[\"1\\. 코드 체크아웃
(actions/checkout@v4)\"];\n C --> D{\"2\\. setup.sh 실행
(macOS & Linux 작업)\"};\n D --> E[\"3\\. verify.sh 실행
(도구 설치 확인)\"];\n E --> F{워크플로
성공 / 실패};\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 3장에 있습니다.\n\n- [ ] `push`, `pull_request`, `workflow_dispatch`에 대한 워크플로 트리거.\n- [ ] `macos-latest`에서 실행되는 `verify-macos` 작업.\n- [ ] `ubuntu-latest`에서 실행되는 `verify-linux` 작업.\n- [ ] 각 작업 내에 코드 체크아웃, `setup.sh` 실행, `verify.sh` 실행 단계 포함.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 스크립트 기반 오케스트레이션\n- **관련 주요 구성 요소**:\n - **`.github/workflows/ci.yml`**: 생성될 구성 요소입니다. 전체 시스템의 자동화된 테스트 하네스 역할을 하는 지속적 통합 파이프라인을 정의합니다.\n - **`setup.sh`**: 주요 오케스트레이션 스크립트입니다. CI 워크플로는 이 구성 요소를 실행하여 깨끗한 러너에서 전체 환경 설정을 수행하고, 그 주요 기능을 테스트합니다.\n - **`verify.sh`**: 검증 스크립트입니다. CI 워크플로는 `setup.sh` 실행 후 이 구성 요소를 실행하여 모든 도구가 올바르게 설치되었는지 프로그래밍 방식으로 확인하며, 각 작업의 최종 성공 기준 역할을 합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `.github/workflows/ci.yml`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을', '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 워크플로 트리거 `push`, `pull_request`, `workflow_dispatch` 설정\n\n#### 1. 워크플로 이름 및 트리거 정의\n\n이 액션은 CI 워크플로가 언제 실행될지 설정합니다. `name` 키는 GitHub Actions UI에서 사람이 읽을 수 있는 식별자를 제공합니다. `on` 블록은 세 가지 트리거를 구성합니다: `main` 브랜치로의 `push`는 주 브랜치가 항상 검증되도록 보장하고, `main` 브랜치를 대상으로 하는 `pull_request`는 변경 사항이 병합되기 전에 검증하며, `workflow_dispatch`는 필요시 UI에서 수동으로 실행하여 온디맨드 테스트를 가능하게 합니다.\n\n**파일**: `.github/workflows/ci.yml`\n\n```yaml\n# 이 GitHub Actions 워크플로는 C++ 환경 설정 스크립트의 검증을 자동화합니다.\n# macOS와 Linux 모두에서 실행하여 크로스플랫폼 호환성을 보장합니다.\n\nname: CI 검증\n\non:\n # main 브랜치로의 푸시 시 실행\n push:\n branches: [\"main\"]\n # main 브랜치를 대상으로 하는 풀 리퀘스트 시 실행\n pull_request:\n branches: [\"main\"]\n\n # Actions 탭에서 이 워크플로를 수동으로 실행할 수 있도록 허용\n workflow_dispatch:\n\njobs:\n ...\n```\n\n---\n\n### 단계 2: `macos-latest`에서 실행되는 `verify-macos` 작업\n\n#### 1. `verify-macos` 작업 정의\n\n이 액션은 macOS에서의 설정 검증을 담당하는 작업을 생성합니다. `verify-macos`는 작업의 고유 식별자입니다. UI에 표시될 이름으로 `name: macOS에서 검증`이 설정되고, 최신 안정 버전의 macOS를 사용하는 GitHub 호스팅 러너에서 실행되도록 `runs-on: macos-latest`로 지정됩니다.\n\n**파일**: `.github/workflows/ci.yml`\n\n```yaml\n...\njobs:\n verify-macos:\n name: macOS에서 검증\n runs-on: macos-latest\n\n steps:\n ...\n```\n\n---\n\n### 단계 3: `ubuntu-latest`에서 실행되는 `verify-linux` 작업\n\n#### 1. `verify-linux` 작업 정의\n\n이 액션은 Linux에서의 설정 검증을 위한 병렬 작업을 생성합니다. `verify-linux`는 이 작업의 식별자입니다. 표시 목적으로 `name: Linux에서 검증`이 설정되고, 최신 안정 LTS 버전의 Ubuntu를 사용하는 GitHub 호스팅 러너에서 실행되도록 `runs-on: ubuntu-latest`로 지정됩니다.\n\n**파일**: `.github/workflows/ci.yml`\n\n```yaml\n...\n verify-macos:\n ...\n\n verify-linux:\n name: Linux에서 검증\n runs-on: ubuntu-latest\n\n steps:\n ...\n```\n\n---\n\n### 단계 4: 각 작업 내 코드 체크아웃, `setup.sh` 실행, `verify.sh` 실행 단계\n\n#### 1. `verify-macos` 작업의 단계 구현\n\n이 액션은 macOS 작업의 실행 순서를 정의합니다. 첫 번째 단계에서는 표준 `actions/checkout@v4` 액션을 사용하여 리포지토리의 코드를 러너에서 사용할 수 있도록 합니다. 후속 단계에서는 올바른 위치(`scripts/cpp_development_environment`)에서 `setup.sh` 및 `verify.sh` 스크립트를 실행하여 macOS에서의 전체 프로세스를 검증합니다.\n\n**파일**: `.github/workflows/ci.yml`\n\n```yaml\n...\n verify-macos:\n name: macOS에서 검증\n runs-on: macos-latest\n\n steps:\n - name: 리포지토리 체크아웃\n uses: actions/checkout@v4\n\n - name: 설정 스크립트 실행\n run: |\n cd scripts/cpp_development_environment\n bash setup.sh\n\n - name: 검증 스크립트 실행\n run: |\n cd scripts/cpp_development_environment\n bash verify.sh\n...\n```\n\n#### 2. `verify-linux` 작업의 단계 구현\n\n이 액션은 Linux 작업의 실행 순서를 정의합니다. macOS 작업 단계를 미러링하지만, 예비 단계인 `sudo apt-get update`를 포함합니다. 이는 `setup.sh`가 종속성을 설치하기 전에 `apt` 패키지 관리자가 사용 가능한 패키지의 최신 목록을 가지도록 보장하기 위해 Ubuntu 러너에서 필요한 선행 조건입니다.\n\n**파일**: `.github/workflows/ci.yml`\n\n```yaml\n...\n verify-linux:\n name: Linux에서 검증\n runs-on: ubuntu-latest\n\n steps:\n - name: 리포지토리 체크아웃\n uses: actions/checkout@v4\n\n - name: apt 패키지 목록 업데이트\n run: sudo apt-get update\n\n - name: 설정 스크립트 실행\n run: |\n cd scripts/cpp_development_environment\n bash setup.sh\n\n - name: 검증 스크립트 실행\n run: |\n cd scripts/cpp_development_environment\n bash verify.sh\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- `ci.yml` 파일의 정확성은 GitHub 플랫폼 내에서 그 실행을 관찰함으로써 검증됩니다.\n\n```bash\n# 1. 새 파일이 Git에 의해 추적되는지 확인\ngit add .github/workflows/ci.yml\n\n# 2. 새 워크플로 파일 커밋\ngit commit -m \"feat: add GitHub Actions CI workflow\"\n\n# 3. 변경 사항을 GitHub의 새 브랜치로 푸시\ngit push origin feat/add-ci-workflow\n\n# 4. `feat/add-ci-workflow`에서 `main`으로 풀 리퀘스트 열기\n# 5. GitHub UI에서 \"Actions\" 탭 또는 풀 리퀘스트의 \"Checks\" 섹션으로 이동\n```\n\n### 4.2. 예상 결과\n\n- 브랜치를 푸시하고 풀 리퀘스트를 생성하면 \"CI 검증\" 워크플로가 자동으로 트리거됩니다.\n- 워크플로 실행 시 \"macOS에서 검증\"과 \"Linux에서 검증\" 두 개의 작업이 표시됩니다.\n- 두 작업 모두 모든 단계를 성공적으로 실행하고 녹색 체크 표시와 함께 완료되어야 하며, 이는 설정 및 검증 스크립트가 두 운영 체제 모두에서 통과했음을 나타냅니다.\n","두 운영 체제 모두에 대한 작업을 포함하는 GitHub Actions 워크플로를 정의하는 `ci.yml` 파일",[778,780,782,784],{"_24":779,"_83":39,"_84":374,"_85":61},"`push`, `pull_request`, `workflow_dispatch`에 대한 워크플로 트리거",{"_24":781,"_83":39,"_84":374,"_85":88},"`macos-latest`에서 실행되는 `verify-macos` 작업",{"_24":783,"_83":39,"_84":374,"_85":91},"\"`ubuntu-latest`에서 실행되는 `verify-linux` 작업",{"_24":785,"_83":39,"_84":374,"_85":94},"각 작업 내에서 코드를 체크아웃하고, `setup.sh`를 실행하며, `verify.sh`를 실행하는 단계들","macOS 및 Linux에서 설정 스크립트 테스트를 자동화하는 CI 파이프라인",{"_22":788,"_24":789,"_75":790,"_77":791,"_79":792,"_51":803,"_42":99},"task-1751002606284","프로젝트 README 문서","# 작업: 프로젝트 README 문서\n\n> **에픽**: 프로젝트 문서화 및 README\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 프로젝트의 목적, 아키텍처, 사용 지침을 담은 포괄적인 루트 문서.\n- **근거**: `README.md` 파일은 모든 사용자와 기여자를 위한 주요 진입점 역할을 합니다. 명확하고 정확하며 포괄적인 문서는 사용자 채택, 지원 문의 감소, 다른 사람들이 자동화된 환경을 효과적으로 이해하고 사용하는 데 매우 중요합니다. 이는 프로젝트 설정 및 사용에 대한 단일 정보 소스입니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 사용자와 기여자를 위한 주요 진입점 역할을 하는 상세한 `README.md` 파일.\n- **명세**: 최종 `README.md` 파일은 다음의 검증된 섹션들을 포함해야 합니다:\n - 프로젝트의 목적과 범위를 상세히 설명하는 \"개요\" 섹션.\n - 문제 정의와 측정 가능한 성공 기준을 정의하는 \"프로젝트 목표\" 섹션.\n - 정확한 시스템 수준 다이어그램과 구성 요소 책임 표를 포함하는 \"아키텍처\" 섹션.\n - 명확하고, 전제 조건을 인지하며, 단계별 지침을 제공하는 \"설정 및 설치\" 섹션.\n - 설치 확인 방법과 샘플 프로젝트 실행 방법을 상세히 설명하는 \"사용 가이드\" 섹션.\n- **결과 파일 구조**\n\n```bash\n# ./\n└── README.md <-- 수정됨\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 README 문서에 따라 진행되는 사용자 여정을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n User[\"사용자\"] --> ReadMe[\"README.md 읽기\"]\n ReadMe --> UnderstandArch[\"프로젝트 목표 및
아키텍처 이해\"]\n ReadMe --> FollowSetup[\"설정 및 설치
지침 따르기\"]\n FollowSetup --> ExecuteSetup[\"bash setup.sh 실행\"]\n ExecuteSetup --> EnvReady[\"환경 구성 완료\"]\n EnvReady --> FollowUsage[\"사용 가이드 따르기\"]\n FollowUsage --> ExecuteVerify[\"bash verify.sh 실행\"]\n ExecuteVerify --> Confirmation[\"성공 확인 메시지 수신\"]\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 상세 구현 내용은 섹션 3에 있습니다.\n\n- [ ] 프로젝트의 목적과 범위를 명시하는 개요 섹션.\n- [ ] 프로젝트 목표와 성공 기준에 대한 섹션.\n- [ ] 다이어그램과 구성 요소 설명을 포함하는 아키텍처 섹션.\n- [ ] 명확한 설정 및 설치 지침.\n- [ ] 검증 및 샘플 프로젝트를 위한 사용 가이드.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 스크립트 기반 오케스트레이션\n- **관련 주요 구성 요소**:\n - `README.md` 문서는 전체 시스템 아키텍처를 정확하게 설명해야 합니다. 프로젝트 청사진에 정의된 모든 핵심 구성 요소의 역할을 참조하고 설명하여 문서가 구현과 동기화되도록 보장합니다. 이러한 구성 요소에는 `setup.sh`, `verify.sh`, `macos/scripts`, `linux/scripts`, `common/scripts`, `.github/workflows/ci.yml`이 포함됩니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `README.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 프로젝트의 목적과 범위를 명시하는 개요 섹션\n\n#### 1. 개요 섹션 검증\n\n`README.md`의 기존 \"개요\" 섹션을 검토합니다. 이 작업은 목적, 범위, 대상 독자 설명이 상위 수준의 프로젝트 정의와 완전히 일치하는지 확인하기 위한 것입니다. 불일치가 없는 한 변경 사항은 없을 것으로 예상됩니다.\n\n**파일**: `README.md`\n\n```markdown\n...\n## 0. 개요\n\n- **목적** 완전한 C++ 개발 환경을 빠르고 일관되며 자동화된 방식으로 설정하는 방법을 제공합니다.\n- **범위** macOS 및 Linux용 컴파일러, 빌드 도구, 린터, 편집기 구성 설치를 자동화합니다.\n- **대상 독자** 현대적이고 생산적인 작업 공간을 신속하게 부트스트랩하려는 C++ 개발자.\n...\n```\n\n---\n\n### 단계 2: 프로젝트 목표와 성공 기준에 대한 섹션\n\n#### 1. 목표 및 성공 기준 검증\n\n\"프로젝트 목표\" 섹션을 검토합니다. 이 작업은 README의 \"성공 기준\" 목록이 프로젝트 청사진의 `key_objectives`와 완벽하게 일치하는지 확인합니다. 이 일치는 프로젝트의 성공적인 실행이 무엇을 의미하는지 정의하는 데 매우 중요합니다.\n\n**파일**: `README.md`\n\n```markdown\n...\n### 2.2 성공 기준\n\n- **자동화된 설정**: 단일 명령어(`bash setup.sh`)로 모든 필수 도구를 성공적으로 설치하고 구성합니다.\n- **크로스 플랫폼**: 설정 프로세스가 macOS(Sonoma+)와 Linux(Ubuntu 22.04+) 모두에서 완벽하게 실행됩니다.\n- **멱등성 실행**: 스크립트를 여러 번 실행해도 기존 설정을 변경하거나 오류를 일으키지 않습니다.\n- **검증**: `verify.sh` 스크립트가 모든 구성 요소가 올바르게 설치되었고 시스템의 PATH에서 접근 가능한지 확인합니다.\n...\n```\n\n---\n\n### 단계 3: 다이어그램과 구성 요소 설명을 포함하는 아키텍처 섹션\n\n#### 1. 아키텍처 다이어그램 업데이트\n\n현재의 상위 수준 `graph TD` Mermaid 다이어그램을 프로젝트 명세서의 더 상세하고 정확한 시퀀스 다이어그램으로 교체합니다. 시퀀스 다이어그램은 오케스트레이터, 플랫폼별 스크립트, 공통 스크립트 간의 상호 작용을 더 명확하게 보여주며, 이는 \"모듈형 스크립트 기반 오케스트레이션\" 스타일에 필수적입니다.\n\n**파일**: `README.md`\n\n```markdown\n...\n### 3.1 상위 수준 다이어그램\n\n아래의 시퀀스 다이어그램은 설정에서 검증까지 사용자가 시작하는 일반적인 실행 흐름을 보여줍니다.\n\n```mermaid\n%%{ init: { \"sequence\": { \"htmlLabels\": true } } }%%\nsequenceDiagram\n participant User as \"사용자\"\n participant SetupSH as \"setup.sh
(오케스트레이터)\"\n participant PlatformScripts as \"플랫폼별 스크립트
(macOS/Linux)\"\n participant CommonScripts as \"공통 스크립트\"\n participant VerifySH as \"verify.sh
(검증기)\"\n\n User->>SetupSH: \"`bash setup.sh` 실행\"\n SetupSH->>SetupSH: \"OS 감지 (macOS 또는 Linux)\"\n SetupSH->>PlatformScripts: \"도구 설치 프로그램 호출 (예: `install_clang.sh`)\"\n PlatformScripts-->>SetupSH: \"설치 확인\"\n SetupSH->>CommonScripts: \"공통 모듈 호출 (예: `configure_vscode.sh`)\"\n CommonScripts-->>SetupSH: \"구성 확인\"\n SetupSH->>User: \"설정 완료 보고\"\n\n User->>VerifySH: \"`bash verify.sh` 실행\"\n VerifySH->>VerifySH: \"PATH에서 필수 CLI 도구 확인\"\n VerifySH-->>User: \"성공 또는 실패 보고\"\n```\n\n...\n\n```\n\n#### 2. 주요 구성 요소 표 검증\n\n\"주요 구성 요소\" 표를 검토하여 프로젝트 청사진에 정의된 모든 핵심 구성 요소와 그 책임이 올바르게 나열되었는지 확인합니다. 이 표는 시스템 각 부분의 역할을 이해하기 위한 빠른 참조 자료입니다.\n\n**파일**: `README.md`\n\n```markdown\n...\n### 3.2 주요 구성 요소\n\n| 구성 요소 | 책임 | 기술 |\n|---|---|---|\n| `setup.sh` | 주 진입점, OS 감지 및 다른 스크립트 오케스트레이션. | Bash |\n| `verify.sh` | 모든 도구가 설치되어 PATH에서 사용 가능한지 확인. | Bash |\n| `macos/` 스크립트 | Homebrew를 사용하여 macOS에 도구 설치 처리. | Bash |\n| `linux/` 스크립트 | `apt`를 사용하여 Linux에 도구 설치 처리. | Bash |\n| `common/` 스크립트 | VS Code 구성과 같은 OS에 독립적인 로직 포함. | Bash |\n| `assets/` | 템플릿 및 구성 파일 저장 (예: VS Code 설정). | JSON |\n...\n```\n\n---\n\n### 단계 4: 명확한 설정 및 설치 지침\n\n#### 1. 설정 지침 검증\n\n\"설정 및 설치\" 섹션을 검토합니다. 이 작업은 전제 조건이 올바른지, 그리고 명령어 순서가 프로젝트의 디렉터리 구조와 실행 진입점(`scripts/cpp_development_environment/setup.sh`)을 정확하게 반영하는지 확인합니다.\n\n**파일**: `README.md`\n\n```markdown\n...\n## 4. 설정 및 설치\n>\n> **전제 조건**\n>\n> - **macOS**: [Homebrew](https://brew.sh/)가 설치되어 있어야 합니다.\n> - **Linux**: `sudo` 권한이 필요합니다.\n> - 안정적인 인터넷 연결.\n\n```bash\n# 1) 리포지토리 복제\ngit clone https://github.com/movingChurch/readable-code-cpp-development-environment.git\ncd readable-code-cpp-development-environment\n\n# 2) 주 설정 스크립트 실행\ncd scripts/cpp_development_environment\nbash setup.sh\n```\n\n...\n\n```\n\n---\n\n### 단계 5: 검증 및 샘플 프로젝트를 위한 사용 가이드.\n\n#### 1. 사용 가이드 검증\n\n\"사용 가이드\" 섹션을 검토합니다. 이 작업은 `verify.sh` 스크립트 실행 및 샘플 프로젝트 실행 파일 위치 확인/실행 지침이 올바른지 확인하기 위한 것입니다. 제공된 경로는 성공적인 설정 후 사용자의 혼동을 방지하기 위해 정확해야 합니다.\n\n**파일**: `README.md`\n\n```markdown\n...\n## 5. 사용 가이드\n\n### 5.1 설치 확인\n\n설정 스크립트가 완료된 후, 검증 스크립트를 실행하여 모든 구성 요소가 올바르게 설치되었는지 확인할 수 있습니다.\n\n```bash\n# scripts/cpp_development_environment 디렉터리에서\nbash verify.sh\n```\n\n### 5.2 샘플 프로젝트\n\n\"Hello, World\" C++ 샘플 프로젝트가 홈 디렉터리 `~/cpp-sample`에 자동으로 생성되어 즉시 시작할 수 있도록 도와줍니다. 프로젝트는 이미 구성 및 빌드되었으며, 실행 파일을 실행하여 환경이 작동하는지 확인할 수 있습니다.\n\n```bash\n# 실행 파일은 build 디렉터리에 있습니다\n~/cpp-sample/build/hello_world\n```\n\n...\n\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n1. 수정된 `README.md` 파일을 마크다운 뷰어(예: GitHub 웹 인터페이스 또는 로컬 편집기 미리보기)를 사용하여 렌더링합니다.\n2. 이 문서의 `인수 조건`에 따라 각 섹션을 수동으로 검토합니다.\n3. \"아키텍처\" 섹션의 업데이트된 Mermaid 시퀀스 다이어그램이 올바르게 렌더링되고 프로그램 흐름을 명확하게 나타내는지 확인합니다.\n4. 깨끗한 테스트 환경(또는 macOS/Linux용 Docker 컨테이너)에서 \"설정 및 설치\" 섹션의 지침을 꼼꼼하게 따릅니다.\n5. 설정 스크립트가 완료된 후 \"사용 가이드\" 섹션의 명령을 실행합니다.\n\n### 4.2. 예상 결과\n\n- 렌더링된 `README.md`는 서식이 올바르게 지정되어야 하며, 다이어그램에 깨진 링크나 렌더링 오류가 없어야 합니다.\n- 설정 및 사용 명령어는 작성된 대로 실행했을 때 오류 없이 실행되어야 합니다.\n- `bash verify.sh`를 실행하면 성공 메시지가 출력되어야 합니다.\n- `~/cpp-sample/build/hello_world`를 실행하면 표준 출력에 \"Hello, World!\"가 인쇄되어야 합니다.\n- `README.md`를 따르는 전반적인 사용자 경험은 원활해야 하며, 완벽하게 작동하는 C++ 환경으로 이어져야 합니다.\n","사용자와 기여자를 위한 주요 진입점 역할을 하는 상세한 `README.md` 파일",[793,795,797,799,801],{"_24":794,"_83":39,"_84":392,"_85":61},"프로젝트의 목적과 범위를 기술하는 개요 섹션",{"_24":796,"_83":39,"_84":392,"_85":88},"프로젝트 목표 및 성공 기준에 대한 섹션",{"_24":798,"_83":39,"_84":392,"_85":91},"다이어그램과 구성 요소 설명이 포함된 아키텍처 섹션",{"_24":800,"_83":39,"_84":392,"_85":94},"명확한 설정 및 설치 지침",{"_24":802,"_83":39,"_84":392,"_85":97},"검증 및 샘플 프로젝트에 대한 사용 가이드","프로젝트의 목적, 아키텍처 및 사용 지침을 위한 포괄적인 루트 문서",[805,806],{"_28":29,"_26":501},{"_28":482,"_26":483},[808],{"_22":809,"_488":499,"_489":490,"_26":810,"_492":493,"_494":811,"_496":812,"_42":99},"d43cc6e0-456b-468d-9f80-59a4d20c2bc8",84150,"2025-06-27T06:00:00.000Z","2025-07-01T14:59:00.000Z",{"_22":814,"_24":815,"_26":483,"_28":482,"_30":31,"_32":33,"_34":35,"_36":816,"_38":817,"_40":818,"_484":977},"c08cd902-f1c9-400d-bdd3-4ccf980cd794","CodeCraft : 대규모 C++ 프로젝트를 위한 코딩 표준 수립 및 자동화 (Source Code)","2025-07-01T10:19:50.373Z",true,{"_22":33,"_24":25,"_42":43,"_44":31,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":39,"_56":57,"_58":59,"_60":61,"_62":61,"_63":819,"_70":820,"_478":479},[65,66,67,68,69],[821,828,835,842,849,856,862,870,877,884,891,898,905,912,919,926,933,940,947,954,961,969],{"_22":73,"_24":74,"_75":76,"_77":78,"_79":822,"_51":98,"_42":99},[823,824,825,826,827],{"_24":82,"_83":39,"_84":61,"_85":61},{"_24":87,"_83":39,"_84":61,"_85":88},{"_24":90,"_83":39,"_84":61,"_85":91},{"_24":93,"_83":39,"_84":61,"_85":94},{"_24":96,"_83":39,"_84":61,"_85":97},{"_22":101,"_24":102,"_75":103,"_77":104,"_79":829,"_51":116,"_42":99},[830,831,832,833,834],{"_24":107,"_83":39,"_84":88,"_85":61},{"_24":109,"_83":39,"_84":88,"_85":88},{"_24":111,"_83":39,"_84":88,"_85":91},{"_24":113,"_83":39,"_84":88,"_85":94},{"_24":115,"_83":39,"_84":88,"_85":97},{"_22":118,"_24":119,"_75":120,"_77":121,"_79":836,"_51":133,"_42":99},[837,838,839,840,841],{"_24":124,"_83":39,"_84":91,"_85":61},{"_24":126,"_83":39,"_84":91,"_85":88},{"_24":128,"_83":39,"_84":91,"_85":91},{"_24":130,"_83":39,"_84":91,"_85":94},{"_24":132,"_83":39,"_84":91,"_85":97},{"_22":135,"_24":136,"_75":137,"_77":138,"_79":843,"_51":150,"_42":99},[844,845,846,847,848],{"_24":141,"_83":39,"_84":94,"_85":61},{"_24":143,"_83":39,"_84":94,"_85":88},{"_24":145,"_83":39,"_84":94,"_85":91},{"_24":147,"_83":39,"_84":94,"_85":94},{"_24":149,"_83":39,"_84":94,"_85":97},{"_22":152,"_24":153,"_75":154,"_77":155,"_79":850,"_51":167,"_42":99},[851,852,853,854,855],{"_24":158,"_83":39,"_84":97,"_85":61},{"_24":160,"_83":39,"_84":97,"_85":88},{"_24":162,"_83":39,"_84":97,"_85":91},{"_24":164,"_83":39,"_84":97,"_85":94},{"_24":166,"_83":39,"_84":97,"_85":97},{"_22":169,"_24":170,"_75":171,"_77":172,"_79":857,"_51":183,"_42":99},[858,859,860,861],{"_24":175,"_83":39,"_84":176,"_85":61},{"_24":178,"_83":39,"_84":176,"_85":88},{"_24":180,"_83":39,"_84":176,"_85":91},{"_24":182,"_83":39,"_84":176,"_85":94},{"_22":185,"_24":186,"_75":187,"_77":188,"_79":863,"_51":203,"_42":99},[864,865,866,867,868,869],{"_24":191,"_83":39,"_84":192,"_85":61},{"_24":194,"_83":39,"_84":192,"_85":88},{"_24":196,"_83":39,"_84":192,"_85":91},{"_24":198,"_83":39,"_84":192,"_85":94},{"_24":200,"_83":39,"_84":192,"_85":97},{"_24":202,"_83":39,"_84":192,"_85":176},{"_22":205,"_24":206,"_75":207,"_77":208,"_79":871,"_51":221,"_42":99},[872,873,874,875,876],{"_24":211,"_83":39,"_84":212,"_85":61},{"_24":214,"_83":39,"_84":212,"_85":88},{"_24":216,"_83":39,"_84":212,"_85":91},{"_24":218,"_83":39,"_84":212,"_85":94},{"_24":220,"_83":39,"_84":212,"_85":97},{"_22":223,"_24":224,"_75":225,"_77":226,"_79":878,"_51":239,"_42":99},[879,880,881,882,883],{"_24":229,"_83":39,"_84":230,"_85":61},{"_24":232,"_83":39,"_84":230,"_85":88},{"_24":234,"_83":39,"_84":230,"_85":91},{"_24":236,"_83":39,"_84":230,"_85":94},{"_24":238,"_83":39,"_84":230,"_85":97},{"_22":241,"_24":242,"_75":243,"_77":244,"_79":885,"_51":257,"_42":99},[886,887,888,889,890],{"_24":247,"_83":39,"_84":248,"_85":61},{"_24":250,"_83":39,"_84":248,"_85":88},{"_24":252,"_83":39,"_84":248,"_85":91},{"_24":254,"_83":39,"_84":248,"_85":94},{"_24":256,"_83":39,"_84":248,"_85":97},{"_22":259,"_24":260,"_75":261,"_77":262,"_79":892,"_51":275,"_42":99},[893,894,895,896,897],{"_24":265,"_83":39,"_84":266,"_85":61},{"_24":268,"_83":39,"_84":266,"_85":88},{"_24":270,"_83":39,"_84":266,"_85":91},{"_24":272,"_83":39,"_84":266,"_85":94},{"_24":274,"_83":39,"_84":266,"_85":97},{"_22":277,"_24":278,"_75":279,"_77":280,"_79":899,"_51":293,"_42":99},[900,901,902,903,904],{"_24":283,"_83":39,"_84":284,"_85":61},{"_24":286,"_83":39,"_84":284,"_85":88},{"_24":288,"_83":39,"_84":284,"_85":91},{"_24":290,"_83":39,"_84":284,"_85":94},{"_24":292,"_83":39,"_84":284,"_85":97},{"_22":295,"_24":296,"_75":297,"_77":298,"_79":906,"_51":311,"_42":99},[907,908,909,910,911],{"_24":301,"_83":39,"_84":302,"_85":61},{"_24":304,"_83":39,"_84":302,"_85":88},{"_24":306,"_83":39,"_84":302,"_85":91},{"_24":308,"_83":39,"_84":302,"_85":94},{"_24":310,"_83":39,"_84":302,"_85":97},{"_22":313,"_24":314,"_75":315,"_77":316,"_79":913,"_51":329,"_42":99},[914,915,916,917,918],{"_24":319,"_83":39,"_84":320,"_85":61},{"_24":322,"_83":39,"_84":320,"_85":88},{"_24":324,"_83":39,"_84":320,"_85":91},{"_24":326,"_83":39,"_84":320,"_85":94},{"_24":328,"_83":39,"_84":320,"_85":97},{"_22":331,"_24":332,"_75":333,"_77":334,"_79":920,"_51":347,"_42":99},[921,922,923,924,925],{"_24":337,"_83":39,"_84":338,"_85":61},{"_24":340,"_83":39,"_84":338,"_85":88},{"_24":342,"_83":39,"_84":338,"_85":91},{"_24":344,"_83":39,"_84":338,"_85":94},{"_24":346,"_83":39,"_84":338,"_85":97},{"_22":349,"_24":350,"_75":351,"_77":352,"_79":927,"_51":365,"_42":99},[928,929,930,931,932],{"_24":355,"_83":39,"_84":356,"_85":61},{"_24":358,"_83":39,"_84":356,"_85":88},{"_24":360,"_83":39,"_84":356,"_85":91},{"_24":362,"_83":39,"_84":356,"_85":94},{"_24":364,"_83":39,"_84":356,"_85":97},{"_22":367,"_24":368,"_75":369,"_77":370,"_79":934,"_51":383,"_42":99},[935,936,937,938,939],{"_24":373,"_83":39,"_84":374,"_85":61},{"_24":376,"_83":39,"_84":374,"_85":88},{"_24":378,"_83":39,"_84":374,"_85":91},{"_24":380,"_83":39,"_84":374,"_85":94},{"_24":382,"_83":39,"_84":374,"_85":97},{"_22":385,"_24":386,"_75":387,"_77":388,"_79":941,"_51":401,"_42":99},[942,943,944,945,946],{"_24":391,"_83":39,"_84":392,"_85":61},{"_24":394,"_83":39,"_84":392,"_85":88},{"_24":396,"_83":39,"_84":392,"_85":91},{"_24":398,"_83":39,"_84":392,"_85":94},{"_24":400,"_83":39,"_84":392,"_85":97},{"_22":403,"_24":404,"_75":405,"_77":406,"_79":948,"_51":419,"_42":99},[949,950,951,952,953],{"_24":409,"_83":39,"_84":410,"_85":61},{"_24":412,"_83":39,"_84":410,"_85":88},{"_24":414,"_83":39,"_84":410,"_85":91},{"_24":416,"_83":39,"_84":410,"_85":94},{"_24":418,"_83":39,"_84":410,"_85":97},{"_22":421,"_24":422,"_75":423,"_77":424,"_79":955,"_51":437,"_42":99},[956,957,958,959,960],{"_24":427,"_83":39,"_84":428,"_85":61},{"_24":430,"_83":39,"_84":428,"_85":88},{"_24":432,"_83":39,"_84":428,"_85":91},{"_24":434,"_83":39,"_84":428,"_85":94},{"_24":436,"_83":39,"_84":428,"_85":97},{"_22":439,"_24":440,"_75":441,"_77":442,"_79":962,"_51":457,"_42":99},[963,964,965,966,967,968],{"_24":445,"_83":39,"_84":446,"_85":61},{"_24":448,"_83":39,"_84":446,"_85":88},{"_24":450,"_83":39,"_84":446,"_85":91},{"_24":452,"_83":39,"_84":446,"_85":94},{"_24":454,"_83":39,"_84":446,"_85":97},{"_24":456,"_83":39,"_84":446,"_85":176},{"_22":459,"_24":460,"_75":461,"_77":462,"_79":970,"_51":477,"_42":99},[971,972,973,974,975,976],{"_24":465,"_83":39,"_84":466,"_85":61},{"_24":468,"_83":39,"_84":466,"_85":88},{"_24":470,"_83":39,"_84":466,"_85":91},{"_24":472,"_83":39,"_84":466,"_85":94},{"_24":474,"_83":39,"_84":466,"_85":97},{"_24":476,"_83":39,"_84":466,"_85":176},[978],{"_22":979,"_488":814,"_489":490,"_26":980,"_492":493,"_494":495,"_496":497,"_42":99},"9f6554bf-b9f8-42e6-ab61-5861120812dc",42500,{"_22":982,"_24":983,"_26":483,"_28":482,"_30":31,"_32":502,"_34":984,"_36":985,"_38":817,"_40":986,"_484":1106},"6e88e7ee-a35e-45ad-bc5f-49de38765d5f","C++ DevEnv Accelerator : 크로스플랫폼 C++ 환경 자동화 (Source Code)","2025-06-25T07:19:37.512Z","2025-06-27T07:13:22.935Z",{"_22":502,"_24":500,"_42":506,"_44":31,"_45":46,"_47":507,"_49":508,"_51":509,"_53":510,"_55":39,"_56":511,"_58":59,"_60":61,"_62":61,"_63":987,"_70":988,"_478":804},[513,514,515,516],[989,996,1003,1010,1017,1023,1029,1035,1040,1046,1052,1058,1065,1072,1079,1086,1093,1099],{"_22":519,"_24":278,"_75":520,"_77":521,"_79":990,"_51":533,"_42":99},[991,992,993,994,995],{"_24":524,"_83":39,"_84":61,"_85":61},{"_24":526,"_83":39,"_84":61,"_85":88},{"_24":528,"_83":39,"_84":61,"_85":91},{"_24":530,"_83":39,"_84":61,"_85":94},{"_24":532,"_83":39,"_84":61,"_85":97},{"_22":535,"_24":536,"_75":537,"_77":538,"_79":997,"_51":550,"_42":99},[998,999,1000,1001,1002],{"_24":541,"_83":39,"_84":88,"_85":61},{"_24":543,"_83":39,"_84":88,"_85":88},{"_24":545,"_83":39,"_84":88,"_85":91},{"_24":547,"_83":39,"_84":88,"_85":94},{"_24":549,"_83":39,"_84":88,"_85":97},{"_22":552,"_24":553,"_75":554,"_77":555,"_79":1004,"_51":567,"_42":99},[1005,1006,1007,1008,1009],{"_24":558,"_83":39,"_84":91,"_85":61},{"_24":560,"_83":39,"_84":91,"_85":88},{"_24":562,"_83":39,"_84":91,"_85":91},{"_24":564,"_83":39,"_84":91,"_85":94},{"_24":566,"_83":39,"_84":91,"_85":97},{"_22":569,"_24":570,"_75":571,"_77":572,"_79":1011,"_51":584,"_42":99},[1012,1013,1014,1015,1016],{"_24":575,"_83":39,"_84":94,"_85":61},{"_24":577,"_83":39,"_84":94,"_85":88},{"_24":579,"_83":39,"_84":94,"_85":91},{"_24":581,"_83":39,"_84":94,"_85":94},{"_24":583,"_83":39,"_84":94,"_85":97},{"_22":586,"_24":587,"_75":588,"_77":589,"_79":1018,"_51":599,"_42":99},[1019,1020,1021,1022],{"_24":592,"_83":39,"_84":97,"_85":61},{"_24":594,"_83":39,"_84":97,"_85":88},{"_24":596,"_83":39,"_84":97,"_85":91},{"_24":598,"_83":39,"_84":97,"_85":94},{"_22":601,"_24":602,"_75":603,"_77":604,"_79":1024,"_51":614,"_42":99},[1025,1026,1027,1028],{"_24":607,"_83":39,"_84":176,"_85":61},{"_24":609,"_83":39,"_84":176,"_85":88},{"_24":611,"_83":39,"_84":176,"_85":91},{"_24":613,"_83":39,"_84":176,"_85":94},{"_22":616,"_24":617,"_75":618,"_77":619,"_79":1030,"_51":628,"_42":99},[1031,1032,1033,1034],{"_24":622,"_83":39,"_84":192,"_85":61},{"_24":624,"_83":39,"_84":192,"_85":88},{"_24":611,"_83":39,"_84":192,"_85":91},{"_24":627,"_83":39,"_84":192,"_85":94},{"_22":630,"_24":631,"_75":632,"_77":633,"_79":1036,"_51":641,"_42":99},[1037,1038,1039],{"_24":636,"_83":39,"_84":212,"_85":61},{"_24":638,"_83":39,"_84":212,"_85":88},{"_24":640,"_83":39,"_84":212,"_85":91},{"_22":643,"_24":644,"_75":645,"_77":646,"_79":1041,"_51":656,"_42":99},[1042,1043,1044,1045],{"_24":649,"_83":39,"_84":230,"_85":61},{"_24":651,"_83":39,"_84":230,"_85":88},{"_24":653,"_83":39,"_84":230,"_85":91},{"_24":655,"_83":39,"_84":230,"_85":94},{"_22":658,"_24":659,"_75":660,"_77":661,"_79":1047,"_51":671,"_42":99},[1048,1049,1050,1051],{"_24":664,"_83":39,"_84":248,"_85":61},{"_24":666,"_83":39,"_84":248,"_85":88},{"_24":668,"_83":39,"_84":248,"_85":91},{"_24":670,"_83":39,"_84":248,"_85":94},{"_22":673,"_24":674,"_75":675,"_77":676,"_79":1053,"_51":686,"_42":99},[1054,1055,1056,1057],{"_24":679,"_83":39,"_84":266,"_85":61},{"_24":681,"_83":39,"_84":266,"_85":88},{"_24":683,"_83":39,"_84":266,"_85":91},{"_24":685,"_83":39,"_84":266,"_85":94},{"_22":688,"_24":689,"_75":690,"_77":691,"_79":1059,"_51":703,"_42":99},[1060,1061,1062,1063,1064],{"_24":694,"_83":39,"_84":284,"_85":61},{"_24":696,"_83":39,"_84":284,"_85":88},{"_24":698,"_83":39,"_84":284,"_85":91},{"_24":700,"_83":39,"_84":284,"_85":94},{"_24":702,"_83":39,"_84":284,"_85":97},{"_22":705,"_24":706,"_75":707,"_77":708,"_79":1066,"_51":720,"_42":99},[1067,1068,1069,1070,1071],{"_24":711,"_83":39,"_84":302,"_85":61},{"_24":713,"_83":39,"_84":302,"_85":88},{"_24":715,"_83":39,"_84":302,"_85":91},{"_24":717,"_83":39,"_84":302,"_85":94},{"_24":719,"_83":39,"_84":302,"_85":97},{"_22":722,"_24":723,"_75":724,"_77":725,"_79":1073,"_51":737,"_42":99},[1074,1075,1076,1077,1078],{"_24":728,"_83":39,"_84":320,"_85":61},{"_24":730,"_83":39,"_84":320,"_85":88},{"_24":732,"_83":39,"_84":320,"_85":91},{"_24":734,"_83":39,"_84":320,"_85":94},{"_24":736,"_83":39,"_84":320,"_85":97},{"_22":739,"_24":740,"_75":741,"_77":742,"_79":1080,"_51":754,"_42":99},[1081,1082,1083,1084,1085],{"_24":745,"_83":39,"_84":338,"_85":61},{"_24":747,"_83":39,"_84":338,"_85":88},{"_24":749,"_83":39,"_84":338,"_85":91},{"_24":751,"_83":39,"_84":338,"_85":94},{"_24":753,"_83":39,"_84":338,"_85":97},{"_22":756,"_24":757,"_75":758,"_77":759,"_79":1087,"_51":771,"_42":99},[1088,1089,1090,1091,1092],{"_24":762,"_83":39,"_84":356,"_85":61},{"_24":764,"_83":39,"_84":356,"_85":88},{"_24":766,"_83":39,"_84":356,"_85":91},{"_24":768,"_83":39,"_84":356,"_85":94},{"_24":770,"_83":39,"_84":356,"_85":97},{"_22":773,"_24":774,"_75":775,"_77":776,"_79":1094,"_51":786,"_42":99},[1095,1096,1097,1098],{"_24":779,"_83":39,"_84":374,"_85":61},{"_24":781,"_83":39,"_84":374,"_85":88},{"_24":783,"_83":39,"_84":374,"_85":91},{"_24":785,"_83":39,"_84":374,"_85":94},{"_22":788,"_24":789,"_75":790,"_77":791,"_79":1100,"_51":803,"_42":99},[1101,1102,1103,1104,1105],{"_24":794,"_83":39,"_84":392,"_85":61},{"_24":796,"_83":39,"_84":392,"_85":88},{"_24":798,"_83":39,"_84":392,"_85":91},{"_24":800,"_83":39,"_84":392,"_85":94},{"_24":802,"_83":39,"_84":392,"_85":97},[1107],{"_22":1108,"_488":982,"_489":1109,"_26":980,"_492":1110,"_494":1111,"_496":812,"_42":99},"127b40e9-4362-4713-8b11-b6307b173ea6","early",99,"2025-06-27T00:20:00.000Z",{"_22":1113,"_24":1114,"_26":1115,"_28":482,"_30":31,"_32":1116,"_34":1117,"_36":1118,"_38":817,"_40":1119,"_484":1505},"d2d44df5-e50d-4fae-9551-0b5fb1ae03fb","C++ Ultimate CMake Template : 최신 CMake와 품질 도구를 활용한 C++ 프로젝트 설정 자동화 (Source Code)",300000,"8a3ee045-41a4-4c1c-9792-c8bf6dac4e9a","2025-06-27T07:16:16.971Z","2025-06-27T07:16:16.947Z",{"_22":1116,"_24":1120,"_42":1121,"_44":31,"_45":46,"_47":1122,"_49":1123,"_51":1124,"_53":1125,"_55":39,"_56":1126,"_58":59,"_60":61,"_62":61,"_63":1127,"_70":1132,"_478":1501},"C++ Ultimate CMake Template : 최신 CMake와 품질 도구를 활용한 C++ 프로젝트 설정 자동화","새로운 C++ 프로젝트마다 빌드 시스템과 품질 도구를 설정하느라 몇 주씩 낭비하지 마세요. 이 프로덕션 수준의 템플릿은 모듈식 C++20 기반 환경과 함께 포맷팅, 정적 분석, 테스트 자동화 기능을 즉시 제공합니다. 보일러플레이트와 씨름하는 대신, 첫날부터 고품질 애플리케이션 코드 작성에 집중하세요.","C++ 프로젝트를 시작할 때마다 처음 며칠, 때로는 몇 주 동안 CMake와 씨름하고, 린터, 포매터, 테스트 프레임워크를 설정하고, 이 모든 것이 제대로 작동하도록 애쓰느라 시간을 허비한 적이 셀 수 없이 많습니다. 아이디어와 실제로 만들고 싶었던 멋진 C++ 코드를 *작성하는* 것 사이에 놓인 상용구 코드의 산더미 같은 반복적인 좌절감이었습니다. 새로운 프로젝트를 시작할 때마다 바퀴를 다시 발명하는 기분이었고, 프로젝트 간의 불일치는 장기적인 유지보수를 골치 아프게 만들었습니다.\n\n특히 힘들었던 설정 단계를 거친 후 전환점을 맞이했습니다. 이 초기 마찰이 단순히 짜증나는 것이 아니라 생산성을 적극적으로 저해하고, 때로는 *무언가* 작동하게 만들기 위해 코드 품질에 타협을 초래한다는 것을 깨달았습니다. 더 나은 방법이 분명히 있을 거라 생각했습니다.\n\n그래서 **확실한 C++ 프로젝트 템플릿**을 만들기 위해 미리 시간을 투자하기로 결정했습니다. 저뿐만 아니라 다른 사람들도 바로 시작할 수 있는 것을 만드는 것이 목표였습니다. 이해하고 확장하기 쉬운 모듈식 CMake 구조에 중점을 두었고, 매일 사용하는 모든 필수 도구(예: `clang-tidy`, `clang-format`, Catch2, Doxygen, `gcovr`)를 통합했으며, 모든 것을 철저히 문서화했습니다. *기본적으로* 가독성 있고 유지보수 가능한 코드를 장려하는 기반을 원했습니다.\n\n그 결과가 바로 이 템플릿입니다. 수많은 시간을 절약해 주었고, C++ 코드베이스의 일관성과 품질을 향상시켰으며, 솔직히 새로운 프로젝트를 시작하는 것을 다시 흥미롭게 만들었습니다. 이제 각 프로젝트의 고유한 과제에 집중할 수 있게 되었고, 기본적인 토대가 견고하고 신뢰할 수 있다는 것을 압니다. 만약 여러분도 프로젝트 초기 설정의 고통을 느껴보셨다면, 이 템플릿이 여러분의 C++ 개발 경험 또한 변화시킬 수 있다고 진심으로 믿습니다. **한번 사용해 보시고 아이디어를 얼마나 더 빨리 현실로 만들 수 있는지 확인해 보세요!**\n ","# 프로젝트 명세서: readable-code-cpp-project-template\n\n## 1. 프로젝트 정의\n\n### 1.1. 주요 목표\n\n- 모듈식 빌드 시스템과 자동화된 도구를 통해 개발자 생산성과 코드 품질을 향상시키는 포괄적이고 사전 구성된 C++ 프로젝트 템플릿을 제공하는 것.\n\n### 1.2. 핵심 기능\n\n- 새로운 C++ 프로젝트를 위한 견고하고 사전 구성된 기반\n- 모듈식이며 가독성 높고 확장 가능한 CMake 아키텍처\n- 자동화된 코드 품질 관리 (포맷팅, 정적 분석, 테스트)\n- 최신 C++20 및 CMake (3.15+) 모범 사례 통합\n- FetchContent 및 Git 서브모듈을 사용한 유연한 의존성 관리\n\n### 1.3. 결과물\n\n- Git에 완전하고 재사용 가능한 C++ 프로젝트 템플릿 저장소\n- 선언적 인터페이스 함수를 갖춘 계층형 CMake 빌드 시스템\n- 포맷팅, 정적 분석, 문서를 위한 통합 개발자 도구 타겟\n- 전체 테스트 스위트를 포함한 데모 라이브러리 및 실행 파일\n- 코딩 표준 및 프로젝트 규칙에 대한 포괄적인 문서\n\n## 2. 시스템 아키텍처\n\n### 2.1. 아키텍처 패턴\n\n- **계층형 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿**: 이 아키텍처는 실행 가능한 애플리케이션이 아니라 재사용 가능한 프로젝트 스캐폴딩입니다. 핵심은 계층으로 구조화된 CMake 빌드 시스템으로, 저수준 유틸리티 함수와 주 빌드 스크립트에서 사용되는 고수준 선언적 인터페이스를 분리합니다. 이는 명확성과 유지보수성을 증진시킵니다.\n\n### 2.2. 의존성 다이어그램\n\n- 프로젝트 에픽 간의 빌드 타임 의존성을 시각화한 다이어그램입니다. 거버넌스 및 CMake 유틸리티를 위한 기본 에픽이 기반을 형성하며, 그 위에 고수준 추상화, 애플리케이션 코드, 테스트가 구축됩니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n ProjectGovernance[\"프로젝트 거버넌스 및
코딩 표준\"]\n FoundationalCMake[\"기반 CMake
유틸리티 및 모듈\"]\n \n FoundationalCMake --> HighLevelCMake[\"고수준 CMake
인터페이스 모듈\"]\n FoundationalCMake --> DependencyIntegration[\"의존성 통합
프레임워크\"]\n \n HighLevelCMake --> TopLevelOrchestration[\"최상위 빌드
오케스트레이션\"]\n DependencyIntegration --> TopLevelOrchestration\n \n TopLevelOrchestration --> CoreMathLibrary[\"코어 수학 라이브러리
구현\"]\n \n CoreMathLibrary --> ExampleApp[\"예제 애플리케이션
실행 파일\"]\n CoreMathLibrary --> TestSuite[\"테스트 스위트 및
코드 커버리지\"]\n CoreMathLibrary --> AutomatedTooling[\"자동화된 개발자
도구\"]\n```\n\n### 2.3. 프로그램 흐름\n\n- 이 다이어그램은 개발자 명령으로 시작되어 CMake 빌드 시스템에 의해 조율되는 프로젝트의 빌드 타임 데이터 흐름을 보여줍니다.\n\n```mermaid\n%%{ init: { \"sequence\": { \"htmlLabels\": true } } }%%\nsequenceDiagram\n participant Dev as \"개발자\"\n participant TopLevelCMake as \"최상위 CMakeLists.txt\"\n participant CMakeModules as \"CMake 인터페이스 모듈\"\n participant BuildTools as \"빌드 도구 (컴파일러, CTest 등)\"\n\n Dev->>TopLevelCMake: \"`cmake` 명령어 실행\"\n TopLevelCMake->>CMakeModules: \"`configure_*` 함수 호출\"\n CMakeModules-->>TopLevelCMake: \"빌드 타겟(라이브러리, 실행 파일, 도구) 정의\"\n TopLevelCMake-->>BuildTools: \"빌드 시스템 파일(예: Makefiles) 생성\"\n \n Dev->>BuildTools: \"빌드/테스트 명령어 실행 (예: `make`, `ctest`)\"\n BuildTools->>BuildTools: \"소스 컴파일, 테스트 실행, 도구 실행\"\n BuildTools-->>Dev: \"빌드/테스트 결과 보고\"\n```\n\n### 2.4. 컴포넌트별 역할 및 책임\n\n- **모듈식 CMake 빌드 시스템**\n - **역할:** 빌드 자동화, 의존성 관리, 도구 통합.\n - **상호작용:** C++ 소스 파일을 사용하고 외부 도구(컴파일러, 링커, CTest)를 호출하여 라이브러리, 실행 파일, 보고서를 생성하며 전체 빌드 프로세스를 조율합니다.\n\n- **C++ 예제 라이브러리**\n - **역할:** 깔끔한 public/private 인터페이스를 가진 모듈식 라이브러리.\n - **상호작용:** 다른 컴포넌트(예: 실행 파일)에서 사용할 헤더 파일(`include/`)과 빌드 시스템에서 컴파일할 소스 파일(`source/`)을 제공합니다.\n\n- **테스트 스위트**\n - **역할:** Catch2와 CTest를 통한 단위 및 통합 테스트.\n - **상호작용:** C++ 예제 라이브러리의 public 인터페이스를 사용하여 정확성을 검증합니다. CTest에 의해 실행되며, 결과 보고 및 커버리지 데이터를 생성합니다.\n\n- **품질 보증 툴체인**\n - **역할:** 정적 분석, 코드 포맷팅, 문서 생성.\n - **상호작용:** C++ 소스 파일과 설정 파일(`.clang-tidy`, `.clang-format`, `Doxyfile`)을 사용하여 분석 보고서를 생성하고, 코드를 재포맷하며, HTML/LaTeX 문서를 생성합니다.\n\n- **의존성 관리 시스템**\n - **역할:** 외부 의존성의 자동 발견 및 구성.\n - **상호작용:** CMake 빌드 시스템에 의해 관리되며, Git Submodules와 FetchContent를 사용하여 라이브러리(예: spdlog, Catch2)를 가져오고, 프로젝트의 자체 라이브러리 및 실행 파일에 연결할 수 있도록 해당 타겟을 제공합니다.\n\n### 2.5. 기술 스택\n\n- **언어:**\n - C++20\n - CMake\n - Shell\n- **프레임워크:**\n - Catch2\n\n## 3. 디렉터리 구조\n\n### 3.1. 개요\n\n- 디렉터리 구조는 빌드 시스템 로직, 외부 의존성, public 인터페이스, private 구현, 테스트 코드 간의 명확한 관심사 분리를 강제하도록 설계되었습니다.\n\n### 3.2. 폴더 트리\n\n```bash\n/\n├── .clang-format\n├── .clang-tidy\n├── .gitmodules\n├── CMakeLists.txt\n├── assets/\n│ └── doxyfile.in\n├── cmake/\n│ ├── common/\n│ ├── interface/\n│ └── ...\n├── dependencies/\n│ ├── externals/\n│ └── internals/\n├── documents/\n│ └── guidelines/\n├── executables/\n│ └── print_math_result.cpp\n├── include/\n│ └── example/\n│ └── math/\n├── source/\n│ └── math/\n├── tests/\n│ ├── integration/\n│ └── unit/\n└── README.md\n```\n\n## 4. 실행 계획\n\n실행 계획은 프로젝트를 기초부터 구축하는 순서로 구성됩니다. 먼저 기본적인 거버넌스와 코딩 표준을 수립하는 것부터 시작합니다. 다음으로, 저수준 유틸리티에서 시작하여 고수준 인터페이스로 진행하며 계층형 CMake 빌드 시스템을 구현합니다. 빌드 시스템이 준비되면 의존성을 통합하고, 이어서 코어 라이브러리, 예제 애플리케이션, 테스트 스위트를 구현합니다. 계획은 완전히 구축된 프로젝트를 활용하는 자동화된 개발자 도구를 추가하는 것으로 마무리됩니다.\n\n---\n\n### 에픽 1: 프로젝트 거버넌스 및 코딩 표준\n\n- **목표:** 모든 C++ 및 CMake 개발 전반에 걸쳐 코드 품질과 일관성을 위한 기본적인 프로젝트 표준 및 가이드라인을 수립합니다.\n- **태스크**\n - **1.1 C++ 코드 포맷팅 표준 구성:** `.clang-format` 설정 파일을 생성하여 C++ 코드 포맷팅 표준을 정의합니다.\n - **1.2 정적 분석 규칙 구성:** `.clang-tidy` 설정 파일을 생성하여 버그 예방을 위한 정적 분석 검사 집합을 정의합니다.\n - **1.3 CMake 코딩 스타일 가이드:** 포괄적인 마크다운 문서에 CMake 코딩 표준과 모범 사례를 정의합니다.\n - **1.4 Doxygen 문서 표준:** C++ 코드에서 Doxygen 주석을 작성하기 위한 명확한 가이드라인을 수립합니다.\n - **1.5 테스트 스위트 코딩 스타일 가이드:** Catch2 프레임워크를 사용하여 단위 및 통합 테스트를 작성하기 위한 표준을 명시합니다.\n\n---\n\n### 에픽 2: 기반 CMake 유틸리티 및 모듈\n\n- **목표:** 빌드 시스템 로직의 핵심을 이루는 저수준의 재사용 가능한 CMake 유틸리티 함수를 구현합니다.\n- **태스크**\n - **2.1 공통 CMake 유틸리티 함수:** 문자열 조작 및 하위 디렉터리 처리를 위한 범용 헬퍼 함수 집합을 생성합니다.\n - **2.2 프로젝트 전역 구성 모듈:** 전역 프로젝트 경로, 컴파일러 플래그, 빌드 설정을 초기화하는 CMake 모듈을 개발합니다.\n - **2.3 타겟 속성 헬퍼 모듈:** 빌드 타겟에 표준 컴파일 속성을 적용하고 의존성을 연결하기 위한 재사용 가능한 CMake 함수를 생성합니다.\n\n---\n\n### 에픽 3: 고수준 CMake 인터페이스 모듈\n\n- **목표:** 주 빌드 스크립트를 위한 깔끔하고 간단한 API를 제공하는 고수준의 선언적 `configure_*` 함수를 구현합니다.\n- **태스크**\n - **3.1 고수준 프로젝트 구성 인터페이스:** 전체 프로젝트 수준의 설정을 조율하는 단일 `configure_project` 함수를 생성합니다.\n - **3.2 라이브러리 및 실행 파일 구성 인터페이스:** 빌드 타겟을 정의하기 위한 선언적 `configure_library` 및 `configure_executable` 함수를 개발합니다.\n - **3.3 테스트 스위트 및 커버리지 구성 인터페이스:** 전체 테스트 및 코드 커버리지 환경을 설정하는 `configure_tests` 함수를 생성합니다.\n - **3.4 개발자 도구 구성 인터페이스:** 포맷팅, 정적 분석, 문서를 위한 사용자 정의 빌드 타겟을 정의하는 고수준 함수를 생성합니다.\n\n---\n\n### 에픽 4: 의존성 통합 프레임워크\n\n- **목표:** 외부 라이브러리 의존성을 구성하고 통합하여 CMake 시스템 내에서 발견 가능한 빌드 타겟으로 사용할 수 있게 합니다.\n- **태스크**\n - **4.1 Git 서브모듈을 통한 spdlog 통합:** Git 서브모듈을 사용하여 spdlog 라이브러리를 버전 관리되는 의존성으로 통합합니다.\n - **4.2 FetchContent를 통한 Catch2 통합:** FetchContent를 사용하여 구성 시 다운로드되는 의존성으로 Catch2 테스트 프레임워크를 통합합니다.\n\n---\n\n### 에픽 5: 최상위 빌드 오케스트레이션\n\n- **목표:** 고수준 인터페이스 함수를 호출하여 전체 빌드 프로세스를 조율하는 주 `CMakeLists.txt` 파일을 생성합니다.\n- **태스크**\n - **5.1 주 프로젝트 빌드 스크립트:** 모든 모듈을 통합하여 전체 프로젝트 빌드를 구성하는 최상위 `CMakeLists.txt` 파일을 개발합니다.\n\n---\n\n### 에픽 6: 코어 수학 라이브러리 구현\n\n- **목표:** public 헤더와 private 소스 파일을 포함한 코어 'example' 정적 라이브러리를 구현하고 빌드 시스템에 의해 컴파일되도록 합니다.\n- **태스크**\n - **6.1 정수 덧셈 기능:** 해당 헤더 및 소스 파일에 `Add` 함수를 구현합니다.\n - **6.2 정수 뺄셈 기능:** 해당 헤더 및 소스 파일에 `Subtract` 함수를 구현합니다.\n\n---\n\n### 에픽 7: 예제 애플리케이션 실행 파일\n\n- **목표:** 코어 수학 라이브러리와 외부 의존성을 사용하여 완전한 종단 간 빌드를 보여주는 데모 실행 파일을 구현합니다.\n- **태스크**\n - **7.1 수학 라이브러리 데모 실행 파일:** 수학 라이브러리 함수와 결과 로깅을 위해 spdlog를 사용하는 `main` 애플리케이션을 생성합니다.\n\n---\n\n### 에픽 8: 테스트 스위트 및 코드 커버리지\n\n- **목표:** Catch2를 사용하여 라이브러리 기능을 검증하는 포괄적인 테스트 스위트를 구현하고 빌드 후 코드 커버리지 분석을 구성합니다.\n- **태스크**\n - **8.1 Add 함수에 대한 단위 테스트:** `Add` 함수의 정확성을 검증하는 테스트 스위트를 생성합니다.\n - **8.2 Subtract 함수에 대한 단위 테스트:** `Subtract` 함수의 정확성을 검증하는 테스트 스위트를 생성합니다.\n - **8.3 산술 연산에 대한 통합 테스트:** `Add`와 `Subtract` 함수의 결합된 동작을 검증하는 테스트 스위트를 생성합니다.\n\n---\n\n### 에픽 9: 자동화된 개발자 도구\n\n- **목표:** 포맷팅, 정적 분석, 문서 생성을 위한 사용자 정의 자동화 빌드 타겟을 생성하여 개발자 생산성 도구를 통합합니다.\n- **태스크**\n - **9.1 코드 포맷터 실행 스크립트:** `make format` 타겟을 통해 모든 프로젝트 소스 파일에 `clang-format`을 실행하는 셸 스크립트를 생성합니다.\n - **9.2 정적 분석 실행 스크립트:** `make static_analysis` 타겟을 통해 모든 프로젝트 소스 파일에 `clang-tidy`를 실행하는 셸 스크립트를 생성합니다.\n - **9.3 Doxygen 구성 템플릿:** `make create_documentations` 타겟을 통해 API 문서 생성을 활성화하는 `doxyfile.in` 템플릿을 생성합니다.\n","> 몇 달이 아닌, 단 몇 분 만에 엔터프라이즈급 C++ 개발 환경을 구축하세요.\n\n이 프로젝트는 새로운 프로젝트 시작 시 발생하는 상당한 오버헤드를 제거하기 위해 설계된, 포괄적이고 사전 구성된 C++ 템플릿입니다. 빌드 시스템을 직접 설계하고 품질 도구를 통합하는 대신, 최신 C++20 및 CMake 모범 사례를 기반으로 구축된 견고한 기반을 얻게 됩니다.\n\n이 템플릿의 핵심은 유지보수성을 높이는 모듈식의 가독성 높고 확장 가능한 CMake 아키텍처입니다. 포맷팅(clang-format), 정적 분석(clang-tidy), 테스트(Catch2)를 위한 코드 품질 관리가 완벽하게 자동화되어 있어, 팀이 첫 커밋부터 높은 표준을 준수하도록 보장합니다. 또한 유연한 의존성 관리 시스템을 포함하여 서드파티 라이브러리 통합을 간소화합니다.","### 템플릿 구성 요소\n\n- 완전하고 재사용 가능한 C++20 프로젝트 템플릿 저장소\n- 확장이 용이한 계층적, 선언적 CMake 빌드 시스템\n- 단일 명령어로 실행 가능한 포맷팅, 정적 분석, 문서 생성 빌드 타겟\n- 깔끔한 public/private 인터페이스를 보여주는 데모 라이브러리 및 실행 파일\n- 코드 커버리지 리포팅 기능을 갖춘 Catch2 기반의 통합 테스트 스위트\n- 코딩 표준과 프로젝트 규칙을 정의하는 포괄적인 문서\n\n### 도입 효과\n\n- 프로젝트 설정 시간을 몇 주에서 몇 분으로 대폭 단축합니다.\n- 팀 전체에 일관된 코드 품질을 자동으로 적용합니다.\n- 명확하고 잘 문서화된 구조로 신규 개발자의 온보딩 속도를 높입니다.\n- 통합된 자동 테스트 프레임워크를 통해 코드베이스에 대한 신뢰를 구축합니다.\n- 빌드 시스템 유지보수가 아닌, 비즈니스 문제 해결에 에너지를 집중할 수 있습니다.","2025-06-27T07:16:16.729Z",[1128,1129,1130,1131],"C++ 팀 리더: 팀 전체에 일관된 코드 품질을 적용하고 프로젝트 설정 시간을 단축해야 하는 분","시니어 소프트웨어 엔지니어: 반복적인 빌드 시스템 구축에 지쳤으며, 즉시 기능 코드 작성을 시작하고 싶은 분","C++ 개발자: 몇 주간의 설정 작업 없이 최신 C++20과 전문적인 도구를 도입하고 싶은 분","소프트웨어 아키텍트: 여러 C++ 서비스를 구축하기 위한 표준화되고, 유지보수 가능하며, 확장 가능한 템플릿을 찾는 분",[1133,1148,1163,1177,1192,1207,1222,1237,1252,1267,1282,1299,1314,1329,1344,1363,1378,1392,1409,1424,1437,1454,1469,1485],{"_22":1134,"_24":1135,"_75":1136,"_77":1137,"_79":1138,"_51":1147,"_42":99},"task-1750998533184","C++ 코드 포맷팅 표준 구성","# 과제: C++ 코드 포매팅 표준 구성\n\n> **에픽**: 프로젝트 거버넌스 및 코딩 표준\n\n## 1. 과제 정의\n\n### 1.1. 목표\n\n- **목표**: C++ 파일에 대한 코드 포매팅 표준을 정의하여 코드베이스 전반에 걸쳐 일관된 스타일을 보장합니다.\n- **근거**: 단일화되고 자동화된 포매팅 표준을 적용하는 것은 고품질 소프트웨어 개발의 기본 관행입니다. 이는 스타일에 대한 논쟁을 없애고, 코드를 보편적으로 읽고 유지 관리할 수 있도록 보장하며, 개발자의 인지 부하를 줄여 로직에 더 집중할 수 있게 합니다. 이는 개발자 생산성 및 코드 품질 향상이라는 프로젝트의 핵심 목표를 직접적으로 지원합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 프로젝트의 C++ 스타일 규칙을 강제하는 `.clang-format` 설정 파일.\n- **명세**: 설정 파일은 다음 주요 규칙을 구현합니다:\n - `BasedOnStyle`: `Google`\n - `Language`: `Cpp`\n - `ColumnLimit`: `80`\n - `IndentWidth`: `2`\n - `BreakBeforeBraces`: `Attach`\n - `PointerAlignment`: `Left`\n - `IncludeBlocks`: `Regroup`\n- **결과 파일 구조**\n\n```bash\n# .\n# ├── .clang-format <-- 신규\n# └── ...\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 개발자 워크플로우 내에서 `.clang-format` 설정 파일의 역할을 보여줍니다. 이는 런타임 흐름의 일부가 아니라 툴체인 프로세스입니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"개발자 로컬 머신\"\n Dev[\"개발자가 C++ 소스 코드를
작성 또는 수정\"]\n Tool[\"코드 포맷터 호출
(예: 편집기 플러그인 또는 'make format' 사용)\"]\n ClangFormat[\"clang-format 도구\"]\n ConfigFile[\".clang-format에서
설정 읽기\"]\n SourceFiles[\"C++ 소스 파일
(예: 'source/', 'include/')\"]\n FormattedCode[\"포맷팅된 C++ 소스 파일\"]\n end\n\n Dev --> Tool\n Tool --> ClangFormat\n ClangFormat --> ConfigFile\n ConfigFile --> ClangFormat\n ClangFormat --> SourceFiles\n SourceFiles --> FormattedCode\n```\n\n### 1.3. 인수 기준\n\n개발자는 이 과제를 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3장에 있습니다.\n\n- [ ] 기본 스타일 선택 (Google).\n- [ ] 줄 길이, 들여쓰기, 중괄호 줄 바꿈 설정.\n- [ ] 포인터 정렬 및 include 블록 정렬 규칙.\n- [ ] `.clang-format` 파일 최종 확정.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층화된 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **품질 보증 툴체인**: 이 과제는 이 구성 요소의 핵심 부분을 직접 구현합니다. `.clang-format` 파일은 전체 QA 전략의 핵심 부분인 코드 포매팅 도구(`clang-format`)를 제어하는 설정입니다.\n - **C++ 예제 라이브러리**: 이 구성 요소 내의 소스 코드(`source/` 및 `include/`)는 이 과제에서 정의된 포매팅 규칙의 주요 대상이 됩니다.\n - **테스트 스위트**: 이 구성 요소 내의 테스트 코드(`tests/`) 또한 포매팅 규칙을 준수하여 프로젝트의 모든 C++ 코드에 걸쳐 일관성을 보장합니다.\n\n### 2.2. 영향받는 파일\n\n이 과제를 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `.clang-format`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 기준**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을', '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 1단계: 기본 스타일 선택 (Google)\n\n#### 1. 기본 스타일을 Google로 설정\n\n이 작업은 `Google` 스타일 가이드를 우리 커스텀 설정의 기반으로 삼습니다. 널리 알려진 포괄적인 스타일 가이드로 시작하면 대부분의 규칙에 대해 견고하고 합리적인 기본값을 제공하여, 우리가 원하는 차이점만 지정할 수 있게 해줍니다. 이는 설정 속도를 높이고 업계 모범 사례에 부합합니다. 프로젝트의 루트 디렉터리에 다음 내용으로 `.clang-format` 파일을 생성합니다.\n\n**파일**: `.clang-format`\n\n```yaml\n---\n# 이 파일은 YAML 형식입니다.\nLanguage: Cpp\nBasedOnStyle: Google\n...\n```\n\n---\n\n### 2단계: 줄 길이, 들여쓰기, 중괄호 줄 바꿈 설정\n\n#### 1. 열 제한 및 들여쓰기 설정\n\n이 작업은 기본적인 가독성 규칙을 설정합니다. 80자의 `ColumnLimit`은 다양한 디스플레이 크기에서 가독성을 향상시키고 코드의 병렬 검토를 용이하게 하는 오랜 관행입니다. 2칸의 `IndentWidth`는 과도한 수평 공간을 차지하지 않으면서도 명확한 시각적 범위를 제공하여 80열 제한 하에서 유용합니다.\n\n**파일**: `.clang-format`\n\n```yaml\n...\nBasedOnStyle: Google\nColumnLimit: 80\nIndentWidth: 2\n...\n```\n\n#### 2. 중괄호 줄 바꿈 설정\n\n이 작업은 중괄호 스타일을 `Attach`로 설정하여, 여는 중괄호가 이전 구문과 같은 줄에 위치하도록 합니다(예: `class MyClass {`). 이 스타일은 다른 대안보다 더 간결하며 Google 기본 스타일과 잘 맞는 일반적인 관례입니다.\n\n**파일**: `.clang-format`\n\n```yaml\n...\nIndentWidth: 2\nBreakBeforeBraces: Attach\n...\n```\n\n---\n\n### 3단계: 포인터 정렬 및 include 블록 정렬 규칙\n\n#### 1. 포인터 정렬 설정\n\n이 작업은 포인터와 참조를 위한 별표(`*`)가 타입 이름 옆 왼쪽으로 정렬되도록 강제합니다(예: `int* p`). 이는 Google C++ 스타일 가이드에서 사용되는 관례이며 모든 포인터 선언이 시각적으로 일관되도록 보장합니다.\n\n**파일**: `.clang-format`\n\n```yaml\n...\nBreakBeforeBraces: Attach\nPointerAlignment: Left\n...\n```\n\n#### 2. Include 블록 정렬 및 그룹화 설정\n\n이 작업은 `#include` 지시문의 자동 정렬 및 그룹화를 활성화합니다. `IncludeBlocks`를 `Regroup`으로 설정하면 `clang-format`이 `IncludeCategories` 정규식 패턴에 따라 include들을 별개의 블록으로 재정렬합니다. 이는 모든 파일의 헤더 섹션을 표준화하여 의존성을 명확하게 하고 병합 충돌을 방지합니다. 카테고리는 프로젝트별 헤더, 외부 라이브러리 헤더, 그리고 마지막으로 표준 라이브러리 헤더 순으로 우선순위를 정합니다.\n\n**파일**: `.clang-format`\n\n```yaml\n...\nPointerAlignment: Left\nIncludeBlocks: Regroup\nIncludeCategories:\n - Regex: '^\"example/.*\"'\n Priority: 1\n - Regex: '^<.*>'\n Priority: 2\n - Regex: '\".*\"'\n Priority: 3\n...\n```\n\n---\n\n### 4단계: `.clang-format` 파일 최종 확정\n\n#### 1. 최종 .clang-format 설정 파일 생성\n\n이 작업은 지정된 모든 규칙을 최종 `.clang-format` 파일 하나로 통합합니다. 프로젝트 루트에 있는 이 단일 파일은 개발자 편집기와 CI/CD 파이프라인에서 사용할 모든 C++ 코드 스타일에 대한 단일 진실 공급원(single source of truth) 역할을 합니다.\n\n**파일**: `.clang-format`\n\n```yaml\n---\n# 이 파일은 YAML 형식입니다. 전체 옵션 목록은 Clang-Format 스타일 옵션 문서를 참조하세요:\n# https://clang.llvm.org/docs/ClangFormatStyleOptions.html\n\nLanguage: Cpp\nBasedOnStyle: Google\n\n# 커스텀 설정\nColumnLimit: 80\nIndentWidth: 2\nUseTab: Never\nBreakBeforeBraces: Attach\nPointerAlignment: Left\nAllowShortFunctionsOnASingleLine: None\nAllowShortIfStatementsOnASingleLine: Never\nAllowShortLoopsOnASingleLine: false\nSortIncludes: true\nIncludeBlocks: Regroup\nIncludeCategories:\n - Regex: '^\"example/.*\"'\n Priority: 1\n - Regex: '^<.*>'\n Priority: 2\n - Regex: '\".*\"'\n Priority: 3\n...\n```\n\n---\n\n## 4. 검증 절차\n\n### 4.1. 검증 단계\n\n`.clang-format` 파일이 올바르게 설정되었는지 확인하려면 프로젝트의 루트 디렉터리에서 다음 단계를 수행하십시오.\n\n1. **테스트 파일을 생성**하고 의도적으로 잘못 포맷된 C++ 코드를 넣습니다.\n\n ```bash\n # 포맷이 잘못된 코드로 임시 파일 생성\n cat < test_format.cpp\n #include \n #include \n\n #include \"example/math/add.hpp\"\n\n int *p;\n int main()\n {\n if (true) { std::cout << \"Hello\" << std::endl; }\n return 0;\n }\n EOF\n ```\n\n2. 테스트 파일에 대해 **`clang-format`을 실행**합니다. `--style=file` 옵션은 도구가 디렉터리 계층 구조에서 `.clang-format` 파일을 찾아 사용하도록 지시합니다. `-i` 옵션은 변경 사항을 파일에 직접 적용합니다.\n\n ```bash\n clang-format -i --style=file test_format.cpp\n ```\n\n3. **파일 내용을 확인**한 다음 임시 파일을 제거합니다.\n\n ```bash\n # 포맷팅된 내용 표시\n cat test_format.cpp\n\n # 정리\n rm test_format.cpp\n ```\n\n### 4.2. 예상 결과\n\n`clang-format` 명령은 오류 없이 실행되어야 합니다. `cat` 명령의 출력은 코드가 규칙(정렬된 include, 올바른 들여쓰기, 붙은 중괄호, 왼쪽 정렬 포인터, 적절한 공백)에 따라 재포맷되었음을 보여주어야 합니다.\n\n**포맷팅 후 `test_format.cpp`의 예상 내용:**\n\n```cpp\n#include \"example/math/add.hpp\"\n\n#include \n#include \n\nint* p;\nint main() {\n if (true) {\n std::cout << \"Hello\" << std::endl;\n }\n return 0;\n}\n```","프로젝트의 C++ 스타일 규칙을 강제하는 `.clang-format` 구성 파일.",[1139,1141,1143,1145],{"_24":1140,"_83":39,"_84":61,"_85":61},"기본 스타일(Google) 선택.",{"_24":1142,"_83":39,"_84":61,"_85":88},"줄 길이, 들여쓰기, 중괄호 줄 바꿈 구성.",{"_24":1144,"_83":39,"_84":61,"_85":91},"포인터 정렬 및 include 블록 정렬 규칙.",{"_24":1146,"_83":39,"_84":61,"_85":94},"완료된 `.clang-format` 파일.","코드베이스 전반에 걸쳐 일관된 스타일을 보장하기 위한 C++ 파일의 코드 포맷팅 표준 정의.",{"_22":1149,"_24":1150,"_75":1151,"_77":1152,"_79":1153,"_51":1162,"_42":99},"task-1750998583712","정적 분석 규칙 구성","# 과제: 정적 분석 규칙 설정\n\n> **에픽**: 프로젝트 거버넌스 및 코딩 표준\n\n## 1. 과제 정의\n\n### 1.1. 목표\n\n- **목표**: 버그와 스타일 문제를 사전에 식별하기 위한 정적 분석 검사 세트.\n- **근거**: 전체 C++ 코드베이스에 일관되고 높은 품질의 코딩 표준을 적용합니다. `clang-tidy`를 사용한 정적 분석 자동화는 일반적인 오류를 방지하고 코드 가독성을 향상시키며, 수동 코드 리뷰에 소요되는 시간을 줄여 품질 시행 자동화라는 프로젝트의 핵심 목표를 직접적으로 지원합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 활성화된 검사 및 이름 지정 규칙을 명시하는 `.clang-tidy` 설정 파일.\n- **명세**:\n - 설정은 루트 레벨의 `.clang-tidy` 파일에 YAML 형식으로 정의됩니다.\n - `clang-analyzer-*`, `cppcoreguidelines-*`, `performance-*`, `readability-*`, `modernize-*`를 포함한 핵심 검사 그룹이 활성화됩니다.\n - 식별자 이름 지정 규칙이 적용됩니다:\n - `ClassCase`, `StructCase`, `FunctionCase`, `ClassMethodCase`: `CamelCase`\n - `VariableCase`, `ClassMemberCase`: `lower_case`\n - `ClassMemberSuffix`: `_`\n - `EnumConstantCase`, `ConstexprVariableCase`: `k` 접두사를 붙인 `CamelCase`.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── .clang-tidy <-- 수정됨\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 개발 워크플로우 내에서 `.clang-tidy` 설정이 어떻게 사용되는지를 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph A[\"개발자 워크플로우\"]\n Dev[\"개발자
C++ 코드 작성/수정\"]\n Make[\"make static_analysis 실행\"]\n end\n\n subgraph B[\"빌드 시스템\"]\n CMake[\"CMake 빌드 타겟
(static_analysis)\"]\n ClangTidyRun[\"clang-tidy 명령어 실행\"]\n Config[\".clang-tidy에서
설정 읽기\"]\n end\n\n subgraph C[\"출력\"]\n Report[\"분석 보고서 생성
(stdout/stderr)\"]\n end\n\n Dev --> Make\n Make --> CMake\n CMake --> ClangTidyRun\n Config --> ClangTidyRun\n ClangTidyRun --> Report\n Report --> Dev\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 과제를 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] 핵심 검사 세트(clang-analyzer, cppcoreguidelines 등) 정의.\n- [ ] `readability-identifier-naming` 규칙 설정.\n- [ ] 암시적 변환 및 복잡도 검사 설정.\n- [ ] `.clang-tidy` 파일 최종 확정.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층형 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **품질 보증 툴체인**: 이 과제는 이 구성 요소의 핵심 부분을 직접 설정합니다. `.clang-tidy` 파일은 툴체인이 정적 분석을 수행하기 위해 사용하는 중앙 설정 산출물입니다.\n - **모듈식 CMake 빌드 시스템**: 이 구성 요소는 이 과제에서 정의된 설정을 사용하여 `clang-tidy`를 실행하는 사용자용 타겟(예: `make static_analysis`)을 제공함으로써 품질 보증 툴체인을 통합하는 역할을 합니다.\n - **C++ 예제 라이브러리 / 테스트 스위트**: `.clang-tidy`에 정의된 규칙은 예제 라이브러리와 테스트 스위트를 포함한 모든 C++ 소스 코드에 적용되어 프로젝트의 코딩 표준을 준수하도록 보장합니다.\n\n### 2.2. 영향받는 파일\n\n이 과제를 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `.clang-tidy`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 핵심 검사 세트(clang-analyzer, cppcoreguidelines 등) 정의\n\n#### 1. 주 검사 그룹 설정\n\n이 작업은 어떤 검사 그룹을 활성화할지 정의하여 모든 정적 분석의 기준선을 설정합니다. 설정은 차감 모델을 사용합니다: `-*`로 먼저 모든 검사를 비활성화한 다음, 후속 항목에서 와일드카드를 사용하여 원하는 그룹을 선택적으로 다시 활성화합니다. 이 접근 방식은 잠재적 버그, 성능 문제, C++ 핵심 가이드라인 위반을 포괄하는 포괄적이고 현대적인 규칙 세트를 제공하여 코드 품질을 위한 강력한 기반을 만듭니다.\n\n**파일**: `.clang-tidy`\n\n```yaml\nChecks: \"-*, abseil-*, clang-analyzer-*, altera-*, boost-*, concurrency-*, cppcoreguidelines-*, hicpp-*, openmp-*, performance-*, portability-*, readability-*, modernize-*, google-*, misc-*\"\n\nCheckOptions:\n...\n```\n\n---\n\n### 단계 2: `readability-identifier-naming` 규칙 설정\n\n#### 1. 타입과 함수에 대한 이름 지정 규칙 정의\n\n이 작업은 클래스, 구조체, 함수와 같은 주요 코드 구조에 대해 일관된 이름 지정 체계를 강제합니다. 이러한 엔티티에 `CamelCase`를 지정함으로써 일반적인 C++ 관행에 맞춰 코드를 더 쉽게 읽고 탐색할 수 있도록 합니다. `CheckOptions` 섹션은 더 넓은 `readability-identifier-naming` 검사 내에서 이러한 특정 규칙을 설정하는 메커니즘을 제공합니다.\n\n**파일**: `.clang-tidy`\n\n```yaml\n...\nCheckOptions:\n - { key: readability-identifier-naming.NamespaceCase, value: lower_case }\n - { key: readability-identifier-naming.ClassCase, value: CamelCase }\n - { key: readability-identifier-naming.StructCase, value: CamelCase }\n - {\n key: readability-identifier-naming.TemplateParameterCase,\n value: CamelCase,\n }\n - { key: readability-identifier-naming.FunctionCase, value: CamelCase }\n - { key: readability-identifier-naming.ClassMethodCase, value: CamelCase }\n - { key: readability-identifier-naming.StructMethodCase, value: CamelCase }\n...\n```\n\n#### 2. 변수와 멤버에 대한 이름 지정 규칙 정의\n\n이 작업은 데이터 저장 식별자의 종류를 구분합니다. 지역 변수는 `lower_case`를 사용하고, 클래스 멤버는 `lower_case`에 꼬리 밑줄 `_`을 사용합니다. 이 접미사는 변수가 클래스의 멤버임을 즉시 시각적으로 알려주어, 매개변수와의 이름 충돌을 방지하고 메서드 구현 내의 명확성을 향상시킵니다.\n\n**파일**: `.clang-tidy`\n\n```yaml\n...\nCheckOptions:\n...\n - { key: readability-identifier-naming.VariableCase, value: lower_case }\n - { key: readability-identifier-naming.ClassMemberCase, value: lower_case }\n - { key: readability-identifier-naming.ClassMemberSuffix, value: _ }\n - { key: readability-identifier-naming.PrivateMemberSuffix, value: _ }\n - { key: readability-identifier-naming.ProtectedMemberSuffix, value: _ }\n...\n```\n\n#### 3. 상수와 열거형에 대한 이름 지정 규칙 정의\n\n이 작업은 컴파일 타임 상수와 열거형 값에 대한 표준을 설정합니다. 둘 다 `k` 접두사를 붙인 `CamelCase`를 사용합니다. 구글과 같은 스타일 가이드에서 널리 사용되는 이 규칙은 상수를 즉시 알아볼 수 있게 하여, 컴파일 타임에 평가되는 불변 값임을 알립니다.\n\n**파일**: `.clang-tidy`\n\n```yaml\n...\nCheckOptions:\n...\n - { key: readability-identifier-naming.EnumConstantCase, value: CamelCase }\n - { key: readability-identifier-naming.EnumConstantPrefix, value: k }\n - {\n key: readability-identifier-naming.ConstexprVariableCase,\n value: CamelCase,\n }\n - { key: readability-identifier-naming.ConstexprVariablePrefix, value: k }\n - { key: readability-identifier-naming.ConstantCase, value: CamelCase }\n - { key: readability-identifier-naming.GlobalConstantCase, value: CamelCase }\n - { key: readability-identifier-naming.GlobalConstantPrefix, value: k }\n - { key: readability-identifier-naming.MemberConstantCase, value: CamelCase }\n - { key: readability-identifier-naming.MemberConstantPrefix, value: k }\n - { key: readability-identifier-naming.StaticConstantCase, value: CamelCase }\n - { key: readability-identifier-naming.StaticConstantPrefix, value: k }\n...\n```\n\n---\n\n### 단계 3: 암시적 변환 및 복잡도 검사 설정\n\n#### 1. 불리언 변환 규칙 미세 조정\n\n이 작업은 `readability-implicit-bool-conversion` 검사를 조정합니다. 암시적 변환이 때때로 버그를 숨길 수 있지만, 포인터(`if (ptr)`)와 정수(`if (count)`)에서의 사용은 매우 뿌리 깊고 널리 이해되는 C++ 관용구입니다. 이러한 특정 경우를 명시적으로 허용하여 관례적인 코드를 오류로 표시하는 것을 방지함으로써 정적 분석기에서 발생하는 노이즈를 줄입니다.\n\n**파일**: `.clang-tidy`\n\n```yaml\n...\nCheckOptions:\n...\n - {\n key: readability-implicit-bool-conversion.AllowIntegerConditions,\n value: 1,\n }\n - {\n key: readability-implicit-bool-conversion.AllowPointerConditions,\n value: 1,\n }\n...\n```\n\n#### 2. 인지 복잡도 계산 설정\n\n이 작업은 `readability-function-cognitive-complexity` 검사를 수정하여 매크로 내부의 코드를 무시하도록 합니다. 매크로는 복잡도 점수를 인위적으로 부풀려, 그렇지 않으면 단순한 함수에서 거짓 양성(false positive)을 유발할 수 있습니다. `IgnoreMacros`를 활성화함으로써, 복잡도 분석이 직접 작성된 로직에 집중하도록 하여 코드 유지보수성에 대해 더 정확하고 유용한 측정치를 제공합니다.\n\n**파일**: `.clang-tidy`\n\n```yaml\n...\nCheckOptions:\n...\n - { key: readability-function-cognitive-complexity.IgnoreMacros, value: 1 }\n...\n```\n\n---\n\n### 단계 4: `.clang-tidy` 파일 최종 확정\n\n#### 1. 최종 설정 파일 조합\n\n이 작업은 이전에 명시된 모든 설정을 최종 `.clang-tidy` 산출물로 결합하는 것으로 구성됩니다. 이 파일은 모든 정적 분석 규칙에 대한 단일 진실 공급원(single source of truth) 역할을 합니다. 프로젝트 루트에 위치함으로써 `clang-tidy` 및 통합 개발 환경(IDE)에 의해 자동으로 발견되고 적용되어 모든 개발자에게 일관된 규칙 적용을 보장합니다.\n\n**파일**: `.clang-tidy`\n\n```yaml\nChecks: \"-*, abseil-*, clang-analyzer-*, altera-*, boost-*, concurrency-*, cppcoreguidelines-*, hicpp-*, openmp-*, performance-*, portability-*, readability-*, modernize-*, google-*, misc-*\"\n\nCheckOptions:\n - { key: readability-identifier-naming.NamespaceCase, value: lower_case }\n - { key: readability-identifier-naming.ClassCase, value: CamelCase }\n - { key: readability-identifier-naming.StructCase, value: CamelCase }\n - {\n key: readability-identifier-naming.TemplateParameterCase,\n value: CamelCase,\n }\n - { key: readability-identifier-naming.FunctionCase, value: CamelCase }\n - { key: readability-identifier-naming.VariableCase, value: lower_case }\n - { key: readability-identifier-naming.ClassMemberCase, value: lower_case }\n - { key: readability-identifier-naming.ClassMemberSuffix, value: _ }\n - { key: readability-identifier-naming.PrivateMemberSuffix, value: _ }\n - { key: readability-identifier-naming.ProtectedMemberSuffix, value: _ }\n - { key: readability-identifier-naming.EnumConstantCase, value: CamelCase }\n - { key: readability-identifier-naming.EnumConstantPrefix, value: k }\n - {\n key: readability-identifier-naming.ConstexprVariableCase,\n value: CamelCase,\n }\n - { key: readability-identifier-naming.ConstexprVariablePrefix, value: k }\n - { key: readability-identifier-naming.ConstantCase, value: CamelCase }\n - { key: readability-identifier-naming.GlobalConstantCase, value: CamelCase }\n - { key: readability-identifier-naming.GlobalConstantPrefix, value: k }\n - { key: readability-identifier-naming.MemberConstantCase, value: CamelCase }\n - { key: readability-identifier-naming.MemberConstantPrefix, value: k }\n - { key: readability-identifier-naming.StaticConstantCase, value: CamelCase }\n - { key: readability-identifier-naming.StaticConstantPrefix, value: k }\n - {\n key: readability-implicit-bool-conversion.AllowIntegerConditions,\n value: 1,\n }\n - {\n key: readability-implicit-bool-conversion.AllowPointerConditions,\n value: 1,\n }\n - { key: readability-function-cognitive-complexity.IgnoreMacros, value: 1 }\n - { key: readability-identifier-naming.ClassMethodCase, value: CamelCase }\n - { key: readability-identifier-naming.StructMethodCase, value: CamelCase }\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n`.clang-tidy` 파일의 정확성을 검증하기 위해, 개발자는 CMake 빌드 시스템에서 제공하는 정적 분석 타겟을 실행해야 합니다. 이는 에픽 9에서 명시된 `static_analysis` 타겟이 존재한다고 가정합니다.\n\n```bash\n# 1. 아직 설정하지 않았다면 CMake를 사용하여 프로젝트를 설정합니다.\n# 이것은 빌드 시스템(예: Makefiles)을 생성합니다.\ncmake -B build -S .\n\n# 2. 빌드 폴더로 디렉토리를 변경합니다.\ncd build\n\n# 3. 정적 분석 타겟을 실행합니다. 이 명령어는 새로 설정된 .clang-tidy 파일을 사용하여\n# 모든 C++ 소스 파일에 대해 clang-tidy를 호출합니다.\nmake static_analysis\n```\n\n### 4.2. 예상 결과\n\n검증 절차를 실행한 후, `clang-tidy` 도구가 실행됩니다. 프로젝트의 초기 코드는 새로운 규칙을 준수해야 하므로, 명령어는 종료 코드 0으로 성공적으로 완료되고 경고를 생성하지 않아야 합니다. 출력은 다음과 유사해야 하며, 파일이 문제없이 처리되었음을 나타냅니다.\n\n```\n... (빌드 시스템 출력) ...\n[100%] Firing up clang-tidy\n... (clang-tidy 파일 처리 중) ...\n0 warnings generated.\n... (빌드 시스템 출력) ...\n```\n","활성화된 검사 및 이름 지정 규칙을 명시하는 `.clang-tidy` 구성 파일.",[1154,1156,1158,1160],{"_24":1155,"_83":39,"_84":88,"_85":61},"핵심 검사 세트(clang-analyzer, cppcoreguidelines 등) 정의.",{"_24":1157,"_83":39,"_84":88,"_85":88},"`readability-identifier-naming` 규칙 구성.",{"_24":1159,"_83":39,"_84":88,"_85":91},"암시적 변환 및 복잡도 검사 구성.",{"_24":1161,"_83":39,"_84":88,"_85":94},"완료된 `.clang-tidy` 파일.","버그와 스타일 문제를 사전에 식별하기 위한 정적 분석 검사 세트.",{"_22":1164,"_24":296,"_75":1165,"_77":1166,"_79":1167,"_51":1176,"_42":99},"task-1750998629243","# 작업: CMake 코딩 스타일 가이드\n\n> **에픽**: 프로젝트 거버넌스 및 코딩 표준\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 모든 CMake 스크립트에 대한 코딩 표준을 설명하는 포괄적인 문서.\n- **근거**: 프로젝트 내 모든 CMake 코드에 대해 일관되고, 가독성 있으며, 유지보수 가능한 표준을 수립하기 위함. 이는 개발자 생산성과 코드 품질을 향상시키려는 프로젝트의 기본 목표 요소이며, 핵심 구성 요소인 빌드 시스템을 명확하고 확장하기 쉽게 보장함.\n\n### 1.2. 결과물\n\n- **예상 결과**: CMake 모범 사례를 정의하는 마크다운 문서 `coding_styles.md`.\n- **명세**: 최종 문서는 다음 섹션을 포함해야 함:\n - `Core Principles`: 상위 수준의 개발 철학(예: 타겟 중심 CMake)을 정의.\n - `Format`: 이름 지정 규칙, 들여쓰기, 줄 길이에 대한 강제 규칙을 포함.\n - `Style Rules`: 명령어 사용, 파일 구조, 변수 처리에 대한 모범 사례 가이드라인을 제공.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── documents/\n# └── guidelines/\n# └── cmake/\n# └── coding_styles.md <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 개발 수명 주기에서 코딩 스타일 가이드의 역할을 보여줍니다. 이는 개발 및 검토 중에 코드 품질을 보장하기 위해 사용되는 참조 문서입니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n Developer[\"개발자
CMake 코드 작성\"] --> StyleGuide{\"참조
coding_styles.md\"};\n StyleGuide --> Developer;\n Developer --> PullRequest[\"풀 리퀘스트 제출\"];\n PullRequest --> Reviewer[\"코드 리뷰어\"];\n Reviewer --> StyleGuide;\n StyleGuide --> Reviewer;\n Reviewer --> Approval[\"승인 또는
변경 요청\"];\n```\n\n### 1.3. 인수 기준\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이는 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] 핵심 원칙 정의(타겟 중심, 자체 문서화 코드).\n- [ ] 변수, 함수, 타겟에 대한 이름 지정 규칙 수립.\n- [ ] 들여쓰기 및 줄 길이에 대한 서식 규칙.\n- [ ] 명령어 사용 및 파일 구조에 대한 가이드라인.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층화된 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **모듈식 CMake 빌드 시스템**: 이 작업은 해당 구성 요소의 구현에 대한 필수 코딩 표준을 정의함으로써 직접적인 영향을 미침. 스타일 가이드는 빌드 시스템을 구성하는 모든 `.cmake` 파일과 `CMakeLists.txt` 스크립트의 구조와 구문을 관리하게 됨.\n - **품질 보증 툴체인**: 이 문서는 품질에 대한 공식적인 명세 역할을 함. 이 툴체인 내의 향후 자동화된 린팅 또는 서식 지정 도구는 여기에 정의된 규칙을 강제하도록 구성될 것임.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `documents/guidelines/cmake/coding_styles.md`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 기준**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇'과 '왜'를 다룸), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 핵심 원칙 정의(타겟 중심, 자체 문서화 코드)\n\n#### 1. 문서 생성 및 핵심 원칙 정의\n\n이 작업은 `coding_styles.md` 파일을 만들고 다른 모든 규칙을 안내하는 기본 원칙으로 채우는 것을 포함합니다. 이러한 원칙들—최신 타겟 중심 명령어 선호, 자체 문서화 코드 작성, 약어 사용 지양, 의미적으로 명확한 이름 사용—은 전체 스타일 가이드의 철학적 기반을 확립하여 규칙 뒤에 있는 '이유'가 처음부터 명확하도록 보장합니다.\n\n**파일**: `documents/guidelines/cmake/coding_styles.md`\n\n```markdown\n# CMake 코딩 스타일 규칙\n\n버전 v1.0\n생성일 2025-06-26\n소유자 @movingChurch\n\n---\n\n## 0. 개요\n\n- **목적** 프로젝트 전반에 걸쳐 CMake 스크립트의 일관성, 가독성, 유지보수성을 보장하기 위함.\n- **범위** 이 리포지토리 내의 모든 `CMakeLists.txt` 및 `*.cmake` 파일.\n- **대상** 이 프로젝트에 기여하는 모든 개발자.\n\n---\n\n## 1. 목차\n\n1. [핵심 원칙](#2-핵심-원칙)\n2. [서식](#3-서식)\n3. [스타일 규칙](#4-스타일-규칙)\n\n---\n\n## 2. 핵심 원칙\n\n### 원칙 1 최신의, 타겟 중심적인 CMake를 선호\n\n- **범위** 모든 타겟 정의 및 속성 수정.\n- **근거** `target_*` 명령어를 사용하면 속성을 필요한 타겟에 명시적으로 연결하여 모듈성, 캡슐화 및 명확성을 향상시킴. 이는 구식의 디렉토리 기반 명령어에서 흔히 발생하는 부작용과 숨겨진 종속성을 피하게 함.\n\n### 원칙 2 자체 문서화되는 코드 작성\n\n- **범위** 모든 변수, 함수, 타겟.\n- **근거** 명확하고 서술적인 이름은 설명 주석의 필요성을 줄여 빌드 로직을 더 쉽게 이해하고 유지보수할 수 있게 함.\n\n### 원칙 3 약어를 사용하지 않음\n\n- **범위** 모든 식별자(변수, 함수, 타겟 등).\n- **근거** 전체 단어를 사용하면 명확성이 보장되어 코드를 처음 접하는 사람도 그 의도를 쉽게 파악할 수 있음.\n\n### 원칙 4 의미적으로 명확한 이름 사용\n\n- **범위** 모든 식별자.\n- **근거** 이름은 요소의 목적이나 내용을 명확하게 설명해야 함. 이는 코드의 역할을 반영하고 빌드 프로세스를 이해하는 데 도움이 됨.\n\n---\n```\n\n---\n\n### 단계 2: 변수, 함수, 타겟에 대한 이름 지정 규칙 수립\n\n#### 1. 이름 지정 규칙 섹션 추가\n\n이 작업은 `서식` 섹션과 이름 지정 규칙에 대한 하위 섹션을 추가합니다. 명확한 표 형식을 사용하여 모든 유형의 CMake 요소(변수, 함수, 타겟 등)에 필요한 이름 지정 스타일을 정의합니다. 이는 일관성을 강제하고 코드를 예측 가능하고 읽기 쉽게 만듭니다.\n\n**파일**: `documents/guidelines/cmake/coding_styles.md`\n\n```markdown\n...\n## 3. 서식\n\n> **설명** 포매터와 린터에 의해 강제될 수 있는 규칙을 포함하여 일관된 모양과 느낌을 보장합니다.\n\n### 3.1 이름 지정 규칙\n\n| 코드 요소 | 이름 지정 스타일 | 예시 |\n| :--- | :--- | :--- |\n| 명령어 | `lowercase` | `project()`, `add_executable()` |\n| 변수 (지역) | `lower_case_with_underscores` | `my_local_variable` |\n| 변수 (전역) | `UPPER_CASE_WITH_UNDERSCORES` | `MY_PROJECT_VERSION` |\n| 함수/매크로 | `lower_case_with_underscores` | `my_custom_function()` |\n| 타겟 | `PascalCase` | `MyExecutable`, `MyLibrary` |\n| 속성 | `UPPERCASE` | `CXX_STANDARD` |\n\n...\n```\n\n---\n\n### 단계 3: 들여쓰기 및 줄 길이에 대한 서식 규칙\n\n#### 1. 서식 규칙 추가\n\n이 작업은 문서에 구체적이고 강제 가능한 서식 규칙을 채웁니다. 명령어 이름에는 소문자를, 들여쓰기 표준으로는 2칸 공백을, 줄 길이 제한은 100자로 규정합니다. 명확한 \"좋은 예\"와 \"나쁜 예\"를 제공하여 이러한 규칙을 모호하지 않고 개발자가 따르기 쉽게 만듭니다.\n\n**파일**: `documents/guidelines/cmake/coding_styles.md`\n\n```markdown\n...\n### 3.2 서식 규칙\n\n#### 서식 규칙 1 모든 명령어 이름에 소문자 사용\n\n- **범위** 모든 CMake 명령어.\n- **근거** CMake 명령어는 대소문자를 구분하지 않지만, 일관된 스타일은 가독성을 향상시킴.\n\n```cmake\n# 좋은 예\nproject(MyProject)\nadd_executable(MyTarget main.cpp)\n\n# 나쁜 예\nPROJECT(MyProject)\nAdd_Executable(MyTarget main.cpp)\n```\n\n#### 서식 규칙 2 들여쓰기는 2칸 공백 사용\n\n- **범위** 모든 들여쓰기 블록.\n- **근거** 탭 너비 설정에 의존하지 않고 일관된 들여쓰기를 보장함.\n\n```cmake\n# 좋은 예\nif(CONDITION)\n message(\"2칸으로 들여쓰기\")\nendif()\n\n# 나쁜 예\nif(CONDITION)\n message(\"4칸으로 들여쓰기\")\nendif()\n```\n\n#### 서식 규칙 3 줄 길이는 100자 미만으로 유지\n\n- **범위** 모든 코드 라인.\n- **근거** 분할 화면이나 터미널 뷰에서 가독성을 향상시킴.\n\n---\n\n```\n\n---\n\n### 단계 4: 명령어 사용 및 파일 구조에 대한 가이드라인.\n\n#### 1. 명령어 사용 및 파일 구조 규칙 추가\n\n이 마지막 작업은 상위 수준의 모범 사례를 다루는 `스타일 규칙` 섹션을 추가합니다. 여기에는 명확성을 위해 다중 인수 명령어를 구조화하는 규칙, 모호성을 방지하기 위해 명시적인 `PUBLIC`/`PRIVATE`/`INTERFACE` 키워드를 의무화하는 규칙, `CMakeLists.txt` 파일을 논리적이고 예측 가능한 섹션으로 구성하는 규칙이 포함됩니다. 또한 변수 범위와 이름 지정에 대한 원칙을 공식화합니다.\n\n**파일**: `documents/guidelines/cmake/coding_styles.md`\n\n```markdown\n...\n## 4. 스타일 규칙\n\n### 4.1 명령어 사용\n\n#### 명령어 사용 규칙 1 가독성을 위해 다중 인수 명령어 구조화\n\n- **범위** `target_link_libraries`와 같이 여러 인수를 갖는 명령어.\n- **근거** 각 인수를 새 줄에 배치하면 종속성과 속성을 쉽게 파악할 수 있음.\n\n```cmake\n# 좋은 예\ntarget_link_libraries(MyTarget\n PUBLIC\n MyLibrary1\n PRIVATE\n MyLibrary2\n)\n\n# 나쁜 예\ntarget_link_libraries(MyTarget PUBLIC MyLibrary1 PRIVATE MyLibrary2)\n```\n\n#### 명령어 사용 규칙 2 항상 `PUBLIC`/`PRIVATE`/`INTERFACE`를 명시\n\n- **범위** 가시성 키워드를 받는 모든 `target_*` 명령어.\n- **근거** 종속성과 속성의 범위를 명시적으로 지정하면 모호성을 방지하고 올바르게 전파되도록 보장함.\n\n```cmake\n# 좋은 예\ntarget_include_directories(MyLibrary\n INTERFACE\n \"${CMAKE_CURRENT_SOURCE_DIR}/include\"\n)\n\n# 나쁜 예 (그리고 PUBLIC으로 기본 설정되어 의도와 다를 수 있음)\ntarget_include_directories(MyLibrary\n \"${CMAKE_CURRENT_SOURCE_DIR}/include\"\n)\n```\n\n### 4.2 파일 구조\n\n#### 파일 구조 규칙 1 `CMakeLists.txt`를 논리적 섹션으로 구성\n\n- **범위** 모든 `CMakeLists.txt` 파일.\n- **근거** 일관된 구조는 파일을 예측 가능하고 탐색하기 쉽게 만듦.\n\n```cmake\n# 좋은 예\ncmake_minimum_required(VERSION 3.15)\nproject(MyProject LANGUAGES CXX)\n\n# --- 옵션\noption(BUILD_TESTS \"테스트 빌드\" ON)\n\n# --- 종속성\nfind_package(fmt REQUIRED)\n\n# --- 타겟\nadd_library(MyLibrary my_library.cpp)\n\n# --- 타겟 속성\ntarget_link_libraries(MyLibrary PUBLIC fmt::fmt)\n\n# --- 테스팅\nif(BUILD_TESTS)\n # ...\nendif()\n```\n\n### 4.3 변수\n\n#### 변수 규칙 1 전역 변수 사용 최소화\n\n- **범위** 변수 선언.\n- **근거** 전역 변수는 숨겨진 종속성을 만듦. 함수 인수를 통해 변수를 전달하거나 타겟 속성을 사용하는 것을 선호.\n\n```cmake\n# 좋은 예\n# 속성은 타겟과 함께 캡슐화됨\ntarget_compile_definitions(MyTarget PRIVATE MY_DEFINITION)\n\n# 나쁜 예\n# 이는 디렉토리 내의 모든 후속 타겟에 영향을 미침\nadd_compile_definitions(MY_DEFINITION)\n```\n\n### 4.4 이름 지정 원칙\n\n#### 이름 지정 원칙 규칙 1 약어 대신 전체 단어 사용\n\n- **범위** 모든 식별자.\n- **근거** 명확성을 보장하고 코드의 의도를 쉽게 파악할 수 있게 함.\n\n```cmake\n# 좋은 예\nset(source_directory ${CMAKE_CURRENT_SOURCE_DIR}/src)\n\n# 나쁜 예\nset(src_dir ${CMAKE_CURRENT_SOURCE_DIR}/src)\n```\n\n#### 이름 지정 원칙 규칙 2 이름은 목적과 내용을 명확하게 설명해야 함\n\n- **범위** 모든 식별자.\n- **근거** 자체 설명적인 이름은 주석의 필요성을 줄이고 유지보수성을 향상시킴.\n\n```cmake\n# 좋은 예\nset(executable_sources\n main.cpp\n utils.cpp\n)\n\n# 나쁜 예\nset(file_list\n main.cpp\n utils.cpp\n)\n```\n\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n이 문서화 작업에 대한 검증은 수동 검토 프로세스입니다.\n\n1. 파일 위치로 이동합니다: `documents/guidelines/cmake/coding_styles.md`.\n2. 마크다운 뷰어나 편집기에서 파일을 엽니다.\n3. 파일이 존재하고 그 내용이 섹션 3에 명시된 구현과 일치하는지 확인합니다.\n4. 인수 기준의 각 섹션이 존재하는지 확인합니다:\n - 핵심 원칙 섹션이 존재하고 내용이 채워져 있음.\n - 이름 지정 규칙 표가 존재하고 완전함.\n - 들여쓰기, 대소문자, 줄 길이에 대한 서식 규칙이 예제와 함께 정의되어 있음.\n - 명령어 사용 및 파일 구조 가이드라인이 예제와 함께 존재함.\n\n### 4.2. 예상 결과\n\n- `documents/guidelines/cmake/coding_styles.md` 파일이 지정된 디렉토리에 존재합니다.\n- 렌더링된 마크다운 문서가 잘 서식화되어 있고 가독성이 좋습니다.\n- 파일의 내용은 구현 명세(섹션 3)에 제공된 모든 코드 스니펫과 완전히 일치하며, 프로젝트의 CMake 스크립트에 대한 완전하고 포괄적인 스타일 가이드를 수립합니다.\n","CMake 모범 사례를 정의하는 마크다운 문서 `coding_styles.md`.",[1168,1170,1172,1174],{"_24":1169,"_83":39,"_84":91,"_85":61},"핵심 원칙(타겟 중심, 자체 문서화 코드) 정의.",{"_24":1171,"_83":39,"_84":91,"_85":88},"변수, 함수, 타겟에 대한 이름 지정 규칙 수립.",{"_24":1173,"_83":39,"_84":91,"_85":91},"들여쓰기 및 줄 길이에 대한 포맷팅 규칙.",{"_24":1175,"_83":39,"_84":91,"_85":94},"명령어 사용 및 파일 구조에 대한 가이드라인.","모든 CMake 스크립트에 대한 코딩 표준을 설명하는 포괄적인 문서.",{"_22":1178,"_24":1179,"_75":1180,"_77":1181,"_79":1182,"_51":1191,"_42":99},"task-1750998739062","Doxygen 문서화 표준","# 작업: Doxygen 문서화 표준\n\n> **에픽**: 프로젝트 거버넌스 및 코딩 표준\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: C++ 코드에서 Doxygen 주석을 작성하기 위한 명확한 가이드라인 세트.\n- **근거**: 모든 자동 생성 소스 코드 문서가 일관성 있고, 고품질이며, 유지보수 가능하도록 보장하기 위함. 공식적인 표준을 수립하는 것은 개발자 생산성을 향상하고 코드 품질을 강화하려는 프로젝트의 핵심 목표를 지원함. 이 가이드라인은 품질 보증 툴체인의 기본 부분으로, 개발자가 소스 코드에서 직접 예측 가능하고 유용한 API 문서를 생성할 수 있도록 함.\n\n### 1.2. 결과물\n\n- **예상 결과**: Doxygen 스타일과 매개변수 사용법을 정의하는 Markdown 문서.\n- **사양**:\n - `coding_styles.md` 문서: 주석 구문, 명령어 접두사, 그리고 파일, 클래스, 함수, 멤버 변수 문서화를 위한 특정 규칙을 정의.\n - `parameters.md` 문서: 프로젝트의 `doxyfile.in` 템플릿에 사용되는 주요 Doxygen 설정 옵션을 설명.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── documents/\n# └── guidelines/\n# └── doxygen/\n# ├── coding_styles.md <-- 신규\n# └── parameters.md <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 생성된 가이드라인이 개발 및 문서화 워크플로우에 어떻게 통합되는지 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph 개발 단계\n Dev[\"개발자가 C++ 코드
작성/수정\"]\n Guidelines[\"개발자가
Doxygen 가이드라인 참조\"]\n Comments[\"개발자가 준수하는
Doxygen 주석 작성\"]\n end\n \n subgraph 빌드 단계\n DoxygenTool[\"Doxygen 도구 실행
(예: `make create_documentations` 사용)\"]\n APIDocs[\"HTML/LaTeX
API 문서 생성\"]\n end\n\n Dev --> Guidelines\n Guidelines --> Comments\n Dev -- 통합 --> Comments\n Comments -- 처리됨 --> DoxygenTool\n DoxygenTool --> APIDocs\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3장에 있습니다.\n\n- [ ] 주석 스타일 및 명령어 접두사 정의.\n- [ ] 파일, 클래스, 함수 문서화를 위한 스타일 규칙.\n- [ ] `@todo`, `@bug`, `@code`와 같은 고급 태그 사용에 대한 안내.\n- [ ] 주요 Doxygen 설정 매개변수에 대한 문서화.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층화된 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **품질 보증 툴체인**: 이 작업은 이 구성 요소의 핵심 도구인 Doxygen의 표준을 직접 정의합니다. 이 가이드라인은 도구의 출력이 가치 있도록 보장합니다.\n - **C++ 예제 라이브러리**: 이 구성 요소는 앞으로의 모든 C++ 코드와 함께 이러한 문서화 표준의 주요 소비자가 될 것입니다. 이 라이브러리 내의 코드는 이 작업으로 수립된 규칙을 준수해야 합니다.\n\n### 2.2. 영향을 받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `documents/guidelines/doxygen/coding_styles.md`\n- `documents/guidelines/doxygen/parameters.md`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `Step`은 **인수 조건**의 항목에 해당합니다. 각 `Step`은 일련의 세분화된 `Action`으로 나뉩니다. 각 `Action`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공합니다.\n\n---\n\n### Step 1: 주석 스타일 및 명령어 접두사 정의\n\n#### 1. Doxygen 코딩 스타일 가이드 생성\n\n이 작업은 Doxygen 코딩 스타일에 대한 기본 문서를 수립합니다. 문서화의 핵심 원칙, 필요한 주석 블록 스타일(예: `/** ... */`, `///`), 그리고 모든 Doxygen 명령어에 `@` 접두사 사용을 의무화합니다. 이를 통해 모든 문서에서 일관된 모양과 느낌을 보장하고 Doxygen 도구에 의한 정확한 파싱을 보장합니다.\n\n**파일**: `documents/guidelines/doxygen/coding_styles.md`\n\n```markdown\n# Doxygen C++ 코딩 스타일 규칙\n\n버전 v1.1\n생성일 2025-06-26\n소유자 @movingChurch\n\n---\n\n## 0. 개요\n\n- **목적** C++ 프로젝트를 위한 Doxygen 주석 표준을 정의하여 일관성 있고 유지보수 가능한 문서를 보장합니다.\n- **범위** 이 리포지토리의 모든 C++ 소스 코드(`.hpp`, `.cpp`).\n- **대상** 프로젝트에 기여하는 모든 C++ 개발자.\n\n---\n\n## 1. 목차\n\n1. [핵심 원칙](#2-core-principles)\n2. [일반 주석 규칙](#3-general-commenting-rules)\n3. [구성 요소별 스타일 규칙](#4-style-rules-by-component)\n\n---\n\n## 2. 핵심 원칙\n\n### 원칙 1 단순히 기계적으로가 아닌, 의도를 가지고 문서화하라\n\n- **범위** 모든 문서화 주석.\n- **근거** 코드는 *어떻게* 작동하는지 설명할 수 있지만, 문서는 *왜* 존재하는지, 설계 결정, 그리고 의도된 사용법을 설명해야 합니다. 이러한 맥락은 장기적인 유지보수와 협업에 매우 중요합니다.\n\n### 원칙 2 문서와 코드를 일관되게 유지하라\n\n- **범위** 모든 코드 수정.\n- **근거** 오래되거나 부정확한 문서는 문서가 없는 것보다 더 해롭습니다. 코드를 변경할 때는 반드시 해당하는 Doxygen 주석도 업데이트해야 합니다.\n\n---\n\n## 3. 일반 주석 규칙\n\n> **설명** 코드베이스 전체에 보편적으로 적용되는 Doxygen 주석 작성을 위한 기본 규칙을 포함합니다.\n\n### 3.1 주석 스타일\n\n#### 규칙 1 표준 Doxygen 주석 블록을 사용하라\n\n- **범위** 모든 Doxygen 주석.\n- **근거** 주석 스타일의 일관성은 가독성을 향상시키고 Doxygen 파서가 문서 블록을 정확하게 식별하도록 보장합니다.\n\n```cpp\n# GOOD\n/**\n * @brief 파일, 클래스, 함수에 대한 상세 설명을 위한 여러 줄 주석.\n */\n\n/// 선언부 위에 간결한 설명을 위한 한 줄 주석.\nclass MyClass {};\n\nclass MemberExample {\n int member_; ///< 멤버 변수를 위한 인라인 주석.\n};\n```\n\n### 3.2 명령어 (태그) 사용법\n\n#### 규칙 1 모든 Doxygen 명령어에는 @ 접두사를 사용하라\n\n- **범위** 모든 Doxygen 명령어.\n- **근거** Doxygen은 `\\`도 지원하지만, `@`로 표준화하면 프로젝트 전체의 일관성을 보장할 수 있습니다.\n\n```cpp\n# GOOD\n/**\n * @brief 이것이 올바른 방식입니다.\n * @param user 사용자 객체.\n */\n\n# BAD\n/**\n * \\brief 이것은 우리의 표준이 아닙니다.\n * \\param user 사용자 객체.\n */\n```\n\n```\n\n---\n\n### Step 2: 파일, 클래스, 함수 문서화를 위한 스타일 규칙.\n\n#### 1. 코드 구성 요소에 대한 규칙 추가\n\n이 작업은 스타일 가이드를 확장하여 특정 C++ 구문을 다룹니다. 파일(`@file`), 클래스, 구조체, 열거형, 함수 및 멤버 변수를 문서화하기 위한 규칙을 추가합니다. `@brief`, `@param`, `@return`과 같은 특정 태그를 의무화하여 API 문서에 대한 계약을 강제함으로써, 라이브러리 소비자가 완전하고 예측 가능한 문서를 얻을 수 있도록 합니다.\n\n**파일**: `documents/guidelines/doxygen/coding_styles.md`\n\n```markdown\n...\n\n---\n\n## 4. 구성 요소별 스타일 규칙\n\n### 4.1 파일 주석\n\n#### 규칙 1 모든 소스 및 헤더 파일의 최상단에는 파일 주석 블록이 있어야 한다\n\n- **범위** `*.hpp`, `*.cpp` 파일.\n- **근거** 파일의 목적, 작성자, 버전에 대한 상위 수준의 개요를 제공하며, 이는 프로젝트 탐색 및 관리에 필수적입니다.\n\n```cpp\n# GOOD\n/**\n * @file animal.hpp\n * @author Paul Yang (yes@holyground.world)\n * @brief 동물의 기본 특성과 행동을 정의합니다.\n * @details 이 파일은 Animal 클래스와 AnimalType 열거형을 포함하며, 객체 지향 동물 모델의 기초를 제공합니다.\n * @version 1.1.0\n * @date 2025-06-24\n * @copyright HolyGround (c) 2025 HolyGround, All Rights Reserved.\n */\n```\n\n### 4.2 클래스, 구조체, 열거형 주석\n\n#### 규칙 1 모든 공개 클래스, 구조체, 열거형은 문서화되어야 한다\n\n- **범위** `class`, `struct`, `enum` 선언.\n- **근거** 데이터 구조나 타입의 역할, 책임, 사용법을 명확히 합니다.\n\n```cpp\n# GOOD: 클래스 주석\n/**\n * @brief 동물의 기본 정보를 나타내는 추상 기본 클래스(ABC).\n * @details 이름, 나이 등 모든 동물의 공통 속성을 관리하고 소리를 내기 위한 순수 가상 함수를 제공합니다. 이 클래스는 상속을 통해서만 사용해야 합니다.\n * @note 직접 인스턴스화할 수 없습니다.\n * @see Cat, Dog\n */\nclass Animal {\n // ...\n};\n\n# GOOD: 열거형 주석\n/**\n * @brief 동물 타입을 위한 열거형.\n */\nenum class AnimalType {\n kUnknown, ///< 알 수 없음. 초기 또는 오류 상태를 나타냅니다.\n kCat, ///< 고양이.\n kDog, ///< 개.\n};\n```\n\n### 4.3 함수 및 메서드 주석\n\n#### 규칙 1 모든 public 및 protected 함수/메서드는 문서화되어야 한다\n\n- **범위** 함수 및 메서드 선언/정의.\n- **근거** 함수의 계약(목적, 매개변수, 반환 값)을 명확하게 정의하며, 이는 API 사용자에게 매우 중요합니다.\n\n#### 규칙 2 필수 태그: `@brief`, `@param`, `@return`\n\n- **범위** 문서화된 모든 함수/메서드.\n- **근거** 가장 중요한 정보가 항상 존재하도록 보장합니다. `@param`은 모든 매개변수에 필요하며, 함수가 `void`가 아닌 경우 `@return`이 필요합니다.\n\n### 4.4 멤버 변수 주석\n\n#### 규칙 1 모든 protected 및 public 멤버 변수는 인라인 주석을 가져야 한다\n\n- **범위** 멤버 변수 선언.\n- **근거** 변수가 선언된 바로 그 위치에 변수의 목적에 대한 간결한 설명을 제공합니다.\n\n```cpp\n# GOOD\nprotected:\n std::string name_{}; ///< 동물의 이름.\n uint8_t age_{}; ///< 동물의 나이 (0-255세).\n```\n\n```\n\n---\n\n### Step 3: `@todo`, `@bug`, `@code`와 같은 고급 태그 사용에 대한 안내.\n\n#### 1. 고급 및 유틸리티 태그에 대한 규칙 추가\n\n이 작업은 고급 Doxygen 태그에 대한 규칙을 추가하여 코딩 스타일 가이드를 완성합니다. 사용 중단된 코드(`@deprecated`)를 표시하고, 특별한 노트(`@note`, `@warning`)를 추가하고, 작업(`@todo`, `@bug`)을 추적하고, 예제(`@code`)를 제공하는 방법을 표준화합니다. 이를 통해 문서는 정적인 결과물이 아닌 프로젝트 관리 및 개발자 지침을 위한 능동적인 도구가 됩니다.\n\n**파일**: `documents/guidelines/doxygen/coding_styles.md`\n\n```markdown\n...\n\n### 4.5 고급 및 유틸리티 태그\n\n#### 규칙 1 사용 중단된 코드를 명확하게 표시하라\n\n- **범위** 사용되지 않는 함수, 메서드, 클래스 또는 열거형.\n- **근거** 개발자에게 기능이 더 이상 사용을 권장하지 않으며 향후 제거될 것임을 알립니다. 대안을 제시하는 것이 좋은 습관입니다.\n\n```cpp\n# GOOD\n/**\n * @brief 데이터를 처리하는 이전 함수.\n * @deprecated NewProcessData()로 대체되었습니다. v2.0에서 제거될 예정입니다.\n * @see NewProcessData()\n */\nvoid OldProcessData();\n```\n\n#### 규칙 2 중요한 정보를 강조하기 위해 주석 태그를 사용하라\n\n- **범위** 특별한 강조가 필요한 모든 문서 블록.\n- **근거** `@note`, `@warning`, `@attention`은 독자의 주의를 중요한 정보, 잠재적 위험 또는 중요한 고려 사항으로 이끄는 표준화된 방법을 제공합니다.\n\n```cpp\n# GOOD\n/**\n * @brief 중요한 작업을 수행합니다.\n * @warning 이 함수는 스레드로부터 안전하지 않습니다. 외부에서 접근을 동기화해야 합니다.\n * @note 성능상의 이유로 이 함수는 입력 매개변수를 검증하지 않습니다.\n */\nvoid DoCriticalOperation();\n```\n\n#### 규칙 3 작업과 버그를 코드에서 직접 추적하라\n\n- **범위** 향후 작업이 필요하거나 알려진 문제가 있는 코드의 모든 부분.\n- **근거** `@todo`와 `@bug`는 작업 및 버그 추적을 소스 코드에 통합하여 개발자에게 매우 잘 보이도록 합니다. Doxygen은 이러한 모든 항목의 목록을 생성할 수 있습니다.\n\n```cpp\n# GOOD\n/**\n * @brief 총 가격을 계산합니다.\n * @param items 구매할 항목 목록.\n * @return 총 가격.\n * @bug 대량 주문 시 할인을 제대로 처리하지 못합니다.\n * @todo (movingChurch) 새로운 PricingService를 사용하여 할인 로직을 리팩터링해야 합니다.\n */\nfloat CalculatePrice(const std::vector& items);\n```\n\n#### 규칙 4 명확한 코드 예제를 제공하라\n\n- **범위** 사용법이 즉시 명확하지 않은 함수/메서드 주석.\n- **근거** `@code`를 통한 구체적인 코드 예제는 개발자가 API를 올바르게 사용하는 방법을 이해하는 가장 빠른 방법인 경우가 많습니다.\n\n```cpp\n# GOOD\n/**\n * @brief 두 부동 소수점 숫자가 거의 같은지 비교합니다.\n * @return 두 숫자가 거의 같으면 true, 그렇지 않으면 false.\n * @note 사용 예:\n * @code{.cpp}\n * IsEqual(1.0, 1.00000001); // true\n * IsEqual(1.0, 1.01); // false\n * @endcode\n */\nstatic auto IsEqual(double lhs, double rhs) -> bool;\n```\n\n```\n\n---\n\n### Step 4: 주요 Doxygen 설정 매개변수에 대한 문서화.\n\n#### 1. Doxygen 매개변수 가이드 생성\n\n이 작업은 프로젝트의 `doxyfile.in` 템플릿에 사용된 Doxygen 설정 매개변수를 설명하는 별도의 가이드를 생성합니다. 이 문서는 빌드 시스템 유지 관리자에게 매우 중요합니다. 각 설정의 목적, 값, 영향을 명확히 하고, 특히 CMake에 의해 동적으로 설정되는 값(예: `@PROJECT_NAME@`)에 대해 설명하기 때문입니다.\n\n**파일**: `documents/guidelines/doxygen/parameters.md`\n\n```markdown\n# Doxygen 매개변수 관리 가이드\n\n이 문서는 Doxygen 설정 파일(`doxyfile`)의 주요 매개변수를 효과적으로 관리하기 위한 가이드입니다. 각 매개변수는 기능별로 그룹화되어 있으며, 명확한 이해를 돕기 위해 설명, 사용 가능한 값, 기본값 및 예제를 포함합니다.\n\n이 설정 파일은 CMake와 같은 빌드 시스템과 연동하여 동적으로 변수를 설정하도록 설계되었습니다( `@VAR_NAME@` 형식 사용).\n\n---\n\n## Ⅰ. 기본 프로젝트 설정\n\n이름, 버전, 설명과 같은 기본 프로젝트 정보를 설정합니다.\n\n### `PROJECT_NAME`\n\n- **설명**: 프로젝트의 이름을 지정합니다. 생성된 문서의 제목 및 헤더와 같은 다양한 위치에서 사용됩니다.\n- **값**: 문자열 (빌드 시스템 변수 사용 권장)\n- **기본값**: `\"My Project\"`\n- **예제**: `PROJECT_NAME = \"@PROJECT_NAME@\"`\n\n... (내용이 방대하므로 전체 파일 내용을 여기에 삽입해야 함)\n\n---\n\n## Ⅶ. 소스 브라우징 옵션\n\n생성된 문서 내에서 직접 소스 코드를 탐색하는 것과 관련된 옵션을 설정합니다.\n\n### `SOURCE_BROWSER`\n\n- **설명**: 문서화된 각 파일 및 멤버의 소스 코드를 볼 수 있는 기능을 활성화합니다.\n- **값**: `YES | NO`\n- **기본값**: `NO`\n- **예제**: `SOURCE_BROWSER = YES`\n\n### `INLINE_SOURCES`\n\n- **설명**: 멤버의 소스 코드를 상세 설명 섹션에 직접 삽입합니다. `SOURCE_BROWSER`가 활성화되어야 합니다.\n- **값**: `YES | NO`\n- **기본값**: `NO`\n- **예제**: `INLINE_SOURCES = YES`\n\n### `STRIP_CODE_COMMENTS`\n\n- **설명**: 소스 브라우저에 표시되는 코드에서 주석을 제거할지 여부를 설정합니다.\n- **값**: `YES | NO`\n- **기본값**: `YES`\n- **예제**: `STRIP_CODE_COMMENTS = YES`\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n이 작업은 문서 파일 생성을 포함하므로, 검증은 수동 검토 과정입니다.\n\n1. 로컬 리포지토리의 `documents/guidelines/doxygen/` 디렉터리로 이동합니다.\n2. `ls -1`을 실행하여 두 파일이 모두 있는지 확인합니다.\n3. `coding_styles.md`를 열어 핵심 원칙, 일반 규칙, 구성 요소별 스타일 규칙, 고급 태그에 대한 섹션이 포함되어 있는지 확인합니다.\n4. `parameters.md`를 열어 각 항목에 대한 설명과 함께 범주별로 그룹화된 Doxygen 설정 매개변수의 포괄적인 목록이 포함되어 있는지 확인합니다.\n\n```bash\n# 1. 디렉터리로 이동\ncd documents/guidelines/doxygen/\n\n# 2. 파일 목록을 확인하여 존재 여부 검증\nls -1\n\n# 3. 각 파일의 내용을 수동으로 검토\n# cat coding_styles.md\n# cat parameters.md\n```\n\n### 4.2. 예상 결과\n\n- `ls -1` 명령어는 `coding_styles.md`와 `parameters.md`를 나열해야 합니다.\n- `coding_styles.md`의 수동 검토 결과, 명시된 모든 규칙과 예제가 포함되어 있음을 확인합니다.\n- `parameters.md`의 수동 검토 결과, Doxygen 설정에 대한 잘 구조화된 가이드임을 확인합니다.","Doxygen 스타일 및 매개변수 사용법을 정의하는 마크다운 문서.",[1183,1185,1187,1189],{"_24":1184,"_83":39,"_84":94,"_85":61},"주석 스타일 및 명령어 접두사 정의.",{"_24":1186,"_83":39,"_84":94,"_85":88},"파일, 클래스, 함수 문서화를 위한 스타일 규칙.",{"_24":1188,"_83":39,"_84":94,"_85":91},"`@todo`, `@bug`, `@code`와 같은 고급 태그 사용에 대한 지침.",{"_24":1190,"_83":39,"_84":94,"_85":94},"주요 Doxygen 구성 매개변수에 대한 문서화.","C++ 코드에서 Doxygen 주석을 작성하기 위한 명확한 가이드라인 세트.",{"_22":1193,"_24":1194,"_75":1195,"_77":1196,"_79":1197,"_51":1206,"_42":99},"task-1750998790674","테스트 스위트 코딩 스타일 가이드","# 작업: 테스트 스위트 코딩 스타일 가이드\n\n> **에픽**: 프로젝트 거버넌스 및 코딩 표준\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 단위 및 통합 테스트 작성 표준을 명시하는 문서.\n- **근거**: 프로젝트 내 모든 테스트 코드에 대한 통일된 표준을 수립하기 위함입니다. 이를 통해 테스트의 가독성, 유지보수성 및 자체 문서화(self-documenting)를 보장합니다. 테스트 구조와 네이밍 컨벤션을 표준화하는 것은 프로젝트의 품질 보증 전략의 기반이 되는 자동화된 테스트 발견 및 실행 파이프라인에 매우 중요합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 테스트를 위한 `coding_style.md` 문서. Catch2 프레임워크에 중점을 둡니다.\n- **사양**: 최종 마크다운 문서는 다음 섹션을 포함해야 합니다:\n - 핵심 원칙 (AAA 패턴, 테스트 독립성)\n - 네이밍 컨벤션 (파일, `TEST_CASE` 태그)\n - 스타일 규칙 (AAA 구현, `REQUIRE` 대 `CHECK` 사용법)\n - 자동화된 테스트 등록 및 실행 시스템 가이드.\n - 일반적인 테스트 실행 명령어 표.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── documents/\n# └── guidelines/\n# └── test/\n# └── coding_style.md <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 코딩 스타일 가이드가 개발자 워크플로우에 어떤 영향을 미치고 프로젝트의 자동화된 도구와 어떻게 통합되는지를 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"1단계: 개발\"\n Dev[\"개발자\"] --> ReadGuide[\"'coding_style.md' 읽기\"];\n ReadGuide --> WriteTest[\"테스트 작성/수정
(예: tests/unit/my_feature.cpp)\"];\n end\n\n subgraph \"2단계: 빌드 및 테스트 자동화\"\n WriteTest --> CMake[\"빌드 시스템 (CMake)
configure_tests 호출\"];\n CMake --> RegisterTest[\"CTest로 테스트 발견 및 등록\"];\n RegisterTest --> CTest[\"테스트 실행기 (CTest)
테스트 바이너리 실행\"];\n end\n\n subgraph \"3단계: 품질 게이트\"\n CTest --> Report[\"성공/실패 보고서 생성\"];\n CTest --> Gcovr[\"(활성화된 경우)
커버리지 분석을 위해 gcovr 트리거\"];\n Report --> Feedback[\"개발자에게 피드백\"];\n Gcovr --> Feedback;\n end\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 상세 구현은 3절에 있습니다.\n\n- [ ] 핵심 원칙 정의 (AAA 패턴, 테스트 독립성).\n- [ ] 테스트 파일 및 `TEST_CASE` 태그에 대한 네이밍 컨벤션.\n- [ ] 단언(assertion) 사용 규칙 (`REQUIRE` 대 `CHECK`).\n- [ ] 자동화된 테스트 등록 파이프라인 개요.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층화된 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **테스트 스위트**: 이 작업은 테스트 스위트의 구현을 직접적으로 관장합니다. 여기서 정의된 가이드라인은 Catch2를 사용하는 모든 단위 및 통합 테스트가 어떻게 작성될지를 결정합니다.\n - **모듈식 CMake 빌드 시스템**: 이 가이드는 개발자의 테스트 코드와 빌드 시스템의 자동화된 테스트 발견 메커니즘(`register_test_case.cmake`) 간의 상호 작용을 문서화해야 합니다. 네이밍 컨벤션은 이 상호 작용이 올바르게 작동하는 데 매우 중요합니다.\n - **품질 보증 툴체인**: 이 문서는 QA 툴체인의 핵심 산출물로서, CTest 및 gcovr과 같은 자동화된 도구를 보완하는, 사람이 강제하는 표준을 수립합니다.\n\n### 2.2. 영향을 받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `documents/guidelines/test/coding_style.md`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공할 것입니다.\n\n---\n\n### 단계 1: 핵심 원칙 정의 (AAA 패턴, 테스트 독립성)\n\n#### 1. 문서 헤더 및 핵심 원칙 생성\n\n새 파일을 만들고 문서 헤더, 목차, \"핵심 원칙\" 섹션을 추가합니다. 이 섹션은 모든 테스트에 대한 기본 철학을 수립합니다: 테스트는 명확해야 하고, Arrange-Act-Assert (AAA) 패턴을 사용해야 하며, 결정론적 결과를 보장하기 위해 독립적이어야 합니다. 이것이 모든 후속 규칙의 기초를 마련합니다.\n\n**파일**: `documents/guidelines/test/coding_style.md`\n\n```markdown\n# C++ 테스트 코딩 스타일 규칙\n\n버전 v1.0\n생성일 2025-06-26\n소유자 @movingChurch\n\n---\n\n## 0. 개요\n\n- **목적** C++ 테스트 작성 시 일관성, 가독성, 유지보수성을 보장하기 위한 코딩 표준과 모범 사례를 정의합니다.\n- **범위** 이 프로젝트 내에서 Catch2 프레임워크를 사용하는 모든 테스트 코드 (`tests/**/*.cpp`).\n- **대상** 프로젝트에 기여하는 모든 C++ 개발자.\n\n---\n\n## 1. 목차\n\n1. [핵심 원칙](#2-core-principles)\n2. [네이밍 컨벤션](#3-naming-conventions)\n3. [스타일 규칙](#4-style-rules)\n4. [테스트 시스템 가이드](#5-test-system-guide)\n5. [테스트 실행 및 관리](#6-test-execution--management)\n\n---\n\n## 2. 핵심 원칙\n\n### 원칙 1 테스트는 명확하고 읽기 쉬워야 합니다\n\n- **범위** 모든 테스트 케이스.\n- **근거** 테스트는 시스템 동작의 살아있는 문서 역할을 합니다. 명확한 테스트는 이해하고 유지보수하기 쉬워 실패를 진단하기 간단합니다. Arrange-Act-Assert (AAA) 패턴은 이를 달성하기 위한 주요 도구입니다.\n\n### 원칙 2 테스트는 독립적이고 반복 가능해야 합니다\n\n- **범위** 모든 테스트 케이스.\n- **근거** 각 테스트는 다른 테스트의 상태에 의존하지 않고 독립적으로 실행되어야 합니다. 이는 테스트 결과가 결정적이고 실행 순서에 영향을 받지 않도록 보장하며, 신뢰할 수 있는 CI/CD 파이프라인에 매우 중요합니다.\n```\n\n---\n\n### 단계 2: 테스트 파일 및 `TEST_CASE` 태그에 대한 네이밍 컨벤션\n\n#### 1. 네이밍 컨벤션 섹션 추가\n\n문서에 \"네이밍 컨벤션\" 섹션을 추가합니다. 이 섹션은 자동화된 테스트 등록 파이프라인이 테스트 파일명과 그 안의 `TEST_CASE` 태그 간의 엄격한 일치에 의존하기 때문에 매우 중요합니다. 이 규칙은 수동 테스트 등록을 없애고 모든 새 테스트가 CMake에 의해 자동으로 발견되도록 보장합니다.\n\n**파일**: `documents/guidelines/test/coding_style.md`\n\n```markdown\n...\n\n---\n\n## 3. 네이밍 컨벤션\n\n> **설명** 일관된 네이밍은 자동화된 테스트 등록 및 실행 시스템에 매우 중요합니다.\n\n| 코드 요소 | 네이밍 스타일 | 예시 |\n| :--- | :--- | :--- |\n| 테스트 파일 | `snake_case.cpp` | `my_feature.cpp` |\n| `TEST_CASE` 태그 | `[snake_case]` | `[my_feature]` |\n| `TEST_CASE` 이름 | 설명적인 문장 | `\"나의 새로운 기능 검증\"` |\n\n---\n```\n\n---\n\n### 단계 3: 단언 사용 규칙 (`REQUIRE` 대 `CHECK`)\n\n#### 1. 스타일 규칙 섹션 추가\n\n구체적인 구현 지침을 제공하는 \"스타일 규칙\" 섹션을 추가합니다. 명확한 코드 예제와 함께 AAA 패턴 사용을 의무화합니다. 또한 테스트를 중단해야 하는 치명적인 검사를 위한 `REQUIRE`와 테스트가 계속되도록 허용하는 치명적이지 않은 검사를 위한 `CHECK` 간의 중요한 차이점을 정의하여 보다 포괄적인 실패 보고를 가능하게 합니다.\n\n**파일**: `documents/guidelines/test/coding_style.md`\n\n```markdown\n...\n\n## 4. 스타일 규칙\n\n### 4.1 테스트 구조\n\n#### 규칙 1 Arrange-Act-Assert (AAA) 패턴을 사용하여 테스트를 구조화합니다\n\n- **범위** 모든 `TEST_CASE` 블록의 본문.\n- **근거** AAA 패턴은 명확하고 일관된 구조를 제공하여 테스트 설정, 실행, 검증을 분리합니다. 이는 가독성과 유지보수성을 크게 향상시킵니다.\n\n```cpp\n# GOOD\nTEST_CASE(\"나의 새로운 기능 검증\", \"[my_feature]\") {\n // Arrange: 테스트 조건 설정\n int input = 2;\n int expected = 4;\n\n // Act: 테스트 대상 코드 실행\n int result = my_project::MyFunction(input);\n\n // Assert: 결과 검증\n REQUIRE(result == expected);\n}\n\n# BAD\nTEST_CASE(\"기능 테스트\", \"[my_feature]\") {\n // 불분명한 구조, 설정과 단언이 혼재됨\n REQUIRE(my_project::MyFunction(2) == 4);\n}\n```\n\n### 4.2 네이밍 및 태깅\n\n#### 규칙 1 `TEST_CASE` 태그는 파일명과 일치해야 합니다\n\n- **범위** 모든 `TEST_CASE` 선언.\n- **근거** 빌드 시스템은 파일명을 사용하여 CTest를 위한 테스트 이름과 태그를 생성합니다. 일치하는 태그(예: `my_feature.cpp`에 대한 `[my_feature]`)는 테스트가 자동으로 발견되고 실행되기 위해 **필수**입니다.\n\n```cpp\n# GOOD\n// 파일: tests/unit/my_feature.cpp\nTEST_CASE(\"나의 새로운 기능 검증\", \"[my_feature]\") {\n // ...\n}\n\n# BAD\n// 파일: tests/unit/my_feature.cpp\nTEST_CASE(\"나의 새로운 기능 검증\", \"[some_other_tag]\") {\n // 이 테스트는 CTest 필터에 의해 올바르게 등록되거나 실행되지 않습니다.\n}\n```\n\n### 4.3 단언\n\n#### 규칙 1 중요한 검사에는 `REQUIRE`를 사용합니다\n\n- **범위** 모든 단언.\n- **근거** `REQUIRE`는 실패 시 즉시 테스트 케이스를 중단합니다. 검사가 실패하면 나머지 테스트 케이스가 의미가 없는 경우(예: 객체를 사용하기 전에 생성되었는지 확인)에 사용합니다.\n\n#### 규칙 2 중요하지 않은 검사에는 `CHECK`를 사용합니다\n\n- **범위** 모든 단언.\n- **근거** `CHECK`는 실패를 보고하지만 테스트 케이스가 계속 진행되도록 합니다. 이는 객체의 여러 속성을 검증할 때 유용하며, 첫 번째 실패만 보는 대신 모든 실패를 한 번에 볼 수 있게 해줍니다.\n\n```cpp\n# GOOD\nTEST_CASE(\"객체 속성 검증\", \"[object_test]\") {\n // Arrange\n MyObject obj = CreateObject();\n\n // Assert\n REQUIRE(obj.IsValid()); // 객체가 유효하지 않으면 이후 검사는 의미가 없습니다.\n \n CHECK(obj.GetPropertyA() == \"expected_A\");\n CHECK(obj.GetPropertyB() == \"expected_B\");\n}\n```\n\n---\n\n```\n\n---\n\n### 단계 4: 자동화된 테스트 등록 파이프라인 개요.\n\n#### 1. 테스트 시스템 가이드 및 실행 섹션 추가\n\n마지막 섹션인 \"테스트 시스템 가이드\"와 \"테스트 실행 및 관리\"를 추가합니다. 이 내용은 개발자 생산성에 매우 중요합니다. CMake 모듈(`register_test_case.cmake`, `check_code_coverage.cmake`)이 내부적으로 어떻게 작동하는지 설명하여 테스트 자동화 아키텍처를 명확히 합니다. 개발자가 효율적으로 작업을 검증할 수 있도록 테스트 실행 및 관리를 위한 실용적인 커맨드 라인 참조로 마무리합니다.\n\n**파일**: `documents/guidelines/test/coding_style.md`\n\n```markdown\n...\n\n## 5. 테스트 시스템 가이드\n\n### 5.1 전제 조건\n\n- **설명**: 테스트 자동화 파이프라인에는 특정 의존성이 필요합니다. 주요 의존성은 코드 커버리지 분석을 위한 `gcovr`입니다.\n- **설치**: OS별 설치 스크립트는 `script/os/` 디렉토리에 제공됩니다.\n\n- **macOS**:\n\n ```bash\n ./test/script/os/macos/install_gcovr.sh\n ```\n\n- **Ubuntu**:\n\n ```bash\n ./test/script/os/ubuntu/install_gcovr.sh\n ```\n\n### 5.2 자동화된 테스트 파이프라인\n\n- **1. 구현**: 개발자는 정의된 규칙에 따라 `tests/` 디렉토리 내에 테스트 소스 코드를 작성합니다.\n- **2. 등록 (CMake)**: 빌드 시, CMake는 `test/cmake/register_test_case.cmake` 모듈을 통해 자동으로 새 테스트 파일을 발견하고 CTest 스위트에 등록합니다.\n- **3. 실행 (CTest)**: 빌드가 성공하면, `run_all_tests` 타겟의 `POST_BUILD` 명령이 CTest를 트리거하여 등록된 모든 테스트를 실행합니다.\n- **4. 품질 보증 (gcovr)**: 코드 커버리지가 활성화된 경우 (`ENABLE_COVERAGE=ON`), `test/cmake/check_code_coverage.cmake` 모듈은 `gcovr`를 호출하여 커버리지를 분석합니다. 테스트가 실패하거나 커버리지 지표가 요구되는 임계값 미만이면 빌드가 실패하여 코드 품질을 강제합니다.\n\n### 5.3 시스템 아키텍처\n\n- **`CMakeLists.txt` (루트)**\n - `BUILD_TESTING`: 전체 테스트 빌드 프로세스를 활성화하거나 비활성화하는 전역 옵션입니다.\n - `CMAKE_MODULE_PATH`: `test/cmake/` 디렉토리를 모듈 검색 경로에 추가하여 `include()`를 통해 커스텀 함수를 호출할 수 있도록 합니다.\n - `FUNCTION_COVERAGE` / `LINE_COVERAGE`: `gcovr`에 대한 최소 커버리지 임계값을 정의합니다.\n\n- **`test/cmake/register_test_case.cmake`**\n - **목적**: 테스트 소스 파일을 CTest 케이스로 변환합니다.\n - **프로세스**:\n 1. CTest를 위한 고유한 테스트 이름(예: `unit.my_feature`)과 Catch2를 위한 태그(예: `[my_feature]`)를 파일 경로에서 생성합니다.\n 2. 개별 실행을 허용하는 명령(예: `run_all_tests [my_feature]`)을 지정하여 `add_test`를 통해 테스트를 등록합니다.\n 3. 그룹 실행을 위해 최상위 디렉토리를 기반으로 레이블(예: `unit`)을 할당합니다.\n\n- **`test/cmake/check_code_coverage.cmake`**\n - **목적**: 커버리지 측정 및 검증을 자동화합니다.\n - **프로세스**:\n 1. `--coverage` 컴파일러 및 링커 플래그를 빌드 타겟에 추가하여 GCC/Clang이 커버리지 데이터를 생성하도록 지시합니다.\n 2. `gcovr`를 실행하는 빌드 후 명령을 추가합니다. `gcovr`는 임계값에 대해 커버리지를 검증하고 HTML 보고서를 생성합니다.\n\n---\n\n## 6. 테스트 실행 및 관리\n\n- **컨텍스트**: 모든 명령어는 `build/` 디렉토리에서 실행됩니다.\n\n| 카테고리 | 명령어 | 설명 |\n| -------------------- | ------------------------------------- | --------------------------------------------------------------- |\n| **표준 워크플로**| `cmake --build .` | 한 단계로 빌드, 모든 테스트 실행, 커버리지 검증을 수행합니다. |\n| **모든 테스트 재실행** | `ctest` | 기존 빌드에서 모든 테스트를 실행합니다. |\n| **그룹 실행** | `ctest -L unit` | `unit` 레이블이 있는 테스트만 실행합니다. |\n| **개별 테스트** | `ctest -R my_feature` | 이름이 정규식 `my_feature`와 일치하는 테스트를 실행합니다. |\n| **디버깅** | `./tests/run_all_tests [my_feature]` | CTest를 우회하여 테스트 실행 파일을 직접 실행합니다. |\n\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n1. 프로젝트의 루트 디렉토리로 이동합니다.\n2. 다음 명령어를 실행하여 파일이 생성되었는지 확인합니다.\n```bash\nls documents/guidelines/test/coding_style.md\n```\n\n3. 파일의 내용을 수동으로 검토하여 인수 조건에 명시된 모든 섹션이 포함되어 있는지 확인합니다:\n - 핵심 원칙\n - 네이밍 컨벤션\n - 스타일 규칙 (AAA 및 단언 포함)\n - 테스트 시스템 가이드\n - 테스트 실행 및 관리\n\n### 4.2. 예상 결과\n\n- `ls` 명령어는 오류 없이 파일 경로를 성공적으로 나열해야 합니다.\n- `documents/guidelines/test/coding_style.md` 파일의 내용은 구현 단계에서 명시된 마크다운과 일치해야 합니다.\n\n```\ndocuments/guidelines/test/coding_style.md\n```\n","Catch2 프레임워크에 초점을 맞춘 테스트용 `coding_style.md` 문서.",[1198,1200,1202,1204],{"_24":1199,"_83":39,"_84":97,"_85":61},"핵심 원칙(AAA 패턴, 테스트 독립성) 정의.",{"_24":1201,"_83":39,"_84":97,"_85":88},"테스트 파일 및 `TEST_CASE` 태그에 대한 이름 지정 규칙.",{"_24":1203,"_83":39,"_84":97,"_85":91},"단언 사용 규칙 (`REQUIRE` 대 `CHECK`).",{"_24":1205,"_83":39,"_84":97,"_85":94},"자동화된 테스트 등록 파이프라인 개요.","단위 및 통합 테스트 작성을 위한 표준을 명시하는 문서.",{"_22":1208,"_24":1209,"_75":1210,"_77":1211,"_79":1212,"_51":1221,"_42":99},"task-1750998833876","공통 CMake 유틸리티 함수","# 작업: 공용 CMake 유틸리티 함수\n\n> **에픽**: 기반 CMake 유틸리티 및 모듈\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 여러 CMake 모듈에서 공통으로 사용되는 범용 헬퍼 함수 세트.\n- **근거**: 빌드 시스템 전반에 걸쳐 코드 재사용성과 유지보수성을 증진하는 저수준의 재사용 가능한 CMake 함수 라이브러리를 구축합니다. 이러한 유틸리티는 \"계층적 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\" 아키텍처의 기반 계층을 형성합니다. 공통 로직(예: 문자열 조작, 디렉터리 스캔)을 캡슐화함으로써, 상위 수준의 인터페이스 모듈이 깔끔하고 선언적이며 주요 구성 작업에 집중할 수 있도록 합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: `cmake/common/` 디렉터리에 재사용 가능한 로직을 제공하는 `.cmake` 파일 모음.\n- **사양**:\n - `함수: convert_to_uppercase_with_underscores(INPUT_STRING OUTPUT_VARIABLE_NAME)`: 문자열에서 하이픈과 공백을 밑줄로 바꾸고 대문자로 변환합니다.\n - `함수: configure_subdirectory(DIRECTORY_PATH)`: `CMakeLists.txt` 파일이 포함된 경우 단일 하위 디렉터리를 빌드에 추가합니다.\n - `함수: add_subdirectories(DIRECTORY_PATH)`: 상위 디렉터리를 스캔하고 각 하위 디렉터리에 대해 `configure_subdirectory`를 호출합니다.\n- **결과 파일 구조**\n\n```bash\n./\n└── cmake/\n └── common/\n ├── add_subdirectories.cmake <-- New\n ├── configure_subdirectory.cmake <-- New\n └── convert_to_uppercase_with_underscores.cmake <-- New\n```\n\n- **프로세스 흐름도**\n이 다이어그램은 상위 수준의 CMake 스크립트가 이러한 유틸리티 함수를 사용하여 하위 프로젝트의 구성을 자동화하는 방법을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n HigherLevelScript[\"상위 수준 CMake 스크립트
(예: `cmake/interface` 내)\"]\n \n subgraph 기반 CMake 유틸리티\n direction LR\n AddSubdirectories[\"add_subdirectories(DIRECTORY_PATH)\"]\n ConfigureSubdirectory[\"configure_subdirectory(DIRECTORY_PATH)\"]\n end\n \n HigherLevelScript -- \"'source/'와 같은 기본 경로에 대해 호출\" --> AddSubdirectories\n AddSubdirectories -- \"찾은 각 하위 디렉터리에 대해\" --> ConfigureSubdirectory\n ConfigureSubdirectory -- \"CMakeLists.txt가 있으면 빌드에 추가\" --> CMakeBuild[\"CMake 빌드 프로세스\"]\n\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이것은 개략적인 체크리스트이며, 각 항목에 대한 자세한 구현은 3장에 있습니다.\n\n- [ ] 문자열 변환 유틸리티 (`convert_to_uppercase_with_underscores.cmake`).\n- [ ] 하위 디렉터리 검색 및 포함 유틸리티 (`add_subdirectories.cmake`).\n- [ ] 단일 하위 디렉터리 구성을 위한 헬퍼 (`configure_subdirectory.cmake`).\n- [ ] 공용 유틸리티 모듈 완료 및 테스트.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층적 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **모듈식 CMake 빌드 시스템**: 이 작업은 이 구성 요소의 가장 낮은 기반 계층을 직접 구현합니다. 이러한 유틸리티는 나머지 빌드 시스템을 구축하는 기반이 되는 빌딩 블록입니다.\n - **상위 수준 CMake 인터페이스 모듈** (향후 에픽에서 구현 예정): 이 모듈들은 이번 작업에서 생성된 함수의 주된 소비자가 될 것입니다. 예를 들어, `configure_library`는 `add_subdirectories`를 사용하여 `source/` 디렉터리 내의 모든 라이브러리 모듈을 자동으로 찾아 빌드합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `cmake/common/add_subdirectories.cmake`\n- `cmake/common/configure_subdirectory.cmake`\n- `cmake/common/convert_to_uppercase_with_underscores.cmake`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 세부적인 `조치`로 나뉩니다. 각 `조치`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 문자열 변환 유틸리티 (`convert_to_uppercase_with_underscores.cmake`)\n\n#### 1. `convert_to_uppercase_with_underscores` 함수 구현\n\n이 조치는 문자열 정리를 위한 독립적인 CMake 함수를 생성합니다. 그 목적은 다양한 입력(예: \"my-library\" 또는 \"My Library\"와 같은 디렉터리 이름)에서 파생된 변수에 대해 일관된 명명 규칙을 적용하는 것입니다. 문자열을 표준 `UPPERCASE_WITH_UNDERSCORES` 형식으로 변환함으로써, 빌드 스크립트에서 나중에 사용될 변수 이름의 예측 가능성을 보장합니다. 이 함수는 입력 문자열과 출력 변수 이름을 받아, 호출자가 사용할 수 있도록 부모 스코프에 결과를 설정합니다.\n\n**파일**: `cmake/common/convert_to_uppercase_with_underscores.cmake`\n\n```cmake\n# Description:\n# Converts a string to uppercase, replacing hyphens and spaces with underscores.\n#\n# Arguments:\n# INPUT_STRING: The string to convert.\n# OUTPUT_VARIABLE_NAME: The variable to store the result in the parent scope.\nfunction(convert_to_uppercase_with_underscores INPUT_STRING OUTPUT_VARIABLE_NAME)\n # --- Function Start: convert_to_uppercase_with_underscores\n if(NOT INPUT_STRING)\n message(FATAL_ERROR \"convert_to_uppercase_with_underscores() requires 'INPUT_STRING'.\")\n endif()\n\n if(NOT OUTPUT_VARIABLE_NAME)\n message(FATAL_ERROR \"convert_to_uppercase_with_underscores() requires 'OUTPUT_VARIABLE_NAME'.\")\n endif()\n\n string(REPLACE \"-\" \"_\" converted_string \"${INPUT_STRING}\")\n string(REPLACE \" \" \"_\" converted_string \"${converted_string}\")\n string(TOUPPER \"${converted_string}\" converted_string)\n set(${OUTPUT_VARIABLE_NAME} ${converted_string} PARENT_SCOPE)\n\n # --- Function End: convert_to_uppercase_with_underscores\nendfunction()\n```\n\n---\n\n### 단계 2: 하위 디렉터리 검색 및 포함 유틸리티 (`add_subdirectories.cmake`)\n\n#### 1. `add_subdirectories` 함수 구현\n\n이 조치는 주어진 경로 내에서 하위 디렉터리를 자동으로 검색하는 함수를 생성합니다. 그 목적은 빌드 시스템을 확장 가능하게 만드는 것입니다. 새로운 라이브러리나 테스트 모듈을 수동으로 추가하는 대신, 이 함수를 통해 부모 `CMakeLists.txt`가 모든 자식 디렉터리를 자동으로 포함할 수 있습니다. `file(GLOB ...)`를 사용하여 모든 항목을 찾은 다음, 반복하면서 발견된 각 디렉터리를 처리를 위해 `configure_subdirectory` 헬퍼 함수(다음 단계에서 생성)에 전달합니다. 이 함수는 `configure_subdirectory`가 필요하므로, 나중 단계에서 `include` 구문을 추가할 것입니다.\n\n**파일**: `cmake/common/add_subdirectories.cmake`\n\n```cmake\n# Description:\n# Adds all direct subdirectories of a given directory to the build.\n#\n# Arguments:\n# DIRECTORY_PATH: The path to the parent directory.\nfunction(add_subdirectories DIRECTORY_PATH)\n # --- Function Start: add_subdirectories\n if(NOT DIRECTORY_PATH)\n message(FATAL_ERROR \"add_subdirectories() requires the 'DIRECTORY_PATH' argument.\")\n endif()\n\n if(NOT IS_DIRECTORY \"${DIRECTORY_PATH}\")\n message(FATAL_ERROR \"Argument '${DIRECTORY_PATH}' is not a valid directory.\")\n endif()\n\n file(GLOB sub_directories\n CONFIGURE_DEPENDS\n RELATIVE \"${DIRECTORY_PATH}\"\n \"${DIRECTORY_PATH}/*\"\n )\n\n foreach(sub_directory ${sub_directories})\n if(IS_DIRECTORY \"${DIRECTORY_PATH}/${sub_directory}\")\n configure_subdirectory(\"${DIRECTORY_PATH}/${sub_directory}\")\n endif()\n endforeach()\n\n # --- Function End: add_subdirectories\nendfunction()\n```\n\n---\n\n### 단계 3: 단일 하위 디렉터리 구성을 위한 헬퍼 (`configure_subdirectory.cmake`)\n\n#### 1. `configure_subdirectory` 함수 구현\n\n이 조치는 단일 하위 디렉터리 처리를 담당하는 집중된 헬퍼 함수를 생성합니다. 그 목적은 디렉터리를 빌드에 추가하는 로직을 중앙 집중화하는 것입니다. `add_subdirectory()`를 호출하기 전에 `CMakeLists.txt` 파일의 존재 여부를 확실하게 확인하여, 디렉터리에 빌드 스크립트가 없는 경우 빌드 오류를 방지합니다. 또한 명확한 `STATUS` 메시지를 제공하여 빌드 로그의 가독성을 높이고 어떤 디렉터리가 구성되고 있는지 디버깅하기 쉽게 만듭니다.\n\n**파일**: `cmake/common/configure_subdirectory.cmake`\n\n```cmake\n# Description:\n# Configures a subdirectory by adding it to the build if it contains a CMakeLists.txt file.\n#\n# Arguments:\n# DIRECTORY_PATH: The path to the subdirectory to configure.\nfunction(configure_subdirectory DIRECTORY_PATH)\n # --- Function Start: configure_subdirectory\n if(NOT DIRECTORY_PATH)\n message(FATAL_ERROR \"configure_subdirectory() requires the 'DIRECTORY_PATH' argument.\")\n endif()\n\n get_filename_component(subdirectory_name \"${DIRECTORY_PATH}\" NAME)\n\n message(STATUS \"-- Configuring subdirectory: ${subdirectory_name} (${DIRECTORY_PATH})\")\n\n if(EXISTS \"${DIRECTORY_PATH}/CMakeLists.txt\")\n add_subdirectory(\"${DIRECTORY_PATH}\")\n message(STATUS \"-- Finished configuring subdirectory: ${subdirectory_name}\")\n else()\n message(STATUS \"-- No CMakeLists.txt found in ${subdirectory_name}, skipping configuration.\")\n endif()\n\n # --- Function End: configure_subdirectory\nendfunction()\n```\n\n---\n\n### 단계 4: 공용 유틸리티 모듈 완료 및 테스트\n\n#### 1. `add_subdirectories`와 `configure_subdirectory` 간의 의존성 설정\n\n이 조치는 모듈 연결을 마무리합니다. `add_subdirectories` 함수는 작업을 수행하기 위해 논리적으로 `configure_subdirectory`에 의존합니다. `add_subdirectories.cmake` 내에서 `configure_subdirectory` 함수를 사용할 수 있도록 하려면, 파일 상단에 `include()` 구문을 추가해야 합니다. 이는 의존성을 명시적으로 선언하고 모듈이 함께 사용될 때 올바르게 작동하도록 보장합니다.\n\n**파일**: `cmake/common/add_subdirectories.cmake`\n\n```cmake\ninclude(${CMAKE_SOURCE_DIR}/cmake/common/configure_subdirectory.cmake)\n\n# Description:\n# Adds all direct subdirectories of a given directory to the build.\n#\n...\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n이 유틸리티 함수들의 올바른 구현을 검증하기 위해, 개발자는 임시 테스트 구조와 이를 호출하는 `CMakeLists.txt` 파일을 생성한 다음, `cmake`를 실행해야 합니다.\n\n```bash\n# 1. Create a temporary test directory structure\nmkdir -p build_test/test_dir/sub1 build_test/test_dir/sub2 build_test/empty_sub\ntouch build_test/test_dir/sub1/CMakeLists.txt\ntouch build_test/test_dir/sub2/CMakeLists.txt\n\n# 2. Create a test CMakeLists.txt file to invoke the functions\n# File: build_test/CMakeLists.txt\ncat <<'EOF' > build_test/CMakeLists.txt\ncmake_minimum_required(VERSION 3.15)\nproject(UtilityTest)\n\n# Include the newly created utility modules\ninclude(${CMAKE_SOURCE_DIR}/cmake/common/add_subdirectories.cmake)\ninclude(${CMAKE_SOURCE_DIR}/cmake/common/convert_to_uppercase_with_underscores.cmake)\n\n# Test string conversion\nmessage(STATUS \"--- Testing string conversion ---\")\nconvert_to_uppercase_with_underscores(\"my-test string\" MY_TEST_VAR)\nmessage(STATUS \"Converted string: ${MY_TEST_VAR}\")\n\n# Test subdirectory addition\nmessage(STATUS \"--- Testing subdirectory addition ---\")\nadd_subdirectories(\"${CMAKE_CURRENT_SOURCE_DIR}/test_dir\")\nadd_subdirectories(\"${CMAKE_CURRENT_SOURCE_DIR}/empty_sub\")\nEOF\n\n# 3. Configure the project with CMake from a build directory\ncmake -S build_test -B build_test/build\n```\n\n### 4.2. 예상 결과\n\n`cmake` 명령어의 출력은 다음 상태 메시지를 포함해야 하며, 이를 통해 문자열이 올바르게 변환되고 하위 디렉터리들이 예상대로 처리되었음(sub1과 sub2는 구성되고, empty_sub는 건너뜀)을 확인합니다.\n\n```\n-- C 컴파일러 식별은 ...\n-- CXX 컴파일러 식별은 ...\n...\n-- --- 문자열 변환 테스트 ---\n-- 변환된 문자열: MY_TEST_STRING\n-- --- 하위 디렉터리 추가 테스트 ---\n-- 하위 디렉터리 구성 중: sub1 (.../build_test/test_dir/sub1)\n-- 하위 디렉터리 구성 완료: sub1\n-- 하위 디렉터리 구성 중: sub2 (.../build_test/test_dir/sub2)\n-- 하위 디렉터리 구성 완료: sub2\n-- 하위 디렉터리 구성 중: empty_sub (.../build_test/empty_sub)\n-- empty_sub에서 CMakeLists.txt를 찾을 수 없어 구성을 건너뜁니다.\n-- 구성 완료\n-- 생성 완료\n-- 빌드 파일이 다음 위치에 작성되었습니다: .../build_test/build\n```\n","재사용 가능한 로직을 제공하는 `cmake/common/` 내의 `.cmake` 파일 모음.",[1213,1215,1217,1219],{"_24":1214,"_83":39,"_84":176,"_85":61},"문자열 변환 유틸리티 (`convert_to_uppercase_with_underscores.cmake`).",{"_24":1216,"_83":39,"_84":176,"_85":88},"하위 디렉토리 검색 및 포함 유틸리티 (`add_subdirectories.cmake`).",{"_24":1218,"_83":39,"_84":176,"_85":91},"단일 하위 디렉토리 구성을 위한 헬퍼 (`configure_subdirectory.cmake`).",{"_24":1220,"_83":39,"_84":176,"_85":94},"완전하고 테스트된 공통 유틸리티 모듈.","여러 CMake 모듈에서 사용되는 범용 헬퍼 함수 세트.",{"_22":1223,"_24":1224,"_75":1225,"_77":1226,"_79":1227,"_51":1236,"_42":99},"task-1750998900266","프로젝트 전역 구성 모듈","# 작업: 프로젝트 전반의 설정 모듈\n\n> **에픽**: 기본적인 CMake 유틸리티 및 모듈\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 전역 프로젝트 환경 설정을 담당하는 CMake 모듈.\n- **근거**: 이 작업은 \"계층적 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\" 아키텍처의 기반이 됩니다. 프로젝트 설정(경로, 플래그, 상세 출력)을 위해 개별적이고 단일 책임을 갖는 CMake 함수를 생성함으로써, 일관되고 유지보수 가능한 기본 레이어를 구축합니다. 이는 설정의 불일치를 방지하고, 상위 레벨 스크립트의 중복을 줄이며, 빌드 시스템의 모든 부분이 잘 정의된 단일 환경에서 동작하도록 보장합니다. 이는 견고하고 가독성 높은 CMake 아키텍처라는 프로젝트의 핵심 목표를 직접적으로 지원합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 경로, 플래그, 빌드 설정을 초기화하기 위한 `cmake/project/` 디렉터리의 `.cmake` 파일 세트.\n- **사양**:\n - `function(initialize_project_paths project_name_prefix)`: 프로젝트 디렉터리 경로 변수를 정의하고 부모 스코프로 내보냅니다.\n - `function(configure_default_compiler_flags)`: 컴파일러 ID와 플랫폼에 따라 기본 컴파일러 플래그를 설정하고 내보냅니다.\n - `function(configure_makefile_verbosity)`: 현재 `CMAKE_BUILD_TYPE`에 따라 `CMAKE_VERBOSE_MAKEFILE`을 설정합니다.\n - `function(print_project_summary project_name_prefix)`: 빌드 설정에 대한 형식화된 요약을 콘솔에 출력합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── cmake/\n# └── project/\n# ├── configure_default_compiler_flags.cmake <-- 신규\n# ├── configure_makefile_verbosity.cmake <-- 신규\n# ├── initialize_project_paths.cmake <-- 신규\n# └── print_project_summary.cmake <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 상위 레벨 인터페이스 함수(예: `configure_project`)가 CMake 설정 단계에서 빌드 환경을 구축하기 위해 이러한 기본 모듈들을 어떻게 호출하는지 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph CMake 설정 단계\n direction TB\n A[\"상위 레벨 인터페이스
(예: configure_project)\"] --> B[\"initialize_project_paths 호출\"];\n A --> C[\"configure_default_compiler_flags 호출\"];\n A --> D[\"configure_makefile_verbosity 호출\"];\n A --> E[\"print_project_summary 호출\"];\n \n B --> F{\"
설정
READABLE_CODE_CPP_PROJECT_TEMPLATE_ROOT_PATH
등
\"};\n C --> G{\"
설정
COMPILER_FLAGS
\"};\n D --> H{\"
설정
CMAKE_VERBOSE_MAKEFILE
\"};\n E --> I[(\"설정 요약
콘솔에 출력\")];\n end\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 레벨의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3장에 있습니다.\n\n- [ ] 경로 초기화 모듈 (`initialize_project_paths.cmake`).\n- [ ] 기본 컴파일러 플래그 설정 모듈 (`configure_default_compiler_flags.cmake`).\n- [ ] Makefile 상세 출력 제어 모듈 (`configure_makefile_verbosity.cmake`).\n- [ ] 프로젝트 요약 출력 모듈 (`print_project_summary.cmake`).\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층적 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **모듈식 CMake 빌드 시스템**: 이 작업은 이 구성 요소의 가장 낮고 기본적인 계층을 직접 구현합니다. 이러한 유틸리티 모듈들은 환경 설정을 위한 핵심 로직을 제공합니다. 이들은 컨텍스트에 구애받지 않고 재사용 가능하도록 설계되었으며, 상위 레벨 인터페이스 모듈(에픽 3)과 최상위 빌드 오케스트레이션 스크립트(에픽 5)를 위한 빌딩 블록 역할을 합니다. 이들은 경로 및 컴파일러 설정에 대한 \"단일 진실 공급원(single source of truth)\"을 확립합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `cmake/project/initialize_project_paths.cmake`\n- `cmake/project/configure_default_compiler_flags.cmake`\n- `cmake/project/configure_makefile_verbosity.cmake`\n- `cmake/project/print_project_summary.cmake`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 세분화된 일련의 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공할 것입니다.\n\n---\n\n### 단계 1: 경로 초기화 모듈 (`initialize_project_paths.cmake`)\n\n#### 1. `initialize_project_paths.cmake` 모듈 생성\n\n이 액션은 모든 중요한 프로젝트 디렉터리 경로의 정의를 중앙 집중화하는 CMake 함수를 생성합니다. 이는 `project_name_prefix` 인수를 받아 네임스페이스가 있는 변수(예: `MY_PROJECT_ROOT_PATH`)를 만들어 다른 CMake나 시스템 변수와의 충돌을 방지합니다. 이러한 변수들을 `PARENT_SCOPE`로 내보내면 호출하는 스크립트에서 사용할 수 있게 되어, 빌드 시스템 전체에서 디렉터리를 참조하는 일관되고 신뢰할 수 있는 방법을 확립합니다.\n\n**파일**: `cmake/project/initialize_project_paths.cmake`\n\n```cmake\n# 설명:\n# 주어진 접두사를 사용하여 표준 프로젝트 디렉터리 경로 변수를 초기화합니다.\n# 접두사는 일반적으로 대문자 프로젝트 이름입니다 (예: MY_PROJECT).\n#\n# 인수:\n# project_name_prefix (string): 경로 변수에 사용할 프로젝트 이름 접두사 (관례적으로 대문자와 밑줄 사용)\n# (예: MY_PROJECT_ROOT_PATH).\nfunction(initialize_project_paths project_name_prefix)\n # --- 함수 시작: initialize_project_paths\n if(NOT project_name_prefix)\n message(FATAL_ERROR \"initialize_project_paths: project_name_prefix 인수가 필요합니다.\")\n return()\n endif()\n\n set(${project_name_prefix}_ROOT_PATH \"${CMAKE_CURRENT_SOURCE_DIR}\" PARENT_SCOPE)\n set(${project_name_prefix}_SOURCE_PATH \"${CMAKE_CURRENT_SOURCE_DIR}/source\" PARENT_SCOPE)\n set(${project_name_prefix}_INCLUDE_PATH \"${CMAKE_CURRENT_SOURCE_DIR}/include\" PARENT_SCOPE)\n set(${project_name_prefix}_BUILD_PATH \"${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_BUILD_TYPE}\" PARENT_SCOPE)\n set(${project_name_prefix}_INTERNALS_PATH \"${CMAKE_CURRENT_SOURCE_DIR}/dependencies/internals\" PARENT_SCOPE)\n set(${project_name_prefix}_EXECUTABLES_PATH \"${CMAKE_CURRENT_SOURCE_DIR}/executables\" PARENT_SCOPE)\n set(${project_name_prefix}_EXTERNALS_PATH \"${CMAKE_CURRENT_SOURCE_DIR}/dependencies/externals\" PARENT_SCOPE)\n set(${project_name_prefix}_CMAKE_MODULE_PATH \"${CMAKE_CURRENT_SOURCE_DIR}/cmake\" PARENT_SCOPE)\n\n message(STATUS \"프로젝트 경로가 다음 접두사로 초기화되었습니다: ${project_name_prefix}\")\n\n # --- 함수 끝: initialize_project_paths\nendfunction()\n```\n\n---\n\n### 단계 2: 기본 컴파일러 플래그 설정 모듈 (`configure_default_compiler_flags.cmake`)\n\n#### 1. `configure_default_compiler_flags.cmake` 모듈 생성\n\n이 액션은 일관된 컴파일러 플래그 세트를 강제하는 함수를 생성합니다. 이 함수는 `COMPILER_FLAGS`가 이미 정의되었는지 확인하여 오버라이드를 허용하지만, 그렇지 않은 경우 컴파일러 제품군(MSVC 대 GCC/Clang)에 따라 합리적인 기본값을 제공합니다. 이는 품질 관리를 자동화하고 모든 코드가 동일한 표준으로 빌드되도록 보장합니다. 또한 macOS SDK 위치를 찾고 `isysroot` 플래그를 설정하는 것과 같은 플랫폼별 요구 사항을 처리하는데, 이는 Darwin 시스템에서 올바른 컴파일을 위해 매우 중요합니다.\n\n**파일**: `cmake/project/configure_default_compiler_flags.cmake`\n\n```cmake\n# 설명:\n# 변수가 아직 정의되지 않은 경우 기본 컴파일러 플래그(COMPILER_FLAGS)를 설정합니다.\n# CMAKE_CXX_COMPILER_ID (MSVC 또는 GCC/Clang)에 따라 플래그를 선택합니다.\nfunction(configure_default_compiler_flags)\n # --- 함수 시작: configure_default_compiler_flags\n set(_DEFAULT_COMPILER_FLAGS)\n\n # macOS: 올바른 SDK를 찾고 컴파일러가 사용하도록 -isysroot 플래그를 추가\n if(CMAKE_SYSTEM_NAME STREQUAL \"Darwin\")\n execute_process(COMMAND xcrun --sdk macosx --show-sdk-path\n OUTPUT_VARIABLE MACOS_SDK_PATH\n OUTPUT_STRIP_TRAILING_WHITESPACE)\n set(CMAKE_OSX_SYSROOT \"${MACOS_SDK_PATH}\")\n message(STATUS \"macOS SDK 경로 설정: ${MACOS_SDK_PATH}\")\n\n # Clang이 compile_commands.json에 나타나도록 isysroot 플래그를 맨 앞에 추가\n list(PREPEND _DEFAULT_COMPILER_FLAGS \"-isysroot\" \"${CMAKE_OSX_SYSROOT}\")\n endif()\n\n if(NOT DEFINED COMPILER_FLAGS)\n if(CMAKE_CXX_COMPILER_ID STREQUAL \"MSVC\")\n set(local_compiler_flags ${COMPILER_FLAGS_FOR_MSVC})\n else()\n set(local_compiler_flags ${COMPILER_FLAGS_FOR_GCC})\n endif()\n\n list(APPEND local_compiler_flags ${_DEFAULT_COMPILER_FLAGS})\n set(COMPILER_FLAGS ${local_compiler_flags} PARENT_SCOPE)\n message(STATUS \"기본 컴파일러 플래그가 설정되었습니다: ${COMPILER_FLAGS}\")\n else()\n list(APPEND COMPILER_FLAGS ${_DEFAULT_COMPILER_FLAGS})\n set(COMPILER_FLAGS ${COMPILER_FLAGS} PARENT_SCOPE)\n message(STATUS \"기존 COMPILER_FLAGS에 기본 플래그를 추가했습니다.\")\n endif()\n\n # --- 함수 끝: configure_default_compiler_flags\nendfunction()\n```\n\n---\n\n### 단계 3: Makefile 상세 출력 제어 모듈 (`configure_makefile_verbosity.cmake`)\n\n#### 1. `configure_makefile_verbosity.cmake` 모듈 생성\n\n이 액션은 개발자 경험을 향상시키는 유틸리티를 생성합니다. 이 함수는 Release가 아닌 빌드에 대해 `CMAKE_VERBOSE_MAKEFILE`을 자동으로 활성화하여 디버깅에 필수적인 상세한 컴파일러 명령어 출력을 제공합니다. `Release` 빌드의 경우, 더 깨끗하고 간결한 빌드 로그를 제공하기 위해 비활성화됩니다. 이 간단한 자동화는 수동 설정 단계를 제거하고 개발자의 현재 컨텍스트에 맞게 빌드 출력을 조정합니다.\n\n**파일**: `cmake/project/configure_makefile_verbosity.cmake`\n\n```cmake\n# 설명:\n# CMAKE_BUILD_TYPE에 따라 CMAKE_VERBOSE_MAKEFILE 옵션을 설정합니다.\n# Release가 아닌 빌드에서는 상세 출력을 ON으로, Release 빌드에서는 OFF로 설정합니다.\nfunction(configure_makefile_verbosity)\n # --- 함수 시작: configure_makefile_verbosity\n if(CMAKE_BUILD_TYPE STREQUAL \"Release\")\n set(CMAKE_VERBOSE_MAKEFILE OFF PARENT_SCOPE)\n message(STATUS \"Makefile 상세 출력: OFF (Release 빌드)\")\n else()\n set(CMAKE_VERBOSE_MAKEFILE ON PARENT_SCOPE)\n message(STATUS \"Makefile 상세 출력: ON (Debug 또는 기타 빌드 유형)\")\n endif()\n\n # --- 함수 끝: configure_makefile_verbosity\nendfunction()\n```\n\n---\n\n### 단계 4: 프로젝트 요약 출력 모듈 (`print_project_summary.cmake`)\n\n#### 1. `print_project_summary.cmake` 모듈 생성\n\n이 액션은 CMake 실행 시 개발자에게 명확하고 즉각적인 피드백을 제공하는 함수를 생성합니다. 시스템 정보, 컴파일러 설정, 그리고 단계 1에서 정의된 프로젝트 경로를 포함한 모든 중요한 설정 정보의 형식화된 요약을 출력합니다. 이는 빌드 환경이 예상대로 설정되었는지 확인하고, 캐시 파일을 검사할 필요 없이 경로, 컴파일러 플래그 또는 빌드 유형과 관련된 문제를 진단하는 데 매우 유용합니다.\n\n**파일**: `cmake/project/print_project_summary.cmake`\n\n```cmake\n# 설명:\n# 프로젝트 설정에 대한 포괄적인 요약을 출력합니다.\n#\n# 인수:\n# project_name_prefix (string): 경로 변수에 사용된 프로젝트 이름 접두사.\nfunction(print_project_summary project_name_prefix)\n # --- 함수 시작: print_project_summary\n if(NOT project_name_prefix)\n message(FATAL_ERROR \"print_project_summary: project_name_prefix 인수가 필요합니다.\")\n return()\n endif()\n\n message(STATUS \"-----------------------------------------------------------------------------\")\n message(STATUS \"${PROJECT_NAME}에 대한 설정 요약\")\n\n message(STATUS \"\\n시스템 설정\")\n message(STATUS \" 아키텍처: ${CMAKE_SYSTEM_PROCESSOR}\")\n message(STATUS \" 이름: ${CMAKE_SYSTEM_NAME}\")\n message(STATUS \" 버전: ${CMAKE_SYSTEM_VERSION}\")\n\n message(STATUS \"\\n프로젝트 설정\")\n message(STATUS \" 이름: ${PROJECT_NAME}\")\n message(STATUS \" 버전: ${PROJECT_VERSION}\")\n message(STATUS \" 설명: ${PROJECT_DESCRIPTION}\")\n message(STATUS \" 홈페이지 URL: ${PROJECT_HOMEPAGE_URL}\")\n\n message(STATUS \"\\nC++ 컴파일러 설정\")\n message(STATUS \" C++ 컴파일러 ID: ${CMAKE_CXX_COMPILER_ID}\")\n message(STATUS \" C++ 컴파일러 버전: ${CMAKE_CXX_COMPILER_VERSION}\")\n message(STATUS \" C++ 컴파일러 경로: ${CMAKE_CXX_COMPILER}\")\n message(STATUS \" C++ 빌드 유형: ${CMAKE_BUILD_TYPE}\")\n message(STATUS \" C++ 컴파일러 기능: ${COMPILER_FEATURES}\")\n message(STATUS \" C++ 컴파일러 플래그: ${COMPILER_FLAGS}\")\n\n message(STATUS \"\\n프로젝트 경로 (접두사: ${project_name_prefix})\")\n message(STATUS \" 루트: ${${project_name_prefix}_ROOT_PATH}\")\n message(STATUS \" 소스: ${${project_name_prefix}_SOURCE_PATH}\")\n message(STATUS \" 인클루드: ${${project_name_prefix}_INCLUDE_PATH}\")\n message(STATUS \" 빌드: ${${project_name_prefix}_BUILD_PATH}\")\n message(STATUS \" 내부 의존성: ${${project_name_prefix}_INTERNALS_PATH}\")\n message(STATUS \" 외부 의존성: ${${project_name_prefix}_EXTERNALS_PATH}\")\n message(STATUS \" 실행 파일: ${${project_name_prefix}_EXECUTABLES_PATH}\")\n message(STATUS \" CMake 모듈: ${${project_name_prefix}_CMAKE_MODULE_PATH}\")\n\n message(STATUS \"\\n-----------------------------------------------------------------------------\")\n\n # --- 함수 끝: print_project_summary\nendfunction()\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n이러한 기본 모듈들의 올바른 구현을 검증하려면, 프로젝트 루트에 임시 `CMakeLists.txt`를 생성하여 이들을 호출한 다음 CMake를 실행합니다.\n\n1. **임시 `CMakeLists.txt` 파일 생성**: 프로젝트의 루트 디렉터리에 다음 내용으로 임시 파일을 생성합니다. 이 스크립트는 상위 레벨 모듈이 새 함수를 어떻게 사용할지 시뮬레이션합니다.\n\n ```cmake\n cmake_minimum_required(VERSION 3.15)\n\n project(VerificationTest VERSION 1.0 DESCRIPTION \"기본 모듈 테스트용 스크립트\" LANGUAGES CXX)\n\n # 새 모듈 포함\n list(APPEND CMAKE_MODULE_PATH \"${CMAKE_CURRENT_SOURCE_DIR}/cmake/project\")\n include(initialize_project_paths)\n include(configure_default_compiler_flags)\n include(configure_makefile_verbosity)\n include(print_project_summary)\n\n # 이 모듈들이 예상하는 변수 정의\n set(PROJECT_NAME_PREFIX \"READABLE_CODE_CPP_PROJECT_TEMPLATE\")\n set(COMPILER_FLAGS_FOR_GCC \"-Wall;-Wextra;-Wpedantic\")\n\n # 함수 호출\n initialize_project_paths(${PROJECT_NAME_PREFIX})\n configure_default_compiler_flags()\n configure_makefile_verbosity()\n print_project_summary(${PROJECT_NAME_PREFIX})\n ```\n\n2. **CMake 실행**: 빌드 디렉터리에서 CMake를 실행합니다.\n\n ```bash\n # 빌드 디렉터리 생성 및 이동\n mkdir -p build && cd build\n \n # 임시 CMakeLists.txt가 있는 부모 디렉터리를 가리키며 cmake 실행\n cmake -DCMAKE_BUILD_TYPE=Debug ..\n ```\n\n3. **정리**: 프로젝트 루트에서 임시 `CMakeLists.txt` 파일을 제거합니다.\n\n### 4.2. 예상 결과\n\n`cmake ..` 명령어의 콘솔 출력은 각 함수의 상태 메시지를 표시하고, 최종적으로 상세한 설정 요약으로 마무리되어야 합니다. 출력은 경로가 초기화되었고, 컴파일러 플래그가 설정되었으며, 상세 출력이 \"Debug\"용으로 구성되었고, 최종 요약 테이블이 올바르게 출력되었음을 확인해야 합니다.\n\n```\n-- CXX 컴파일러 식별: AppleClang 15.0.0.15000100\n-- CXX 컴파일러 ABI 정보 감지 중\n...\n-- macOS SDK 경로 설정: /Library/Developer/CommandLineTools/SDKs/MacOSX14.2.sdk\n-- 프로젝트 경로가 다음 접두사로 초기화되었습니다: READABLE_CODE_CPP_PROJECT_TEMPLATE\n-- 기본 컴파일러 플래그가 설정되었습니다: -isysroot;/Library/Developer/CommandLineTools/SDKs/MacOSX14.2.sdk;-Wall;-Wextra;-Wpedantic\n-- Makefile 상세 출력: ON (Debug 또는 기타 빌드 유형)\n-- -----------------------------------------------------------------------------\n-- VerificationTest에 대한 설정 요약\n--\n-- 시스템 설정\n-- 아키텍처: arm64\n-- 이름: Darwin\n-- 버전: 23.2.0\n--\n-- 프로젝트 설정\n-- 이름: VerificationTest\n-- 버전: 1.0\n...\n--\n-- C++ 컴파일러 설정\n-- C++ 컴파일러 ID: AppleClang\n...\n-- C++ 빌드 유형: Debug\n-- C++ 컴파일러 플래그: -isysroot;/Library/Developer/CommandLineTools/SDKs/MacOSX14.2.sdk;-Wall;-Wextra;-Wpedantic\n--\n-- 프로젝트 경로 (접두사: READABLE_CODE_CPP_PROJECT_TEMPLATE)\n-- 루트: /path/to/readable-code-cpp-project-template\n-- 소스: /path/to/readable-code-cpp-project-template/source\n-- 인클루드: /path/to/readable-code-cpp-project-template/include\n...\n--\n-- -----------------------------------------------------------------------------\n-- 설정 완료 (0.2초)\n-- 생성 완료 (0.0초)\n-- 빌드 파일이 다음 위치에 기록되었습니다: /path/to/readable-code-cpp-project-template/build\n```\n","경로, 플래그, 빌드 설정 초기화를 위한 `cmake/project/` 내의 `.cmake` 파일 세트.",[1228,1230,1232,1234],{"_24":1229,"_83":39,"_84":192,"_85":61},"경로 초기화 모듈 (`initialize_project_paths.cmake`).",{"_24":1231,"_83":39,"_84":192,"_85":88},"기본 컴파일러 플래그 구성 모듈 (`configure_default_compiler_flags.cmake`).",{"_24":1233,"_83":39,"_84":192,"_85":91},"Makefile 상세 정보 표시 제어 모듈 (`configure_makefile_verbosity.cmake`).",{"_24":1235,"_83":39,"_84":192,"_85":94},"프로젝트 요약 출력 모듈 (`print_project_summary.cmake`).","전역 프로젝트 환경 설정을 담당하는 CMake 모듈.",{"_22":1238,"_24":1239,"_75":1240,"_77":1241,"_79":1242,"_51":1251,"_42":99},"task-1750998940010","타겟 속성 헬퍼 모듈","# 작업: 대상 속성 헬퍼 모듈\n\n> **에픽**: 기반 CMake 유틸리티 및 모듈\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 빌드 대상에 표준 속성을 적용하기 위한 재사용 가능한 CMake 함수.\n- **근거**: 모듈식 CMake 빌드 시스템의 기반 계층을 구축하기 위함입니다. 이러한 헬퍼 함수들은 CMake 대상 구성의 반복적이고 오류가 발생하기 쉬운 세부 사항(예: 컴파일러 플래그 설정, 라이브러리 연결)을 추상화합니다. 이는 상위 수준 스크립트의 일관성, 가독성 및 유지보수성을 증진하며, 확장 가능하고 읽기 쉬운 CMake 아키텍처라는 프로젝트 목표를 직접적으로 지원합니다. 이 로직을 중앙 집중화함으로써 모든 프로젝트 대상이 동일한 빌드 표준을 준수하도록 보장합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 컴파일 속성 구성 및 종속성 연결을 위한 `cmake/library/` 디렉토리 내의 `.cmake` 파일 세트.\n- **사양**:\n - `set_target_compile_properties(target_name)`: 주어진 대상에 프로젝트 전반의 컴파일러 기능, 컴파일러 옵션, 링커 옵션 및 표준 포함 디렉토리 규칙을 적용하는 함수.\n - `add_target_dependencies(target_name DEPENDENCIES ...)`: `PRIVATE` 연결을 사용하여 지정된 대상에 종속 대상 목록을 연결하는 함수.\n - `add_external_package(REPOSITORY_URL REPOSITORY_TAG ...)`: `FetchContent` 모듈의 상용구 코드를 캡슐화하여 외부 Git 기반 종속성을 선언하고 사용 가능하게 만드는 함수.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── cmake/\n# └── library/\n# ├── add_external_package.cmake <-- 신규\n# ├── add_target_dependencies.cmake <-- 신규\n# └── set_target_compile_properties.cmake <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 헬퍼 함수의 빌드 타임 사용법을 보여줍니다. 상위 수준 인터페이스 함수(예: `configure_library`)는 이러한 하위 수준 헬퍼를 호출하여 완전한 빌드 대상을 구성합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"상위 수준 인터페이스 (예: cmake/interface/configure_library.cmake)\"\n A[\"configure_library 호출\"]\n end\n\n subgraph \"대상 속성 헬퍼 (cmake/library/)\"\n B[\"set_target_compile_properties()\"]\n C[\"add_target_dependencies()\"]\n end\n\n subgraph \"CMake 빌드 프로세스\"\n D[\"my_library 대상 정의\"]\n end\n \n A --> D\n A --> B\n A --> C\n \n B --> E{\"빌드 대상: my_library\"}\n C --> E\n D --> E\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] 표준 컴파일 기능, 옵션 및 플래그를 설정하는 모듈 (`set_target_compile_properties.cmake`).\n- [ ] 종속성을 대상에 연결하는 모듈 (`add_target_dependencies.cmake`).\n- [ ] `FetchContent`를 위한 외부 패키지 헬퍼 (`add_external_package.cmake`).\n- [ ] 완전하고 문서화된 대상 헬퍼 모듈.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층적 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **모듈식 CMake 빌드 시스템**: 이 작업은 이 구성 요소의 가장 낮은 기반 계층을 직접 구현합니다. 이러한 유틸리티 함수는 모든 상위 수준 선언적 인터페이스 함수(에픽 3)를 구성하는 빌딩 블록이 됩니다.\n - **종속성 관리 시스템**: `add_external_package.cmake` 헬퍼는 종속성 관리 시스템의 핵심 유틸리티로, `FetchContent`를 통해 외부 라이브러리를 통합하기 위한 표준화되고 단순화된 인터페이스를 제공합니다.\n - **C++ 예제 라이브러리 및 테스트 스위트**: 이 구성 요소들은 헬퍼 함수의 주요 소비자가 될 것입니다. 각각의 `CMakeLists.txt` 파일은 상위 수준 인터페이스를 사용하여 라이브러리 및 테스트 실행 파일 대상을 올바르게 구성하기 위해 이러한 헬퍼를 호출합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `cmake/library/set_target_compile_properties.cmake`\n- `cmake/library/add_target_dependencies.cmake`\n- `cmake/library/add_external_package.cmake`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 표준 컴파일 기능, 옵션 및 플래그를 설정하는 모듈 (`set_target_compile_properties.cmake`)\n\n#### 1. 함수 생성 및 인자 검증\n\n이 작업은 `set_target_compile_properties` 함수를 만들고 필수적인 문서화와 인자 검증을 포함합니다. 문서는 프로젝트 표준에 따라 함수의 목적과 인자를 설명합니다. `target_name`이 제공되었는지 검증하여 암호 같은 다운스트림 CMake 오류를 방지합니다.\n\n**파일**: `cmake/library/set_target_compile_properties.cmake`\n\n```cmake\n# 설명:\n# 주어진 대상에 대한 공통 컴파일 및 링크 관련 속성을 설정합니다.\n#\n# 인자:\n# target_name (문자열): 속성을 설정할 대상의 이름입니다.\nfunction(set_target_compile_properties target_name)\n # --- 함수 시작: set_target_compile_properties\n if(NOT target_name)\n message(FATAL_ERROR \"set_target_compile_properties: target_name 인자가 필요합니다.\")\n return()\n endif()\n\n # ... 추가될 로직 ...\n\n # --- 함수 끝: set_target_compile_properties\nendfunction()\n```\n\n#### 2. 대상 포함 디렉토리 로직 추가\n\n이 작업은 `public` 인터페이스 디렉토리를 자동으로 포함하는 로직을 추가합니다. 관례에 따라 라이브러리의 공용 헤더는 `include` 하위 디렉토리에 위치합니다. 이 코드는 해당 디렉토리의 존재 여부를 확인하고 대상의 `PUBLIC` 포함 디렉토리에 추가하여, 이 대상을 사용하는 모든 소비자가 헤더를 사용할 수 있게 합니다.\n\n**파일**: `cmake/library/set_target_compile_properties.cmake`\n\n```cmake\n # ... 인자 검증 후 ...\n\n # 로컬 'include' 폴더가 존재하면 포함 디렉토리를 추가합니다.\n if(EXISTS \"${CMAKE_CURRENT_SOURCE_DIR}/include\")\n message(STATUS \"[${target_name}] 포함 디렉토리 추가: ${CMAKE_CURRENT_SOURCE_DIR}/include\")\n target_include_directories(${target_name}\n PUBLIC\n \"${CMAKE_CURRENT_SOURCE_DIR}/include\"\n )\n endif()\n\n # ... 추가될 로직 ...\n```\n\n#### 3. 프로젝트 전반의 컴파일 속성 적용\n\n이 작업은 전역으로 정의된 컴파일러 설정을 대상에 적용합니다. `target_compile_features`, `target_compile_options`, `target_link_options`를 사용하여 C++20과 같은 프로젝트 표준을 강제하고 일관된 경고 플래그를 적용합니다. 이를 통해 모든 코드가 동일한 규칙으로 빌드되도록 보장합니다. 테스트 관련 플래그(`--coverage`)는 조건부로 추가됩니다.\n\n**파일**: `cmake/library/set_target_compile_properties.cmake`\n\n```cmake\n # ... 포함 디렉토리 로직 후 ...\n\n # 필수 컴파일러 기능 설정 (예: C++ 표준).\n if(COMPILER_FEATURES)\n message(STATUS \"[${target_name}] 컴파일러 기능 설정: ${COMPILER_FEATURES}\")\n target_compile_features(${target_name}\n PRIVATE\n ${COMPILER_FEATURES}\n )\n else()\n message(WARNING \"[${target_name}] COMPILER_FEATURES가 설정되지 않았습니다. 건너뜁니다.\")\n endif()\n\n # 테스트가 활성화된 경우 테스트 플래그를 설정합니다.\n if(ENABLE_TESTING)\n set(TEST_FLAGS \"--coverage\")\n endif()\n\n # 컴파일러 옵션을 설정합니다.\n message(STATUS \"[${target_name}] 컴파일러 옵션 설정: ${COMPILER_FLAGS} ${TEST_FLAGS}\")\n target_compile_options(${target_name}\n PRIVATE\n ${COMPILER_FLAGS}\n ${TEST_FLAGS}\n )\n\n # 링커 옵션을 설정합니다.\n message(STATUS \"[${target_name}] 링커 옵션 설정: ${LINKER_FLAGS} ${TEST_FLAGS}\")\n target_link_options(${target_name}\n PRIVATE\n ${LINKER_FLAGS}\n ${TEST_FLAGS}\n )\n\n # --- 함수 끝: set_target_compile_properties\nendfunction()\n```\n\n---\n\n### 단계 2: 종속성을 대상에 연결하는 모듈 (`add_target_dependencies.cmake`)\n\n#### 1. 함수 생성 및 키워드 인자 파싱\n\n이 작업은 `add_target_dependencies` 함수를 정의합니다. `cmake_parse_arguments`를 사용하여 연결할 라이브러리 목록을 전달하기 위한 깔끔한 키워드 기반 인터페이스(`DEPENDENCIES`)를 제공합니다. 이는 원시 인자 목록을 `target_link_libraries`에 직접 전달하는 것보다 가독성이 높고 오류 발생 가능성이 적습니다.\n\n**파일**: `cmake/library/add_target_dependencies.cmake`\n\n```cmake\n# 설명:\n# target_link_libraries를 사용하여 지정된 종속성을 주어진 대상에 추가합니다.\n# 이 함수는 여러 라이브러리나 대상을 private\n# 종속성으로 연결하는 것을 단순화합니다.\n#\n# 인자:\n# target_name (문자열, 필수): 종속성이 추가될 대상의 이름입니다.\n# DEPENDENCIES (리스트, 선택): 대상에 연결할 종속성 목록입니다.\nfunction(add_target_dependencies target_name)\n # --- 함수 시작: add_target_dependencies\n set(options \"\")\n set(one_value_args \"\")\n set(multi_value_args \"DEPENDENCIES\")\n\n cmake_parse_arguments(ARGUMENTS\n \"${options}\"\n \"${one_value_args}\"\n \"${multi_value_args}\"\n ${ARGN})\n \n # ... 연결 로직 추가 예정 ...\n\n # --- 함수 끝: add_target_dependencies\nendfunction()\n```\n\n#### 2. 종속성 연결 구현\n\n이 작업은 핵심 로직을 구현합니다. `DEPENDENCIES` 인자가 제공되었는지 확인하고, 그렇다면 `target_link_libraries`를 사용하여 연결합니다. 종속성은 `PRIVATE`으로 연결되는데, 이는 대상의 소비자에게 전파되어서는 안 되는 구현 세부 사항에 대한 표준 관행입니다.\n\n**파일**: `cmake/library/add_target_dependencies.cmake`\n\n```cmake\n # ... cmake_parse_arguments 후 ...\n\n if(ARGUMENTS_DEPENDENCIES)\n message(STATUS \"[${target_name}] 종속성 추가: ${ARGUMENTS_DEPENDENCIES}\")\n target_link_libraries(${target_name} PRIVATE ${ARGUMENTS_DEPENDENCIES})\n else()\n message(STATUS \"[${target_name}] add_target_dependencies에 제공된 종속성이 없습니다.\")\n endif()\n\n # --- 함수 끝: add_target_dependencies\nendfunction()\n```\n\n---\n\n### 단계 3: `FetchContent`를 위한 외부 패키지 헬퍼 (`add_external_package.cmake`)\n\n#### 1. 함수 정의 및 인자 파싱\n\n이 작업은 `FetchContent`를 래핑하는 `add_external_package` 함수를 만듭니다. 코드를 가져오는 데 필수적인 리포지토리 URL과 태그에 대한 인자를 파싱하고, 구성 단계에서 오류를 방지하기 위해 이들의 존재를 검증합니다.\n\n**파일**: `cmake/library/add_external_package.cmake`\n\n```cmake\n# 설명:\n# FetchContent를 사용하여 외부 패키지를 추가합니다. 이 함수는\n# 종속성을 선언하고, 해당 대상을 사용 가능하게 만들고,\n# 지정된 컴파일 옵션이나 정의를 적용하는 과정을 단순화합니다.\n#\n# 인자:\n# REPOSITORY_URL (문자열, 필수): 패키지의 Git 리포지토리 URL입니다.\n# REPOSITORY_TAG (문자열, 필수): Git 태그, 브랜치 또는 커밋 해시입니다.\n# LIBRARIES (리스트, 선택): 패키지에 의해 생성된 대상 이름 목록입니다.\n# COMPILE_OPTIONS (리스트, 선택): 대상에 적용할 컴파일 옵션 목록입니다.\n# COMPILE_DEFINITIONS (리스트, 선택): 적용할 컴파일 정의 목록입니다.\nfunction(add_external_package)\n # --- 함수 시작: add_external_package\n get_filename_component(package_name ${CMAKE_CURRENT_LIST_DIR} NAME)\n message(STATUS \"[${package_name}] 외부 패키지 구성 중...\")\n\n set(one_value_args REPOSITORY_URL REPOSITORY_TAG)\n set(multi_value_args LIBRARIES COMPILE_OPTIONS COMPILE_DEFINITIONS)\n cmake_parse_arguments(PACKAGE \"\" \"${one_value_args}\" \"${multi_value_args}\" ${ARGN})\n\n if(NOT PACKAGE_REPOSITORY_URL OR NOT PACKAGE_REPOSITORY_TAG)\n message(FATAL_ERROR \"[${package_name}] REPOSITORY_URL과 REPOSITORY_TAG를 제공해야 합니다.\")\n return()\n endif()\n\n # ... FetchContent 로직 추가 예정 ...\n\n # --- 함수 끝: add_external_package\nendfunction()\n```\n\n#### 2. 핵심 `FetchContent` 로직 구현\n\n이 작업은 표준 `FetchContent` 워크플로를 추가합니다. 먼저 모듈을 포함하고, Git 리포지토리 세부 정보와 함께 종속성을 선언한 다음, 마지막으로 `FetchContent_MakeAvailable`을 호출하여 코드를 다운로드하고 `CMakeLists.txt`를 처리하여 프로젝트에서 해당 대상을 사용할 수 있도록 합니다.\n\n**파일**: `cmake/library/add_external_package.cmake`\n\n```cmake\n # ... 인자 검증 후 ...\n\n include(FetchContent)\n\n FetchContent_Declare(\n ${package_name}\n GIT_REPOSITORY ${PACKAGE_REPOSITORY_URL}\n GIT_TAG ${PACKAGE_REPOSITORY_TAG}\n GIT_SHALLOW TRUE\n )\n\n FetchContent_MakeAvailable(${package_name})\n\n # ... 후속 구성 로직 추가 예정 ...\n```\n\n#### 3. 가져온 대상에 대한 후속 구성 로직 추가\n\n이 작업은 `FetchContent`에 의해 생성된 대상의 컴파일 설정을 수정하는 고급 기능을 추가합니다. 이는 프로젝트 표준을 따르지 않는 서드파티 코드에서 특정 경고를 비활성화하는 등 빌드 일관성을 유지하는 데 중요합니다. 이 로직은 별칭이 지정된 대상을 처리하여 설정이 올바르게 적용되도록 보장합니다.\n\n**파일**: `cmake/library/add_external_package.cmake`\n\n```cmake\n # ... FetchContent_MakeAvailable 후 ...\n\n if(PACKAGE_LIBRARIES)\n if(PACKAGE_COMPILE_OPTIONS OR PACKAGE_COMPILE_DEFINITIONS)\n message(STATUS \"[${package_name}] 대상에 사용자 지정 컴파일 설정 적용 중: ${PACKAGE_LIBRARIES}\")\n\n foreach(target_name IN LISTS PACKAGE_LIBRARIES)\n if(NOT TARGET ${target_name})\n message(\n WARNING \"[${package_name}] '${target_name}' 대상을 찾을 수 없습니다. 컴파일 설정을 적용할 수 없습니다.\"\n )\n continue()\n endif()\n\n get_target_property(aliased_target ${target_name} ALIASED_TARGET)\n\n if(aliased_target)\n set(actual_target ${aliased_target})\n else()\n set(actual_target ${target_name})\n endif()\n\n if(PACKAGE_COMPILE_OPTIONS)\n target_compile_options(${actual_target} PRIVATE ${PACKAGE_COMPILE_OPTIONS} --coverage)\n endif()\n\n if(PACKAGE_COMPILE_DEFINITIONS)\n target_compile_definitions(${actual_target} PRIVATE ${PACKAGE_COMPILE_DEFINITIONS})\n endif()\n endforeach()\n endif()\n elseif(PACKAGE_COMPILE_OPTIONS OR PACKAGE_COMPILE_DEFINITIONS)\n message(\n WARNING\n \"[${package_name}] COMPILE_OPTIONS 또는 COMPILE_DEFINITIONS가 제공되었지만, 이를 적용할 LIBRARIES가 지정되지 않았습니다.\"\n )\n endif()\n\n message(STATUS \"[${package_name}] 구성 완료. ${package_name}의 대상들을 이제 사용할 수 있습니다.\")\n\n # --- 함수 끝: add_external_package\nendfunction()\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n구현을 검증하기 위해, 새 헬퍼 함수를 포함하고 실행하는 임시 테스트 `CMakeLists.txt`가 생성될 것입니다. 이를 통해 문법적으로 올바르고 빌드 시스템에 통합될 수 있는지 확인합니다.\n\n1. **임시 검증 스크립트 생성.** 프로젝트 루트에 다음 내용을 포함하는 `verification.cmake`라는 이름의 파일을 생성합니다:\n\n ```cmake\n cmake_minimum_required(VERSION 3.15)\n project(VerificationTest)\n\n # 새 헬퍼 모듈 포함\n list(APPEND CMAKE_MODULE_PATH \"${CMAKE_CURRENT_SOURCE_DIR}/cmake/library\")\n include(set_target_compile_properties)\n include(add_target_dependencies)\n\n # 헬퍼가 의존하는 더미 전역 변수 설정\n set(COMPILER_FEATURES \"cxx_std_20\")\n set(COMPILER_FLAGS \"-Wall\")\n set(LINKER_FLAGS \"\")\n\n # 더미 대상 생성\n add_executable(dummy_target empty.cpp)\n\n # 헬퍼 함수 호출\n set_target_compile_properties(dummy_target)\n add_target_dependencies(dummy_target DEPENDENCIES \"some_fake_lib\") # 이것은 경고를 발생시키지만 실패해서는 안 됩니다\n ```\n\n2. **자리 표시자 소스 파일 생성.** 프로젝트 루트에 `empty.cpp`라는 이름의 빈 파일을 생성합니다.\n\n3. **CMake 실행.** 빌드 디렉토리(예: `build/`)에서 프로젝트 루트를 가리키며 CMake를 실행합니다.\n\n ```bash\n # 프로젝트 루트에서\n mkdir -p build && cd build\n cmake .. -C ../verification.cmake\n ```\n\n### 4.2. 예상 결과\n\nCMake 구성 프로세스는 `FATAL_ERROR` 메시지 없이 완료되어야 합니다. 출력에는 헬퍼 함수가 실행되었음을 확인하는 상태 메시지가 포함되어야 합니다.\n\n```\n-- [dummy_target] 포함 디렉토리 추가: /path/to/project/\n-- [dummy_target] 컴파일러 기능 설정: cxx_std_20\n-- [dummy_target] 컴파일러 옵션 설정: -Wall \n-- [dummy_target] 링커 옵션 설정: \n-- [dummy_target] 종속성 추가: some_fake_lib\n-- 구성 완료\n-- 생성 완료\n-- 빌드 파일이 다음 위치에 기록되었습니다: /path/to/project/build\n```\n","컴파일 속성 구성 및 의존성 연결을 위한 `cmake/library/` 내의 `.cmake` 파일 세트.",[1243,1245,1247,1249],{"_24":1244,"_83":39,"_84":212,"_85":61},"표준 컴파일 기능, 옵션, 플래그를 설정하는 모듈 (`set_target_compile_properties.cmake`).",{"_24":1246,"_83":39,"_84":212,"_85":88},"타겟에 의존성을 연결하는 모듈 (`add_target_dependencies.cmake`).",{"_24":1248,"_83":39,"_84":212,"_85":91},"FetchContent를 위한 외부 패키지 헬퍼 (`add_external_package.cmake`).",{"_24":1250,"_83":39,"_84":212,"_85":94},"완전하고 문서화된 타겟 헬퍼 모듈.","빌드 타겟에 표준 속성을 적용하기 위한 재사용 가능한 CMake 함수.",{"_22":1253,"_24":1254,"_75":1255,"_77":1256,"_79":1257,"_51":1266,"_42":99},"task-1750998989374","고수준 프로젝트 구성 인터페이스","# 작업: 고수준 프로젝트 설정 인터페이스\n\n> **에픽**: 고수준 CMake 인터페이스 모듈\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 전체 프로젝트 수준 설정을 총괄하는 단일 함수.\n- **근거**: 초기 프로젝트 설정의 상용구 코드와 복잡성을 단일 선언적 함수로 추상화하기 위함입니다. 이는 최상위 `CMakeLists.txt`에 깨끗하고 고수준의 API를 제공하여 가독성, 유지보수성, 사용 편의성을 향상시킴으로써 '계층형 CMake 빌드 시스템'이라는 프로젝트 아키텍처 목표와 일치합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 경로, 플래그를 초기화하고 하위 프로젝트를 자동 탐지하는 `configure_project.cmake` 모듈.\n- **사양**:\n - `함수 시그니처`: `function(configure_project project_name_arg)`\n - `파일`: `cmake/interface/configure_project.cmake`\n - `부모 스코프에 설정될 변수`: `UPPERCASE_PROJECT_NAME`, `COMPILER_FLAGS`\n- **결과 파일 구조**\n\n```bash\n# ./\n# ├── cmake/\n# │ └── interface/\n# │ └── configure_project.cmake <-- 신규\n# ...\n```\n\n- **프로세스 흐름도**\n이 다이어그램은 최상위 빌드 스크립트가 `configure_project` 함수를 호출할 때의 제어 흐름을 보여줍니다. 이 함수는 오케스트레이터 역할을 하여, 특정 설정 작업을 수행하고 빌드 환경을 준비하기 위해 기반 모듈들을 호출합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n TopLevelCMake[\"최상위 CMakeLists.txt\"] -- \"configure_project() 호출\" --> ConfigureProject[\"configure_project()\"];\n \n subgraph \"configure_project.cmake\"\n ConfigureProject --> IncludeModules[\"1\\. 기반 모듈 포함\"];\n IncludeModules --> ConfigureFlags[\"2\\. 컴파일러 플래그 설정\"];\n ConfigureFlags --> InitializePaths[\"3\\. 프로젝트 경로 초기화\"];\n InitializePaths --> PrintSummary[\"4\\. 설정 요약 출력\"];\n PrintSummary --> AddSubdirs[\"5\\. 종속성 및 실행 파일 디렉터리 추가\"];\n end\n \n AddSubdirs --> BuildEnvironment[\"빌드 환경 준비 완료\"];\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 고수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 3장에 있습니다.\n\n- [ ] 기반 헬퍼 모듈 포함.\n- [ ] 프로젝트 경로 및 컴파일러 플래그 초기화 로직.\n- [ ] 프로젝트 요약 출력 호출.\n- [ ] 종속성 및 실행 파일 하위 디렉터리의 자동 탐지 및 포함.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층형 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **모듈식 CMake 빌드 시스템**: 이 작업은 빌드 시스템의 핵심입니다. 이는 기반 유틸리티 계층(`cmake/project/`, `cmake/common/`) 위에 위치하는 고수준 인터페이스 계층(`cmake/interface/`)을 생성합니다. 그 목적은 이러한 저수준 모듈들을 총괄하는 것입니다.\n - **종속성 관리 시스템**: 이 함수는 `dependencies/` 하위 디렉터리를 자동으로 포함하여 종속성 통합을 용이하게 하며, CMake가 FetchContent 및 Git Submodule 종속성에 대한 빌드 스크립트를 처리할 수 있도록 합니다.\n - **C++ 예제 라이브러리 / 실행 파일**: 직접 수정되지는 않지만, 이 함수 로직에 의해 이들 구성 요소가 탐지 및 설정되며, 이 로직은 `executables/` 디렉터리를 빌드에 추가합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `cmake/interface/configure_project.cmake`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 기반 헬퍼 모듈 포함\n\n#### 1. 코어 및 프로젝트 유틸리티 모듈 포함\n\n이 액션은 `configure_project` 함수가 필요한 모든 저수준 헬퍼 함수에 접근할 수 있도록 보장합니다. `cmake/common/` 및 `cmake/project/`의 모듈을 포함함으로써, 경로 초기화, 컴파일러 플래그 설정, 요약 출력, 하위 디렉터리 처리를 위한 함수들을 가져옵니다. 이들은 이 고수준 인터페이스의 구성 요소입니다.\n\n**파일**: `cmake/interface/configure_project.cmake`\n\n```cmake\n# 설명:\n# 다양한 설정 함수를 호출하여 핵심 프로젝트 설정을 통합합니다.\n# 이 함수는 경로를 초기화하고, 컴파일러 플래그를 설정하며,\n# 프로젝트 요약을 출력합니다. 루트 CMakeLists.txt에서 한 번 호출되도록\n# 의도되었습니다.\n#\n# 인자:\n# project_name_arg (string): 프로젝트의 이름, 일반적으로 ${PROJECT_NAME}입니다.\nfunction(configure_project project_name_arg)\n # --- 함수 시작: configure_project\n # --- 종속 코어 함수 모듈 포함\n include(${CMAKE_SOURCE_DIR}/cmake/common/convert_to_uppercase_with_underscores.cmake)\n include(${CMAKE_SOURCE_DIR}/cmake/project/configure_default_compiler_flags.cmake)\n include(${CMAKE_SOURCE_DIR}/cmake/project/configure_makefile_verbosity.cmake)\n include(${CMAKE_SOURCE_DIR}/cmake/project/initialize_project_paths.cmake)\n include(${CMAKE_SOURCE_DIR}/cmake/project/print_project_summary.cmake)\n include(${CMAKE_SOURCE_DIR}/cmake/common/add_subdirectories.cmake)\n\n # ... 함수의 나머지 부분\nendfunction()\n```\n\n---\n\n### 단계 2: 프로젝트 경로 및 컴파일러 플래그 초기화 로직\n\n#### 1. 전역 컴파일러 및 Makefile 설정 구성\n\n이 액션은 가져온 함수들을 실행하여 프로젝트 전반의 빌드 설정을 확립합니다. `configure_default_compiler_flags`는 C++ 표준 및 경고 수준을 설정하고, `configure_makefile_verbosity`는 기본적으로 빌드 출력이 깨끗하고 읽기 쉽도록 보장합니다.\n\n**파일**: `cmake/interface/configure_project.cmake`\n\n```cmake\nfunction(configure_project project_name_arg)\n # ... include 구문\n\n # --- 프로젝트 설정 구성\n configure_default_compiler_flags()\n configure_makefile_verbosity()\n\n # ... 함수의 나머지 부분\nendfunction()\n```\n\n#### 2. 프로젝트별 변수 준비 및 전파\n\n이 액션은 빌드 전반에 걸쳐 사용될 핵심 변수들을 준비합니다. 변수 접두사 규칙으로 프로젝트 이름을 대문자 형식(예: `my-project` -> `MY_PROJECT`)으로 변환합니다. 그런 다음 `initialize_project_paths`를 호출하여 표준 디렉터리 변수(예: `MY_PROJECT_SOURCE_PATH`)를 정의합니다. 마지막으로, `PARENT_SCOPE`를 사용하여 이러한 중요 변수들을 주 `CMakeLists.txt` 및 후속 빌드 스크립트에서 사용할 수 있게 합니다.\n\n**파일**: `cmake/interface/configure_project.cmake`\n\n```cmake\nfunction(configure_project project_name_arg)\n # ... include 구문 및 초기 설정\n\n # --- 프로젝트 변수 준비\n convert_to_uppercase_with_underscores(${project_name_arg} local_uppercase_project_name)\n set(UPPERCASE_PROJECT_NAME ${local_uppercase_project_name} PARENT_SCOPE)\n initialize_project_paths(${local_uppercase_project_name})\n set(COMPILER_FLAGS ${COMPILER_FLAGS} PARENT_SCOPE)\n\n # ... 함수의 나머지 부분\nendfunction()\n```\n\n---\n\n### 단계 3: 프로젝트 요약 출력 호출\n\n#### 1. 프로젝트 설정 요약 표시\n\n이 액션은 `cmake` 설정 단계에서 개발자에게 즉각적인 피드백을 제공합니다. `print_project_summary`를 호출하여 탐지된 컴파일러, 빌드 유형, 주요 프로젝트 경로를 표시합니다. 이를 통해 생성된 빌드 파일을 검사할 필요 없이 프로젝트가 예상대로 설정되었는지 신속하게 확인할 수 있습니다.\n\n**파일**: `cmake/interface/configure_project.cmake`\n\n```cmake\nfunction(configure_project project_name_arg)\n # ... include 구문 및 설정\n\n # --- 설정 요약 출력\n print_project_summary(${local_uppercase_project_name})\n\n # ... 함수의 나머지 부분\nendfunction()\n```\n\n---\n\n### 단계 4: 종속성 및 실행 파일 하위 디렉터리의 자동 탐지 및 포함\n\n#### 1. 빌드에 종속성 및 실행 파일 하위 디렉터리 추가\n\n이는 함수 내의 마지막 액션입니다. `add_subdirectories` 헬퍼를 사용하여 표준 종속성(`externals`, `internals`) 및 실행 파일 디렉터리 내의 모든 `CMakeLists.txt` 파일을 자동으로 찾아 처리합니다. 이는 빌드 시스템을 모듈화하고 확장 가능하게 만듭니다. 새 종속성이나 실행 파일을 최상위 빌드 스크립트 수정 없이 올바른 디렉터리에 배치하는 것만으로 프로젝트에 추가할 수 있습니다.\n\n**파일**: `cmake/interface/configure_project.cmake`\n\n```cmake\nfunction(configure_project project_name_arg)\n # ... include 구문 및 설정\n\n # --- 하위 디렉터리 설정\n add_subdirectories(${${local_uppercase_project_name}_EXTERNALS_PATH})\n add_subdirectories(${${local_uppercase_project_name}_INTERNALS_PATH})\n add_subdirectories(${${local_uppercase_project_name}_EXECUTABLES_PATH})\n\n # --- 함수 종료: configure_project\nendfunction()\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n함수를 검증하려면, 최상위 `CMakeLists.txt`에서 호출해야 합니다. `cmake` 명령어의 출력은 내부 단계(요약 출력, 변수 설정)가 올바르게 실행되었음을 확인해 줄 것입니다.\n\n1. 프로젝트 루트에 다음 내용으로 최소한의 `CMakeLists.txt`를 생성합니다:\n\n ```cmake\n # ./CMakeLists.txt\n cmake_minimum_required(VERSION 3.15)\n project(verification-test LANGUAGES CXX)\n \n # 인터페이스 모듈 포함\n include(cmake/interface/configure_project.cmake)\n \n # 함수를 호출하여 프로젝트 설정\n configure_project(${PROJECT_NAME})\n ```\n\n2. `build` 디렉터리에서 CMake 설정 명령어를 실행합니다:\n\n ```bash\n mkdir build && cd build\n cmake ..\n ```\n\n### 4.2. 예상 결과\n\n- CMake 설정이 오류 없이 완료되어야 합니다.\n- 콘솔 출력에는 `configure_project`에 의해 호출되는 `print_project_summary` 함수가 출력하는 요약이 포함되어야 합니다. 출력은 다음과 유사할 것입니다:\n\n```\n-- ====================================================================================================\n-- 프로젝트 이름: VERIFICATION_TEST\n-- 프로젝트 버전:\n-- 프로젝트 설명:\n-- --------------------------------------------------------------------------------\n-- 빌드 타입: Debug\n-- C++ 컴파일러: /usr/bin/c++ (11.4.0)\n-- C++ 표준: 20\n-- --------------------------------------------------------------------------------\n-- 루트 경로: /path/to/your/project\n-- 소스 경로: /path/to/your/project/source\n-- 인클루드 경로: /path/to/your/project/include\n-- 실행 파일 경로: /path/to/your/project/executables\n-- ====================================================================================================\n-- 설정 완료\n-- 생성 완료\n-- 빌드 파일이 다음 경로에 작성되었습니다: /path/to/your/project/build\n```\n","경로, 플래그를 초기화하고 하위 프로젝트를 자동 검색하는 `configure_project.cmake` 모듈.",[1258,1260,1262,1264],{"_24":1259,"_83":39,"_84":230,"_85":61},"기반 헬퍼 모듈 포함.",{"_24":1261,"_83":39,"_84":230,"_85":88},"프로젝트 경로 및 컴파일러 플래그 초기화 로직.",{"_24":1263,"_83":39,"_84":230,"_85":91},"프로젝트 요약 출력을 위한 호출.",{"_24":1265,"_83":39,"_84":230,"_85":94},"의존성 및 실행 파일 하위 디렉토리의 자동 검색 및 포함.","전체 프로젝트 수준의 설정을 총괄하는 단일 함수.",{"_22":1268,"_24":1269,"_75":1270,"_77":1271,"_79":1272,"_51":1281,"_42":99},"task-1750999049381","라이브러리 및 실행 파일 구성 인터페이스","# 작업: 라이브러리 및 실행 파일 구성 인터페이스\n\n> **에픽**: 상위 수준 CMake 인터페이스 모듈\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 라이브러리 및 실행 파일 빌드 타겟을 정의하기 위한 선언적 함수.\n- **근거**: 이 작업은 프로젝트의 계층화된 CMake 아키텍처를 구축하는 데 핵심적인 역할을 합니다. 상위 수준의 선언적 함수(`configure_library`, `configure_executable`)를 생성함으로써, 표준 CMake 명령어의 내부 복잡성을 추상화합니다. 이 추상화는 프로젝트 전반의 `CMakeLists.txt` 파일에서 사용할 수 있는 깔끔하고 유지보수하기 쉬우며 가독성 좋은 API를 제공하여, 모듈화되고 확장 가능한 빌드 시스템이라는 핵심 목표를 직접적으로 지원합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: `CMakeLists.txt`에서 사용할 `configure_library.cmake` 및 `configure_executable.cmake` 모듈.\n- **명세**:\n - CMake 함수 `configure_library(NAME TYPE SOURCES DEPENDENCIES )`.\n - CMake 함수 `configure_executable(NAME SOURCES DEPENDENCIES )`.\n - 두 함수 모두 명확성을 위해 명명된 인수를 파싱해야 합니다.\n - 두 함수 모두 생성된 타겟에 프로젝트 전반의 표준 컴파일 속성(경고, C++ 표준)을 적용해야 합니다.\n - 두 함수 모두 지정된 모든 종속성을 생성된 타겟에 연결해야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── cmake/\n# └── interface/\n# ├── configure_executable.cmake <-- 수정됨\n# └── configure_library.cmake <-- 수정됨\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 빌드 프로세스 내에서 선언적 함수가 의도된 사용법을 보여줍니다. 프로젝트의 `CMakeLists.txt` 파일이 이러한 상위 수준 함수를 호출하면, 이 함수들은 CMake의 네이티브 API를 사용하여 빌드 타겟 생성을 조율합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n SubdirCMake[\"프로젝트의 CMakeLists.txt\"] -- \"configure_library(NAME my_lib ...) 호출\" --> ConfigureLibrary[\"cmake/interface/configure_library.cmake\"];\n ConfigureLibrary -- \"네이티브 명령어 호출\" --> CMakeAPI_Lib[\"CMake API (add_library, target_link_libraries 등)\"];\n CMakeAPI_Lib --> BuildSystem[\"빌드 시스템에 'my_lib' 타겟 생성\"];\n\n SubdirCMake -- \"configure_executable(NAME my_app ...) 호출\" --> ConfigureExecutable[\"cmake/interface/configure_executable.cmake\"];\n ConfigureExecutable -- \"네이티브 명령어 호출\" --> CMakeAPI_Exec[\"CMake API (add_executable, target_link_libraries 등)\"];\n CMakeAPI_Exec --> BuildSystem[\"빌드 시스템에 'my_app' 타겟 생성\"];\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] `STATIC`, `SHARED`, `INTERFACE` 타입을 처리하는 `configure_library` 함수.\n- [ ] 고유한 타겟 이름을 생성하는 `configure_executable` 함수.\n- [ ] 두 함수에 표준 컴파일 속성을 적용하는 로직.\n- [ ] 두 함수에 지정된 종속성을 연결하는 로직.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층화된 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **모듈식 CMake 빌드 시스템**: 이 작업은 이 구성 요소의 상위 수준 인터페이스 계층을 직접 구현합니다. 새로운 함수들은 빌드 시스템의 다른 부분들이 타겟을 정의하기 위해 사용할 기본 API가 됩니다.\n - **C++ 예제 라이브러리**: 이 구성 요소는 `configure_library` 함수의 첫 번째 사용자가 됩니다. 이 새로운 인터페이스를 사용함으로써 `CMakeLists.txt`가 단순화될 것입니다.\n - **테스트 스위트**: 테스트 실행 파일은 `configure_executable` 함수를 사용하여 정의될 것이며, 이는 주 애플리케이션 타겟이 아닌 경우에 대한 사용법을 보여줍니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `cmake/interface/configure_library.cmake`\n- `cmake/interface/configure_executable.cmake`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부적인 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을', '왜'를 포함), 그리고 정확한 코드 구현을 제공할 것입니다.\n\n---\n\n### 단계 1: `STATIC`, `SHARED`, `INTERFACE` 타입을 처리하는 `configure_library` 함수\n\n#### 1. 함수 시그니처 및 인수 파싱 업데이트\n\n이 액션은 `configure_library` 함수가 필수 `NAME` 인수를 받도록 수정합니다. 타겟 이름을 `${PROJECT_NAME}`으로 하드코딩하는 것은 확장성이 떨어집니다. 선언적 함수는 호출자가 구성할 라이브러리의 이름을 지정할 수 있도록 해야 합니다. 기존 인수들과 함께 이 새로운 인수를 처리하기 위해 `cmake_parse_arguments`를 사용할 것입니다.\n\n**파일**: `cmake/interface/configure_library.cmake`\n\n```cmake\n...\n# 인수:\n# NAME (문자열, 필수): 라이브러리 타겟의 이름.\n# TYPE (문자열, 선택): 라이브러리 타입 (STATIC, SHARED, 또는 INTERFACE). 기본값은 STATIC.\n# SOURCES (리스트, 선택): 소스 파일. INTERFACE 타입에는 필요하지 않음.\n# DEPENDENCIES (리스트, 선택): 라이브러리 종속성.\nfunction(configure_library)\n # --- 함수 시작: configure_library\n set(options)\n set(oneValueArgs NAME TYPE)\n set(multiValueArgs SOURCES DEPENDENCIES)\n cmake_parse_arguments(ARG \"${options}\" \"${oneValueArgs}\" \"${multiValueArgs}\" ${ARGN})\n\n if(NOT ARG_NAME)\n message(FATAL_ERROR \"configure_library() 함수는 'NAME' 인수가 필요합니다.\")\n endif()\n...\n```\n\n#### 2. 타겟 생성 로직 구현\n\n이 액션은 핵심 `add_library` 호출을 업데이트하여 새로운 `ARG_NAME` 변수를 사용하도록 합니다. 또한 `STATIC` 및 `SHARED` 라이브러리에 대해서는 `SOURCES`가 제공되는지 확인하고, `INTERFACE` 라이브러리는 소스 없이 올바르게 생성되도록 유효성 검사를 포함합니다. 이는 함수의 올바른 사용을 강제합니다.\n\n**파일**: `cmake/interface/configure_library.cmake`\n\n```cmake\n...\n if(NOT ARG_TYPE)\n set(ARG_TYPE STATIC)\n endif()\n\n string(TOUPPER \"${ARG_TYPE}\" ARG_TYPE_UPPER)\n\n set(VALID_LIBRARY_TYPES STATIC SHARED INTERFACE)\n if(NOT ARG_TYPE_UPPER IN_LIST VALID_LIBRARY_TYPES)\n message(FATAL_ERROR \"잘못된 라이브러리 TYPE '${ARG_TYPE}'. STATIC, SHARED, INTERFACE 중 하나여야 합니다.\")\n endif()\n\n message(STATUS \"-- 라이브러리 정의 중: ${ARG_NAME}\")\n\n if(ARG_SOURCES)\n add_library(${ARG_NAME} ${ARG_TYPE} ${ARG_SOURCES})\n else()\n if(ARG_TYPE_UPPER STREQUAL \"INTERFACE\")\n add_library(${ARG_NAME} INTERFACE)\n else()\n message(FATAL_ERROR \"라이브러리 타입 '${ARG_TYPE}'는 SOURCES가 필요하지만, 타겟 '${ARG_NAME}'에 제공되지 않았습니다.\")\n endif()\n endif()\n...\n```\n\n---\n\n### 단계 2: 고유한 타겟 이름을 생성하는 `configure_executable` 함수\n\n#### 1. 함수 시그니처 및 인수 파싱 업데이트\n\n이 액션은 `configure_executable`가 타겟에 대한 명시적인 `NAME`을 받도록 수정합니다. 이전처럼 소스 파일에서 이름을 파생하는 것은 덜 선언적이며, 명확하지 않은 타겟 이름으로 이어질 수 있습니다. 또한 여러 소스 파일로 빌드되는 실행 파일을 허용하기 위해 `SOURCE`를 `SOURCES`로 변경할 것입니다.\n\n**파일**: `cmake/interface/configure_executable.cmake`\n\n```cmake\n...\n# 인수:\n# NAME (문자열, 필수): 실행 파일 타겟의 이름.\n# SOURCES (리스트, 필수): 실행 파일의 소스 파일 리스트.\n# DEPENDENCIES (리스트, 선택): 이 실행 파일이 의존하는 타겟 리스트.\nfunction(configure_executable)\n # --- 함수 시작: configure_executable\n set(options)\n set(oneValueArgs NAME)\n set(multiValueArgs SOURCES DEPENDENCIES)\n cmake_parse_arguments(ARG \"${options}\" \"${oneValueArgs}\" \"${multiValueArgs}\" ${ARGN})\n\n if(NOT ARG_NAME)\n message(FATAL_ERROR \"configure_executable() 함수는 'NAME' 인수가 필요합니다.\")\n endif()\n\n if(NOT ARG_SOURCES)\n message(FATAL_ERROR \"configure_executable() 함수는 'SOURCES' 인수가 필요합니다.\")\n endif()\n...\n```\n\n#### 2. 실행 파일 타겟 생성 구현\n\n이 액션은 이전의 `add_executable` 로직을 명시적인 `ARG_NAME`과 `ARG_SOURCES` 리스트를 사용하는 새로운 호출로 대체합니다. 이는 함수의 동작을 더 예측 가능하게 만들고 선언적 설계 목표에 부합하도록 합니다.\n\n**파일**: `cmake/interface/configure_executable.cmake`\n\n```cmake\n...\n message(STATUS \"-- 실행 파일 정의 중: ${ARG_NAME}\")\n\n add_executable(${ARG_NAME} ${ARG_SOURCES})\n...\n```\n\n---\n\n### 단계 3: 두 함수에 표준 컴파일 속성을 적용하는 로직\n\n#### 1. `configure_library`에 속성 적용\n\n이 액션은 라이브러리 타겟이 생성된 후 `set_target_compile_properties`를 호출하도록 보장합니다. 이 헬퍼 함수(다른 곳에 정의됨)는 C++ 표준, 컴파일러 경고, 기본 포함 디렉터리와 같은 프로젝트 전반의 설정을 캡슐화하여 모든 라이브러리 타겟에 대한 일관성을 보장합니다. 호출은 `ARG_NAME`을 사용하도록 업데이트됩니다.\n\n**파일**: `cmake/interface/configure_library.cmake`\n\n```cmake\n...\n # 라이브러리 타겟 생성\n add_library(${ARG_NAME} ...) # 이전 단계에서\n\n # 프로젝트 전반의 컴파일 설정 적용\n set_target_compile_properties(${ARG_NAME})\n...\n```\n\n#### 2. `configure_executable`에 속성 적용\n\n이 액션은 실행 파일에 대해 동일한 작업을 수행합니다. `set_target_compile_properties` 호출은 모든 실행 파일이 연결되는 라이브러리와 동일하고 일관된 컴파일러 플래그 및 정의 집합으로 빌드되도록 보장합니다. 호출은 `ARG_NAME`을 사용하도록 업데이트됩니다.\n\n**파일**: `cmake/interface/configure_executable.cmake`\n\n```cmake\n...\n # 실행 파일 타겟 생성\n add_executable(${ARG_NAME} ${ARG_SOURCES})\n\n # 프로젝트 전반의 컴파일 설정 적용\n set_target_compile_properties(${ARG_NAME})\n...\n```\n\n---\n\n### 단계 4: 두 함수에 지정된 종속성을 연결하는 로직\n\n#### 1. `configure_library`에서 종속성 연결\n\n이 액션은 `configure_library` 내에 `add_target_dependencies` 헬퍼 함수 호출을 추가합니다. 이 함수는 `target_link_libraries` 명령을 추상화하고, `ARG_DEPENDENCIES` 리스트로 전달된 종속성을 `ARG_NAME`으로 식별되는 새로 생성된 라이브러리 타겟에 올바르게 연결합니다.\n\n**파일**: `cmake/interface/configure_library.cmake`\n\n```cmake\n...\n set_target_compile_properties(${ARG_NAME})\n\n # 지정된 종속성 연결\n add_target_dependencies(${ARG_NAME}\n DEPENDENCIES\n ${ARG_DEPENDENCIES}\n )\n\n # --- 함수 끝: configure_library\nendfunction()\n```\n\n#### 2. `configure_executable`에서 종속성 연결\n\n이 액션은 실행 파일에 대한 종속성 연결을 구현합니다. `add_target_dependencies`를 호출하여 실행 파일 타겟의 `ARG_NAME`을 전달합니다. 관례에 따라, `ARG_DEPENDENCIES`에 지정된 모든 종속성 외에 주 프로젝트 라이브러리(`${PROJECT_NAME}`)도 자동으로 연결하여 실행 파일이 항상 핵심 프로젝트 기능에 접근할 수 있도록 보장합니다.\n\n**파일**: `cmake/interface/configure_executable.cmake`\n\n```cmake\n...\n set_target_compile_properties(${ARG_NAME})\n\n # 주 프로젝트 라이브러리 및 기타 지정된 종속성 연결\n add_target_dependencies(${ARG_NAME}\n DEPENDENCIES\n ${PROJECT_NAME}\n ${ARG_DEPENDENCIES}\n )\n\n # --- 함수 끝: configure_executable\nendfunction()\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n구현을 검증하기 위해, 개발자는 새로운 함수를 사용하는 임시 테스트 빌드 구성을 생성하고 빌드 시스템이 올바른 타겟을 생성하는지 확인할 것입니다.\n\n1. **임시 디렉터리(예: `build/cmake_test/CMakeLists.txt`)에 테스트 `CMakeLists.txt` 파일을 생성합니다**.\n2. **테스트 파일에 콘텐츠를 추가하여** 새로운 함수를 호출합니다. 이 콘텐츠는 더미 라이브러리와 이에 의존하는 실행 파일을 정의해야 합니다.\n\n ```cmake\n # build/cmake_test/CMakeLists.txt\n cmake_minimum_required(VERSION 3.15)\n project(VerificationTest CXX)\n\n # 주 프로젝트가 구성되어 모듈을 사용할 수 있다고 가정\n # 실제 테스트 설정에서는 주 프로젝트를 add_subdirectory 할 것입니다.\n # 수동 검증을 위해, cmake/가 CMAKE_MODULE_PATH에 있는지 확인하세요.\n set(CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake)\n include(interface/configure_library)\n include(interface/configure_executable)\n\n # 더미 소스 파일 생성\n file(WRITE ${CMAKE_BINARY_DIR}/lib.cpp \"int lib_func() { return 42; }\")\n file(WRITE ${CMAKE_BINARY_DIR}/main.cpp \"int lib_func(); int main() { return lib_func(); }\")\n\n # 새로운 함수 사용\n configure_library(NAME test_lib SOURCES ${CMAKE_BINARY_DIR}/lib.cpp)\n configure_executable(NAME test_app SOURCES ${CMAKE_BINARY_DIR}/main.cpp DEPENDENCIES test_lib)\n ```\n\n3. **`build/cmake_test` 디렉터리 내에서 테스트 프로젝트를 구성합니다**.\n\n ```bash\n # 프로젝트 루트에서\n mkdir -p build/cmake_test && cd build/cmake_test\n cmake ../..\n ```\n\n4. **테스트 타겟을 빌드합니다**.\n\n ```bash\n cmake --build .\n ```\n\n### 4.2. 예상 결과\n\n- `cmake ../..` 명령어는 `FATAL_ERROR` 메시지 없이 완료되어야 합니다. 출력에는 다음 상태 메시지가 포함되어야 합니다:\n - `-- 라이브러리 정의 중: test_lib`\n - `-- 실행 파일 정의 중: test_app`\n- `cmake --build .` 명령어는 성공적으로 완료되어야 합니다. 이 명령어는 `lib.cpp`를 정적 라이브러리로, `main.cpp`를 실행 파일로 컴파일해야 합니다.\n- `test_app` 실행 파일의 링크 단계는 'undefined reference to `lib_func()`' 오류 없이 성공해야 하며, 이는 `test_lib`가 종속성으로 올바르게 연결되었음을 증명합니다.\n- 최종 빌드 프로세스는 종료 코드 0으로 종료되어야 합니다.\n","`CMakeLists.txt`에서 사용하기 위한 `configure_library.cmake` 및 `configure_executable.cmake` 모듈.",[1273,1275,1277,1279],{"_24":1274,"_83":39,"_84":248,"_85":61},"STATIC, SHARED, INTERFACE 타입을 처리하는 `configure_library` 함수.",{"_24":1276,"_83":39,"_84":248,"_85":88},"고유한 타겟 이름을 생성하는 `configure_executable` 함수.",{"_24":1278,"_83":39,"_84":248,"_85":91},"두 함수에 표준 컴파일 속성을 적용하는 로직.",{"_24":1280,"_83":39,"_84":248,"_85":94},"두 함수에 명시된 의존성을 연결하는 로직.","라이브러리 및 실행 파일 빌드 타겟을 정의하기 위한 선언적 함수.",{"_22":1283,"_24":1284,"_75":1285,"_77":1286,"_79":1287,"_51":1298,"_42":99},"task-1750999114566","테스트 스위트 및 커버리지 구성 인터페이스","# 작업: 테스트 스위트 및 커버리지 구성 인터페이스\n\n> **상위 에픽**: 상위 수준 CMake 인터페이스 모듈\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 전체 테스트 및 코드 커버리지 환경을 설정하는 상위 수준 함수.\n- **근거**: 테스트 발견, 실행 파일 생성, CTest 등록, 코드 커버리지 구성의 복잡한 로직을 단일 선언적 함수로 추상화합니다. 이는 계층적이고 가독성 있는 CMake 빌드 시스템이라는 프로젝트의 아키텍처 원칙에 부합하며, 최상위 빌드 스크립트를 단순화하고 유지보수성을 향상시킵니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 테스트 러너를 생성하고 CTest 및 gcovr을 구성하는 `configure_tests.cmake` 모듈.\n- **명세**:\n - CMake 함수 `configure_tests()`가 정의됩니다.\n - 함수 시그니처는 `TEST_DIR`, `ENABLE_COVERAGE`, `FUNCTION_COVERAGE`, `LINE_COVERAGE` 인자를 받습니다.\n - `run_all_tests`라는 이름의 단일 테스트 실행 파일 타겟을 생성합니다.\n - 포함된 `register_test_case.cmake` 헬퍼를 사용하여 각 테스트 소스 파일을 개별 CTest 케이스로 등록합니다.\n - 포함된 `check_code_coverage.cmake` 헬퍼를 사용하여 조건부로 커버리지 생성 단계를 추가합니다.\n- **결과 파일 구조**\n (이 작업은 주로 기존 모듈 파일의 구현 및 검증을 포함합니다.)\n\n```bash\n# ./cmake/\n# ├── interface/\n# │ └── configure_tests.cmake <-- 구현됨\n# └── test/\n# ├── check_code_coverage.cmake <-- 활용됨\n# └── register_test_case.cmake <-- 활용됨\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 상위 수준 `CMakeLists.txt`에서 호출될 때 `configure_tests` 함수가 수행하는 내부 오케스트레이션을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n A[\"configure_tests(...) 호출\"] --> B{인자 파싱};\n B --> C[TEST_DIR에서 테스트 소스 Glob];\n C --> D[\"'run_all_tests' 실행 파일 생성\"];\n D --> E[\"의존성 링크: 프로젝트 라이브러리 & Catch2\"];\n \n subgraph CTest 구성\n C --> F[각 테스트 소스에 대해 반복];\n F --> G[register_test_case 헬퍼 호출];\n G --> H[CTest에 개별 테스트 추가];\n end\n \n subgraph 빌드 후 작업\n E --> I[CTest 실행을 위한 빌드 후 명령 추가];\n B --> J{커버리지 활성화됨?};\n J -- 예 --> K[check_code_coverage 헬퍼 호출];\n K --> L[gcovr 실행을 위한 빌드 후 명령 추가];\n end\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이는 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] `configure_tests` 함수 정의.\n- [ ] 모든 테스트 소스로부터 `run_all_tests` 실행 파일 생성.\n- [ ] `register_test_case.cmake` 헬퍼를 사용한 자동화된 테스트 케이스 등록.\n- [ ] `check_code_coverage.cmake` 헬퍼를 사용한 조건부 코드 커버리지 설정.\n- [ ] 테스트 자동 실행을 위한 빌드 후 명령.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층적 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **모듈식 CMake 빌드 시스템**: 이 작업은 빌드 시스템의 인터페이스 계층에 위치하는 중요한 상위 수준 인터페이스 함수(`configure_tests`)를 구현합니다. 이는 하위 수준의 테스트 및 도구 구성 로직을 캡슐화합니다.\n - **테스트 스위트**: 이 모듈은 테스트 소스를 실행 파일로 빌드하고, CTest에 등록하며, 실행하는 데 필요한 구성과 자동화를 제공합니다. 이는 `테스트 스위트` 구성 요소의 기능을 직접적으로 활성화합니다.\n - **품질 보증 툴체인**: 이 모듈은 QA 툴체인의 일부, 특히 테스트 실행 관리를 위한 CTest와 코드 커버리지 분석을 위한 `gcovr`을 직접 통합하여 표준 빌드 프로세스를 통해 접근할 수 있도록 합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `cmake/interface/configure_tests.cmake`\n- `cmake/test/register_test_case.cmake`\n- `cmake/test/check_code_coverage.cmake`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공할 것입니다.\n\n---\n\n### 단계 1: `configure_tests` 함수 정의\n\n#### 1. 함수 정의 및 인자 파싱\n\n이 액션은 `configure_tests` 함수를 만들고 `cmake_parse_arguments`를 사용하여 이름 있는 인자를 처리합니다. 이 표준적인 방법은 함수의 인터페이스를 깔끔하고 자체적으로 문서화되도록 만듭니다. 테스트 소스 파일의 위치를 지정하는 필수 `TEST_DIR` 인자가 제공되지 않으면 치명적인 오류가 발생합니다.\n\n**파일**: `cmake/interface/configure_tests.cmake`\n\n```cmake\n# ... (포함)\n\nfunction(configure_tests)\n # --- 함수 시작: configure_tests\n set(options)\n set(oneValueArgs TEST_DIR ENABLE_COVERAGE FUNCTION_COVERAGE LINE_COVERAGE)\n set(multiValueArgs)\n cmake_parse_arguments(ARG \"${options}\" \"${oneValueArgs}\" \"${multiValueArgs}\" ${ARGN})\n\n if(NOT ARG_TEST_DIR)\n message(FATAL_ERROR \"configure_tests() requires the 'TEST_DIR' argument.\")\n endif()\n\n # ...\nendfunction()\n```\n\n---\n\n### 단계 2: `run_all_tests` 실행 파일을 모든 테스트 소스로부터 생성\n\n#### 1. 테스트 소스 파일 발견\n\n이 액션은 `file(GLOB_RECURSE)`를 사용하여 제공된 `TEST_DIR` 내의 모든 `.cpp` 파일을 자동으로 발견합니다. 이로써 각 테스트 파일을 수동으로 나열할 필요가 없어지며, 새로운 테스트가 빌드에 자동으로 포함되도록 보장합니다.\n\n**파일**: `cmake/interface/configure_tests.cmake`\n\n```cmake\n # ...\n\n include(CTest)\n\n file(GLOB_RECURSE test_sources\n CONFIGURE_DEPENDS \"${ARG_TEST_DIR}/*.cpp\"\n )\n\n # ...\n```\n\n#### 2. 테스트 실행 파일 정의 및 링크\n\n이 액션은 발견된 소스 파일로부터 `run_all_tests` 실행 파일을 생성합니다. 그런 다음 이 타겟을 주 프로젝트 라이브러리(`${PROJECT_NAME}`)에 링크하여 그 기능을 테스트하고, `Catch2::Catch2WithMain`에 링크하여 테스트 프레임워크의 진입점과 단언(assertion) 라이브러리를 제공합니다.\n\n**파일**: `cmake/interface/configure_tests.cmake`\n\n```cmake\n # ...\n\n add_executable(run_all_tests ${test_sources})\n\n set_target_compile_properties(run_all_tests)\n\n add_target_dependencies(run_all_tests\n DEPENDENCIES\n ${PROJECT_NAME}\n Catch2::Catch2WithMain\n )\n\n # ...\n```\n\n---\n\n### 단계 3: `register_test_case.cmake` 헬퍼를 사용한 자동화된 테스트 케이스 등록\n\n#### 1. 테스트 등록 헬퍼 포함\n\n이 액션은 `register_test_case.cmake` 모듈을 포함하여 `configure_tests` 함수 내에서 그 기능을 사용할 수 있게 합니다. 이는 테스트 등록 로직을 주 테스트 구성 흐름에서 분리함으로써 모듈식 설계를 준수합니다.\n\n**파일**: `cmake/interface/configure_tests.cmake`\n\n```cmake\n# ...\ninclude(cmake/test/check_code_coverage.cmake)\ninclude(cmake/test/register_test_case.cmake)\n\nfunction(configure_tests)\n # ...\n```\n\n#### 2. CTest에 개별 테스트 등록\n\n이 액션은 발견된 각 테스트 소스 파일을 순회하며 `register_test_case` 헬퍼를 호출합니다. 이 헬퍼 함수는 파일 경로에서 설명적인 이름을 추출하고 이를 CTest에 별개의 테스트 케이스로 등록합니다. 이를 통해 개발자는 `ctest -R `을 사용하여 특정 테스트를 실행할 수 있으며, 디렉터리 구조에 기반한 테스트 레이블링(예: `unit`, `integration`)이 가능해집니다.\n\n**파일**: `cmake/interface/configure_tests.cmake`\n\n```cmake\n # ...\n\n add_test(NAME all-tests COMMAND run_all_tests)\n\n foreach(test_source ${test_sources})\n register_test_case(${test_source})\n endforeach()\n\n # ...\n```\n\n---\n\n### 단계 4: `check_code_coverage.cmake` 헬퍼를 사용한 조건부 코드 커버리지 설정\n\n#### 1. 코드 커버리지 헬퍼 포함\n\n이 액션은 gcovr 설정을 위한 전문화된 로직을 포함하는 `check_code_coverage.cmake` 모듈을 포함합니다. 이는 `configure_tests` 함수를 깔끔하게 유지하고 오케스트레이션에 집중하도록 합니다.\n\n**파일**: `cmake/interface/configure_tests.cmake`\n\n```cmake\n# 설명:\n# ...\n\ninclude(cmake/test/check_code_coverage.cmake)\ninclude(cmake/test/register_test_case.cmake)\n\n# ...\n```\n\n#### 2. 커버리지 구성 함수 호출\n\n이 액션은 `check_code_coverage()` 함수를 호출합니다. 이 함수는 부모 `configure_tests` 함수에 전달된 인자(`ENABLE_COVERAGE` 등)를 읽고, 커버리지가 활성화된 경우 `run_all_tests` 타겟에 `gcovr`로 커버리지 보고서를 생성하는 빌드 후 명령을 구성합니다. 이는 `gcovr` 실행 파일 찾기 및 올바른 플래그로 명령어 빌드와 같은 모든 커버리지 관련 로직을 캡슐화합니다.\n\n**파일**: `cmake/interface/configure_tests.cmake`\n\n```cmake\n # ...\n\n add_custom_command(\n # ... (빌드 후 테스트 실행)\n )\n\n check_code_coverage()\n\n # --- 함수 끝: configure_tests\nendfunction()\n```\n\n---\n\n### 단계 5: 테스트 자동 실행을 위한 빌드 후 명령\n\n#### 1. CTest 실행을 위한 빌드 후 명령 추가\n\n이 액션은 `run_all_tests` 타겟이 성공적으로 빌드된 후 자동으로 `ctest`를 실행하는 사용자 지정 명령을 추가합니다. 이는 빌드 과정에서 개발자에게 즉각적인 피드백을 제공하여, 별도의 수동 단계 없이 테스트 실패를 알려줍니다. `--output-on-failure` 플래그는 테스트가 실패할 경우에만 테스트 세부 정보가 출력되도록 하여, 성공 시 빌드 로그를 깔끔하게 유지합니다.\n\n**파일**: `cmake/interface/configure_tests.cmake`\n\n```cmake\n # ... (테스트 등록)\n\n add_custom_command(\n TARGET run_all_tests\n POST_BUILD\n COMMAND ${CMAKE_CTEST_COMMAND} --output-on-failure\n WORKING_DIRECTORY ${CMAKE_BINARY_DIR}\n COMMENT \"빌드 후 모든 테스트 자동 실행 중...\"\n VERBATIM\n )\n\n # ... (커버리지 확인)\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n이 모듈의 올바른 구현을 검증하려면, 상위 수준 `CMakeLists.txt` 파일(예: `tests/CMakeLists.txt`)에서 호출해야 합니다.\n\n1. **`tests/CMakeLists.txt` 파일을 생성하여** 함수를 호출합니다:\n\n ```cmake\n # tests/CMakeLists.txt\n include(cmake/interface/configure_tests.cmake)\n\n configure_tests(\n TEST_DIR ${CMAKE_CURRENT_SOURCE_DIR}\n ENABLE_COVERAGE ${ENABLE_COVERAGE}\n FUNCTION_COVERAGE 80\n LINE_COVERAGE 80\n )\n ```\n\n2. 빌드 디렉터리에서 **CMake를 구성합니다**. 커버리지를 테스트하려면 해당 옵션을 활성화합니다.\n\n ```bash\n # 프로젝트 루트에서\n mkdir build && cd build\n cmake .. -DENABLE_COVERAGE=ON\n ```\n\n3. **프로젝트를 빌드합니다**. 이렇게 하면 빌드 후 테스트 실행이 트리거됩니다.\n\n ```bash\n make\n ```\n\n4. **수동으로 CTest를 실행하여** 등록을 확인하고 테스트를 실행합니다.\n\n ```bash\n # 등록된 모든 테스트 나열\n ctest -N\n\n # 상세 모드로 테스트 실행\n ctest -V\n ```\n\n5. **커버리지 보고서를 확인합니다** (활성화된 경우).\n\n ```bash\n # 생성된 HTML 보고서 확인\n ls coverage/index.html\n ```\n\n### 4.2. 예상 결과\n\n- `make` 명령 실행 중, `[100%] Linking CXX executable bin/run_all_tests` 단계 이후에 메시지 `빌드 후 모든 테스트 자동 실행 중...`가 표시되고, 그 뒤에 모든 테스트가 통과되었음을 나타내는 CTest 출력이 나와야 합니다.\n\n- `ctest -N`의 출력은 발견된 모든 테스트를 나열해야 합니다. 여기에는 일반적인 `all-tests`와 파일 이름에서 파생된 특정 테스트(예: `unit.test_add`, `unit.test_subtract`)가 포함됩니다.\n\n ```\n Test #1: all-tests\n Test #2: integration.test_arithmetic\n Test #3: unit.test_add\n Test #4: unit.test_subtract\n\n Total Tests: 4\n ```\n\n- `ctest -V`의 출력은 각 테스트가 통과하는 것을 보여주어야 합니다.\n\n- `ENABLE_COVERAGE`가 `ON`이었다면, `coverage/index.html` 파일이 빌드 디렉터리에 존재할 것입니다.\n","테스트 러너를 생성하고 CTest 및 gcovr를 구성하는 `configure_tests.cmake` 모듈.",[1288,1290,1292,1294,1296],{"_24":1289,"_83":39,"_84":266,"_85":61},"`configure_tests` 함수 정의.",{"_24":1291,"_83":39,"_84":266,"_85":88},"모든 테스트 소스로부터 `run_all_tests` 실행 파일 생성.",{"_24":1293,"_83":39,"_84":266,"_85":91},"`register_test_case.cmake` 헬퍼를 사용한 자동화된 테스트 케이스 등록.",{"_24":1295,"_83":39,"_84":266,"_85":94},"`check_code_coverage.cmake` 헬퍼를 사용한 조건부 코드 커버리지 설정.",{"_24":1297,"_83":39,"_84":266,"_85":97},"빌드 후 테스트를 자동으로 실행하는 명령어.","전체 테스트 및 코드 커버리지 환경을 설정하는 고수준 함수.",{"_22":1300,"_24":1301,"_75":1302,"_77":1303,"_79":1304,"_51":1313,"_42":99},"task-1750999173343","개발자 도구 구성 인터페이스","# 작업: 개발자 도구 설정 인터페이스\n\n> **에픽**: 상위 수준 CMake 인터페이스 모듈\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 개발자 생산성 도구를 위한 사용자 정의 빌드 타겟을 생성하는 상위 수준 함수를 만듭니다.\n- **근거**: 개발자 도구(포매터, 정적 분석기, 문서 생성기)의 복잡한 설정 로직을 단순한 상위 수준 함수로 캡슐화합니다. 이는 프로젝트의 계층적 CMake 아키텍처와 일치하며, 최상위 `CMakeLists.txt`에 깔끔하고 선언적인 API를 제공하고 주 빌드 스크립트로부터 구현 세부 사항을 숨깁니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: `configure_formatter`, `configure_static_analysis`, `configure_doxygen`을 위한 모듈.\n- **사양**:\n - `함수: configure_formatter()`: `format`이라는 이름의 사용자 정의 타겟을 생성합니다.\n - `함수: configure_static_analysis(SOURCES )`: `static_analysis`라는 이름의 사용자 정의 타겟을 생성합니다.\n - `함수: configure_doxygen()`: `create_documentations`라는 이름의 사용자 정의 타겟을 생성합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── cmake/\n# └── interface/\n# ├── configure_doxygen.cmake <-- 신규\n# ├── configure_formatter.cmake <-- 신규\n# └── configure_static_analysis.cmake <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 빌드 시간의 조율 과정을 보여줍니다. 주 CMake 스크립트는 상위 수준 설정 함수를 호출하여 사용자 정의 타겟을 정의합니다. 개발자는 빌드 도구(예: `make`)를 통해 이러한 타겟을 직접 실행할 수 있습니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"설정 시간 (cmake ..)\"\n A[\"최상위 CMakeLists.txt\"] --> B{\"configure_formatter() 호출\"};\n A --> C{\"configure_static_analysis() 호출\"};\n A --> D{\"configure_doxygen() 호출\"};\n B --> E[\"format 타겟 정의\"];\n C --> F[\"static_analysis 타겟 정의\"];\n D --> G[\"create_documentations 타겟 정의\"];\n end\n \n subgraph \"빌드 시간 (make )\"\n H[개발자] --> I{\"make format 실행\"};\n H --> J{\"make static_analysis 실행\"};\n H --> K{\"make create_documentations 실행\"};\n I --> L[Clang-Format 도구];\n J --> M[Clang-Tidy 도구];\n K --> N[Doxygen 도구];\n end\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] `format` 타겟을 생성하는 `configure_formatter` 함수.\n- [ ] `static_analysis` 타겟을 생성하는 `configure_static_analysis` 함수.\n- [ ] `create_documentations` 타겟을 생성하는 `configure_doxygen` 함수.\n- [ ] 각 도구에 대한 기본 스크립트 및 설정 파일 통합.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층적 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **주요 관련 구성 요소**:\n - **모듈식 CMake 빌드 시스템**: 확장 대상이 되는 핵심 구성 요소입니다. 이 작업은 새로운 상위 수준 인터페이스 함수 계층을 추가하여 빌드 시스템의 선언적 스타일을 강화합니다.\n - **품질 보증 도구 체인**: 통합될 도구들(`clang-format`, `clang-tidy`, `doxygen`)을 나타내는 구성 요소입니다. 새로운 CMake 함수는 다리 역할을 하여 빌드 시스템이 간단하고 통일된 명령을 통해 이러한 외부 도구를 제어하고 실행할 수 있게 합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `cmake/interface/configure_formatter.cmake`\n- `cmake/interface/configure_static_analysis.cmake`\n- `cmake/interface/configure_doxygen.cmake`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `조치`로 나뉩니다. 각 `조치`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `format` 타겟을 생성하는 `configure_formatter` 함수\n\n#### 1. `configure_formatter` CMake 함수 생성\n\n이 조치는 `configure_formatter` 함수를 정의하는 새로운 CMake 모듈 파일을 생성하는 것을 포함합니다. 이 함수의 책임은 `clang-format` 실행 파일을 찾고 `format`이라는 이름의 사용자 정의 타겟을 정의하는 것입니다. 이 타겟이 호출되면(예: `make format`), 프로젝트 내의 모든 C++ 소스 및 헤더 파일에 대해 `clang-format`을 실행합니다. 이 캡슐화는 도구 찾기 및 명령줄 구성 로직을 주 빌드 스크립트로부터 추상화합니다.\n\n**파일**: `cmake/interface/configure_formatter.cmake`\n\n```cmake\n# 설명:\n# 코드 포매터(clang-format)를 실행하기 위한 사용자 정의 타겟을 설정합니다.\n# 프로젝트의 모든 C++ 소스 및 헤더 파일에 적용됩니다.\n#\nfunction(configure_formatter)\n find_program(CLANG_FORMAT_EXECUTABLE clang-format)\n if(NOT CLANG_FORMAT_EXECUTABLE)\n message(WARNING \"clang-format을 찾을 수 없습니다. 'format' 타겟을 사용할 수 없습니다.\")\n return()\n endif()\n\n # 포매팅할 모든 관련 소스 및 헤더 파일을 수집합니다.\n file(GLOB_RECURSE FORMAT_SOURCES\n \"${PROJECT_SOURCE_DIR}/executables/*.cpp\"\n \"${PROJECT_SOURCE_DIR}/include/*.hpp\"\n \"${PROJECT_SOURCE_DIR}/source/*.cpp\"\n \"${PROJECT_SOURCE_DIR}/tests/*.cpp\"\n )\n\n add_custom_target(format\n COMMAND ${CLANG_FORMAT_EXECUTABLE} -i -style=file ${FORMAT_SOURCES}\n WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}\n COMMENT \"clang-format으로 C++ 코드 포매팅 중...\"\n VERBATIM\n )\n\n message(STATUS \"clang-format을 실행하는 'format' 타겟을 추가했습니다.\")\nendfunction()\n```\n\n---\n\n### 단계 2: `static_analysis` 타겟을 생성하는 `configure_static_analysis` 함수\n\n#### 1. `configure_static_analysis` CMake 함수 생성\n\n이 조치는 새로운 모듈 파일에 `configure_static_analysis` 함수를 정의합니다. 이 함수는 `static_analysis` 사용자 정의 타겟을 생성하도록 설계되었습니다. 빌드의 일부인 파일만 분석하도록 `SOURCES` 인자를 통해 소스 파일 목록을 받아야 합니다. 이 함수는 `clang-tidy` 실행 파일을 찾아 CMake가 생성한 컴파일 데이터베이스(`compile_commands.json`)를 컨텍스트로 사용하여 지정된 파일에 대해 실행하도록 타겟을 설정합니다. `cmake_parse_arguments`를 사용하면 견고한 함수 시그니처를 보장할 수 있습니다.\n\n**파일**: `cmake/interface/configure_static_analysis.cmake`\n\n```cmake\n# 설명:\n# 정적 분석(clang-tidy)을 실행하기 위한 사용자 정의 타겟을 설정합니다.\n#\n# 인자:\n# SOURCES: 분석할 소스 파일 목록.\n#\nfunction(configure_static_analysis)\n set(options)\n set(oneValueArgs)\n set(multiValueArgs SOURCES)\n cmake_parse_arguments(ARG \"${options}\" \"${oneValueArgs}\" \"${multiValueArgs}\" ${ARGN})\n\n if(NOT ARG_SOURCES)\n message(FATAL_ERROR \"configure_static_analysis() 함수는 'SOURCES' 인자가 필요합니다.\")\n endif()\n\n find_program(CLANG_TIDY_EXECUTABLE clang-tidy)\n if(NOT CLANG_TIDY_EXECUTABLE)\n message(WARNING \"clang-tidy를 찾을 수 없습니다. 'static_analysis' 타겟을 사용할 수 없습니다.\")\n return()\n endif()\n\n # -p 플래그는 clang-tidy에게 컴파일 데이터베이스를 찾도록 지시합니다.\n add_custom_target(static_analysis\n COMMAND ${CLANG_TIDY_EXECUTABLE} -p=${PROJECT_BINARY_DIR} ${ARG_SOURCES}\n WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}\n COMMENT \"clang-tidy로 정적 분석 실행 중...\"\n VERBATIM\n )\n\n message(STATUS \"clang-tidy를 실행하는 'static_analysis' 타겟을 추가했습니다.\")\nendfunction()\n```\n\n---\n\n### 단계 3: `create_documentations` 타겟을 생성하는 `configure_doxygen` 함수\n\n#### 1. `configure_doxygen` CMake 함수 생성\n\n이 조치는 `configure_doxygen` 함수를 생성합니다. 이 함수의 목적은 API 문서 생성을 조율하는 것입니다. `Doxygen` 패키지를 찾고, `configure_file`을 사용하여 `doxyfile.in` 템플릿을 처리하며(프로젝트 이름 및 소스 디렉토리와 같은 변수 치환), `create_documentations` 사용자 정의 타겟을 생성합니다. 이 타겟이 실행되면, 새로 생성된 설정 파일을 사용하여 Doxygen을 호출하고 빌드 디렉토리에 API 문서를 생성합니다.\n\n**파일**: `cmake/interface/configure_doxygen.cmake`\n\n```cmake\n# 설명:\n# Doxygen을 사용하여 API 문서를 생성하는 사용자 정의 타겟을 설정합니다.\n#\nfunction(configure_doxygen)\n find_package(Doxygen)\n if(NOT DOXYGEN_FOUND)\n message(WARNING \"Doxygen을 찾을 수 없습니다. 'create_documentations' 타겟을 사용할 수 없습니다.\")\n return()\n endif()\n\n set(DOXYGEN_IN ${PROJECT_SOURCE_DIR}/assets/doxyfile.in)\n set(DOXYGEN_OUT ${PROJECT_BINARY_DIR}/doxyfile)\n\n # 프로젝트별 경로로 Doxyfile 템플릿을 설정합니다\n configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)\n\n add_custom_target(create_documentations\n COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}\n WORKING_DIRECTORY ${PROJECT_BINARY_DIR}\n COMMENT \"Doxygen으로 API 문서 생성 중...\"\n VERBATIM\n )\n\n message(STATUS \"Doxygen을 실행하는 'create_documentations' 타겟을 추가했습니다.\")\nendfunction()\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 개발자는 먼저 최상위 `CMakeLists.txt`가 이 새로운 함수들을 포함하고 호출하는지 확인해야 합니다. 그런 다음, 깨끗한 빌드 디렉토리에서 다음 명령을 실행합니다.\n\n```bash\n# 1. 프로젝트 루트로 이동하여 빌드 디렉토리를 생성합니다\nmkdir build && cd build\n\n# 2. CMake로 프로젝트를 설정합니다. CMAKE_EXPORT_COMPILE_COMMANDS가 ON인지 확인합니다.\n# 이것은 clang-tidy에 필요합니다.\ncmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..\n\n# 3. 'format' 타겟이 오류 없이 실행되는지 확인합니다.\nmake format\n\n# 4. 'static_analysis' 타겟이 오류 없이 실행되는지 확인합니다.\nmake static_analysis\n\n# 5. 'create_documentations' 타겟이 오류 없이 실행되는지 확인합니다.\nmake create_documentations\n\n# 6. 생성된 문서를 확인합니다.\nls documents/html\n```\n\n### 4.2. 예상 결과\n\n- **`cmake ..`**: 출력에 다음 상태 메시지가 포함되어야 합니다:\n - `STATUS clang-format을 실행하는 'format' 타겟을 추가했습니다.`\n - `STATUS clang-tidy를 실행하는 'static_analysis' 타겟을 추가했습니다.`\n - `STATUS Doxygen을 실행하는 'create_documentations' 타겟을 추가했습니다.`\n- **`make format`**: 빌드 도구는 `clang-format으로 C++ 코드 포매팅 중...` 주석을 출력하고 성공적으로 완료해야 합니다.\n- **`make static_analysis`**: 빌드 도구는 `clang-tidy로 정적 분석 실행 중...` 주석을 출력하고 성공적으로 완료해야 합니다. `clang-tidy`가 발견한 모든 사항은 콘솔에 출력됩니다.\n- **`make create_documentations`**: 빌드 도구는 `Doxygen으로 API 문서 생성 중...` 주석을 출력하고 성공적으로 완료해야 합니다.\n- **`ls documents/html`**: 이 명령은 Doxygen이 생성한 HTML 파일(예: `index.html`, 클래스 파일 등)을 나열하여 빌드 디렉토리에 문서가 생성되었음을 확인해야 합니다.\n","`configure_formatter`, `configure_static_analysis`, `configure_doxygen`을 위한 모듈.",[1305,1307,1309,1311],{"_24":1306,"_83":39,"_84":284,"_85":61},"`format` 타겟을 생성하는 `configure_formatter` 함수.",{"_24":1308,"_83":39,"_84":284,"_85":88},"`static_analysis` 타겟을 생성하는 `configure_static_analysis` 함수.",{"_24":1310,"_83":39,"_84":284,"_85":91},"`create_documentations` 타겟을 생성하는 `configure_doxygen` 함수.",{"_24":1312,"_83":39,"_84":284,"_85":94},"각 도구에 대한 기본 스크립트 및 구성 파일 통합.","개발자 생산성 도구를 위한 사용자 정의 빌드 타겟을 생성하는 고수준 함수.",{"_22":1315,"_24":1316,"_75":1317,"_77":1318,"_79":1319,"_51":1328,"_42":99},"task-1750999222080","Git 서브모듈을 통한 spdlog 통합","# 작업: Git 서브모듈을 통한 spdlog 통합\n\n> **에픽**: 의존성 통합 프레임워크\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 버전 관리되는 의존성으로 spdlog 라이브러리를 통합합니다.\n- **근거**: 빌드 재현성과 안정성을 보장하기 위해, 프로젝트는 외부 의존성 버전을 고정하는 메커니즘이 필요합니다. `spdlog`에 Git 서브모듈을 사용하면 라이브러리의 특정 커밋이 메인 프로젝트의 Git 기록에 직접 포함됩니다. 이를 통해 모든 개발자와 빌드 환경이 정확히 동일한 버전의 의존성을 사용하게 되어, 라이브러리의 다른 버전으로 인해 발생할 수 있는 불일치를 방지할 수 있습니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: spdlog 리포지토리를 추적하는 `.gitmodules` 파일이 생성되어, 빌드 시스템에서 해당 타겟을 사용할 수 있게 됩니다.\n- **사양**:\n - 프로젝트 루트에 새 파일 `.gitmodules`가 생성됩니다.\n - `dependencies/internals/spdlog/` 디렉터리가 spdlog 라이브러리의 소스 코드로 채워집니다.\n - `spdlog` 라이브러리는 `add_subdirectory()`를 통해 CMake 빌드 시스템에서 발견할 수 있으며, 연결을 위해 `spdlog::spdlog` 타겟을 노출합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n├── .gitmodules <-- New\n├── dependencies/\n│ └── internals/\n│ └── spdlog/ <-- Populated by Git\n└── ...\n```\n\n- **프로세스 흐름도**\n이 다이어그램은 서브모듈의 빌드 시점 통합 흐름을 보여줍니다. 개발자의 일회성 조치를 통해 CMake 빌드 시스템은 모든 후속 빌드에서 자동으로 의존성을 통합할 수 있습니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n A[개발자가
git submodule add 실행] --> B{Git이 .gitmodules 파일을 생성하고
리포지토리를 복제};\n B --> C[CMake 빌드 프로세스 시작];\n C --> D{\"add_subdirectory(dependencies/internals)\"};\n D --> E{CMake가 spdlog/CMakeLists.txt 처리};\n E --> F[CMake 타겟 spdlog::spdlog
사용 가능];\n F --> G[프로젝트 타겟이
spdlog::spdlog에 연결 가능];\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이것은 개략적인 체크리스트이며, 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] `.gitmodules`에 spdlog 서브모듈 항목 추가.\n- [ ] `dependencies/internals/spdlog`에 정확한 경로 지정.\n- [ ] `configure_project`에서 서브모듈을 발견할 수 있는지 확인.\n- [ ] 복제되어 사용할 준비가 된 서브모듈.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층형 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련된 주요 구성 요소**:\n - **의존성 관리 시스템**: 이 구성 요소는 외부 라이브러리를 관리하는 직접적인 책임이 있습니다. 이 작업은 버전 관리되는 소스 수준 의존성에 Git 서브모듈을 사용하여 시스템의 핵심 전략을 구현합니다. 서브모듈은 프로젝트의 일부로 빌드된다는 것을 나타내기 위해 `dependencies/internals/`에 위치합니다.\n - **모듈식 CMake 빌드 시스템**: 이 구성 요소는 의존성 관리 시스템에서 제공하는 의존성을 사용합니다. 빌드 시스템은 `dependencies/internals/` 디렉터리를 자동으로 스캔하도록 설계되었습니다. `spdlog` 서브모듈을 찾으면 `add_subdirectory`를 통해 해당 `CMakeLists.txt`를 처리하여 `spdlog`의 타겟을 메인 프로젝트 빌드 그래프에 통합합니다.\n\n### 2.2. 영향을 받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `.gitmodules`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: .gitmodules에 spdlog 서브모듈 항목 추가\n\n#### 1. spdlog Git 서브모듈 추가\n\n이 작업은 표준 Git 명령을 사용하여 `spdlog` 리포지토리를 서브모듈로 등록합니다. 이 명령은 프로젝트 루트에 `.gitmodules` 파일을 자동으로 생성하고, 서브모듈의 로컬 경로와 원격 URL을 지정하는 필수 구성을 추가합니다. 이 파일은 모든 개발자와 의존성 구성을 공유하기 위해 리포지토리에 커밋되어야 합니다.\n\n**파일**: `.gitmodules`\n\n```\n[submodule \"dependencies/internals/spdlog\"]\n path = dependencies/internals/spdlog\n url = https://github.com/gabime/spdlog.git\n```\n\n---\n\n### 단계 2: `dependencies/internals/spdlog`에 정확한 경로 지정\n\n#### 1. 서브모듈 추가 명령 실행\n\n이 작업은 서브모듈을 생성하고 프로젝트 아키텍처에서 지정한 정확한 디렉터리에 그 내용을 배치합니다. `git submodule add` 명령이 이 작업을 수행합니다. 이 명령은 Git에게 `spdlog` 리포지토리를 `dependencies/internals/spdlog` 경로로 복제하도록 지시합니다. 이 경로는 CMake 빌드 시스템이 내부 의존성을 검색하도록 구성된 위치이므로 매우 중요합니다.\n\n**셸 명령**:\n\n```bash\n# 이 명령을 프로젝트 루트 디렉터리에서 실행하세요.\ngit submodule add https://github.com/gabime/spdlog.git dependencies/internals/spdlog\n```\n\n---\n\n### 단계 3: `configure_project`에서 서브모듈을 발견할 수 있는지 확인\n\n#### 1. CMake 발견 메커니즘 확인\n\n이 작업은 코드 수정이 아닌 이해를 요구합니다. 프로젝트의 `모듈식 CMake 빌드 시스템`은 `dependencies/internals/` 내의 하위 디렉터리를 자동으로 발견하고 통합하도록 미리 구성되어 있습니다. 상위 수준의 `configure_project` 함수(또는 이 함수가 호출하는 유틸리티)는 `dependencies/internals/spdlog`에 대해 `add_subdirectory()`를 실행합니다. 이 과정에서 `spdlog` 자체의 `CMakeLists.txt`가 처리되어 라이브러리 타겟(예: `spdlog::spdlog`)이 정의됩니다. CMake 구성 단계(4절 참조)의 성공적인 실행이 서브모듈을 발견할 수 있다는 검증이 됩니다. 이 단계에서는 파일이 변경되지 않으며, 시스템 설계의 확인 과정입니다.\n\n---\n\n### 단계 4: 복제되어 사용할 준비가 된 서브모듈\n\n#### 1. 서브모듈 내용 초기화 및 복제\n\n이 작업은 서브모듈의 소스 코드가 로컬에 존재하도록 보장합니다. `git submodule add`는 실행한 사용자를 위해 내용을 복제하지만, 메인 리포지토리를 복제하는 다른 개발자는 서브모듈 디렉터리를 채우기 위해 추가 명령을 실행해야 합니다. `git submodule update --init` 명령은 `.gitmodules` 파일을 읽고 메인 프로젝트가 추적하는 특정 커밋에서 서브모듈 내용을 복제합니다. `--recursive` 플래그는 중첩된 서브모듈을 초기화하는 데 가장 좋은 방법입니다.\n\n**셸 명령**:\n\n```bash\n# 이 명령은 메인 리포지토리를 방금 복제한 개발자를 위한 것입니다.\n# 이 명령은 비어있는 dependencies/internals/spdlog 디렉터리를 채웁니다.\ngit submodule update --init --recursive\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 개발자는 서브모듈의 올바른 구현을 검증하기 위해 프로젝트 루트에서 다음 명령을 실행해야 합니다.\n\n```bash\n# 1. 서브모듈 추가 (이것이 주요 구현 단계입니다.)\n# 이미 완료했다면 2단계로 건너뛰세요.\ngit submodule add https://github.com/gabime/spdlog.git dependencies/internals/spdlog\n\n# 2. git status를 확인하여 새 파일을 봅니다.\ngit status\n\n# 3. .gitmodules 파일의 내용을 검사합니다.\ncat .gitmodules\n\n# 4. 서브모듈 디렉터리가 채워졌는지 확인합니다.\nls dependencies/internals/spdlog\n\n# 5. CMake 구성을 실행하여 의존성이 성공적으로 통합되었는지 확인합니다.\n# 이는 소스 외부 빌드를 위한 'build' 디렉터리가 있다고 가정합니다.\ncmake -S . -B build\n```\n\n### 4.2. 예상 결과\n\n- `git status`의 출력은 새 파일(`.gitmodules`)과 해당 경로(`dependencies/internals/spdlog`)에 대한 새 커밋 참조를 보여주어야 합니다.\n\n```\nOn branch main\nYour branch is up to date with 'origin/main'.\n\nChanges to be committed:\n (use \"git restore --staged ...\" to unstage)\n new file: .gitmodules\n new file: dependencies/internals/spdlog\n```\n\n- `cat .gitmodules`의 출력은 단계 1에서 지정된 내용과 일치해야 합니다.\n\n```\n[submodule \"dependencies/internals/spdlog\"]\n path = dependencies/internals/spdlog\n url = https://github.com/gabime/spdlog.git\n```\n\n- `ls` 명령은 `spdlog` 리포지토리의 내용(예: `CMakeLists.txt`, `include/`, `src/`)을 나열해야 합니다.\n\n- `cmake` 명령은 `spdlog`를 찾는 것과 관련된 오류 없이 성공적으로 완료되어야 합니다. 출력에는 `spdlog` 프로젝트의 구성을 나타내는 줄이 포함되어야 합니다.\n","spdlog 저장소를 추적하여 빌드 시스템에서 해당 타겟을 사용할 수 있게 하는 `.gitmodules` 파일.",[1320,1322,1324,1326],{"_24":1321,"_83":39,"_84":302,"_85":61},"`.gitmodules`에 spdlog 서브모듈 항목 추가.",{"_24":1323,"_83":39,"_84":302,"_85":88},"`dependencies/internals/spdlog`에 정확한 경로 명시.",{"_24":1325,"_83":39,"_84":302,"_85":91},"`configure_project`에 의해 서브모듈이 검색 가능한지 확인.",{"_24":1327,"_83":39,"_84":302,"_85":94},"사용 준비가 된 복제된 서브모듈.","버전 관리되는 의존성으로 spdlog 라이브러리 통합.",{"_22":1330,"_24":1331,"_75":1332,"_77":1333,"_79":1334,"_51":1343,"_42":99},"task-1750999269968","FetchContent를 통한 Catch2 통합","# 작업: FetchContent를 통한 Catch2 통합\n\n> **에픽**: 의존성 통합 프레임워크\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 설정 시간에 다운로드되는 의존성으로 Catch2 테스트 프레임워크를 통합합니다.\n- **근거**: 프로젝트의 테스트 스위트 구성 요소에 강력하고 널리 사용되는 테스트 프레임워크를 제공하기 위함입니다. CMake의 `FetchContent` 모듈을 사용하는 것이 선택된 통합 전략인데, 이는 Catch2가 개발 전용 의존성이기 때문입니다. 이 방법은 CMake 설정 단계(`cmake ..`)에서 라이브러리를 자동으로 다운로드하여, 이 템플릿의 핵심 목표인 제3자 코드로 프로젝트 소스 저장소를 불필요하게 늘리는 것을 방지합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: `FetchContent`를 사용하여 `Catch2::Catch2WithMain` 타겟을 사용 가능하게 만드는 Catch2용 `CMakeLists.txt` 파일.\n- **명세**:\n - 생성 파일: `dependencies/externals/catch2/CMakeLists.txt`\n - 사용된 CMake 함수: `add_external_package` (프로젝트별 유틸리티)\n - 주요 인자:\n - `REPOSITORY_URL`: `https://github.com/catchorg/Catch2.git`\n - `REPOSITORY_TAG`: `v3.8.1`\n - `LIBRARIES`: `catch2::catch2`\n - 제공되는 CMake 타겟: 이 스크립트는 `Catch2::Catch2` 및 `Catch2::Catch2WithMain` 라이브러리 타겟을 다른 프로젝트 타겟(예: 테스트 스위트)에서 링크할 수 있도록 합니다.\n\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── dependencies/\n# └── externals/\n# └── catch2/\n# └── CMakeLists.txt <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 빌드 시스템이 이 새로운 의존성 모듈을 처리하는 방법을 보여줍니다. 최상위 CMake 설정은 `dependencies` 디렉터리를 포함하고, 이는 다시 새로운 `catch2/CMakeLists.txt` 스크립트를 처리합니다. 이 스크립트는 `add_external_package` 함수를 호출하여 `FetchContent`를 사용해 Catch2 라이브러리를 다운로드하고 준비하며, 그 타겟들을 테스트 스위트에서 사용할 수 있도록 합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph 빌드 오케스트레이션\n TopLevelCMake[\"최상위 CMakeLists.txt\"] --> IncludeDependencies[\"dependencies 디렉터리 포함\"]\n end\n\n subgraph \"의존성 통합 (이 작업)\"\n IncludeDependencies --> Catch2CMakeLists[\"catch2/CMakeLists.txt 처리\"]\n Catch2CMakeLists --> AddExternalPackage[\"add_external_package 함수 호출\"]\n AddExternalPackage -- \"FetchContent 사용\" --> DownloadCatch2[\"Catch2 소스 다운로드\"]\n DownloadCatch2 --> PrepareTargets[\"Catch2::Catch2WithMain 타겟 준비\"]\n end\n\n subgraph \"테스트 스위트 (하위 소비자)\"\n TestSuite[\"테스트 스위트 타겟\"] -- \"다음을 상대로 링크\" --> PrepareTargets\n end\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 상세 구현은 섹션 3에 있습니다.\n\n- [ ] `dependencies/externals/catch2/` 디렉터리에 `CMakeLists.txt` 파일 생성.\n- [ ] Catch2 저장소 URL과 태그를 사용하여 `add_external_package` 호출.\n- [ ] `catch2::catch2` 라이브러리 타겟 명시.\n- [ ] Catch2 의존성을 제공하는 발견 가능한 모듈.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층적 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **의존성 관리 시스템**: 이 작업은 이 구성 요소 내에서 직접 구현됩니다. `FetchContent`를 통해 외부, 비-서브모듈 의존성을 통합하는 패턴을 수립합니다. 새로운 스크립트는 최상위 빌드 오케스트레이션에 의해 자동으로 발견되고 처리될 것입니다.\n - **모듈식 CMake 빌드 시스템**: 이 작업은 상위 수준의 `add_external_package` 유틸리티 함수를 사용하여 빌드 시스템의 계층적 아키텍처를 활용합니다. 이 함수는 `FetchContent`의 저수준 세부 사항을 추상화하여, 깨끗하고 선언적인 빌드 스크립트라는 프로젝트 원칙을 준수합니다.\n - **테스트 스위트**: 이 구성 요소는 결과물의 주요 소비자입니다. 이 작업으로 생성된 `Catch2::Catch2WithMain` 타겟은 테스트 실행 파일에 링크되어, 단위 및 통합 테스트에 Catch2 프레임워크를 사용할 수 있게 합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정될 것입니다.\n\n- `dependencies/externals/catch2/CMakeLists.txt`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공할 것입니다.\n\n---\n\n### 단계 1: `dependencies/externals/catch2/` 디렉터리에 `CMakeLists.txt` 파일 생성\n\n#### 1. 의존성 모듈 스크립트 생성\n\n이 액션은 Catch2를 프로젝트 의존성으로 정의할 CMake 스크립트를 생성하는 것을 포함합니다. 이 파일은 `dependencies/externals/catch2/`에 위치하여 주 빌드 시스템이 자동으로 발견하고 실행하여 의존성을 통합할 수 있도록 합니다.\n\n**파일**: `dependencies/externals/catch2/CMakeLists.txt`\n\n```cmake\n# 이 파일은 다음 액션들에서 채워질 것입니다.\n# 지금은 이 파일을 생성하고 비워두세요.\n```\n\n---\n\n### 단계 2: Catch2 저장소 URL과 태그를 사용하여 `add_external_package` 호출\n\n#### 1. 커스텀 유틸리티 모듈 포함\n\n프로젝트의 상위 수준 의존성 추가 함수를 사용하려면, 먼저 해당 함수가 정의된 CMake 파일을 포함해야 합니다. 이는 기본적인 유틸리티를 재사용함으로써 프로젝트의 모듈식 아키텍처를 준수합니다.\n\n**파일**: `dependencies/externals/catch2/CMakeLists.txt`\n\n```cmake\n# =============================================================================\n# 외부 패키지 추가: Catch2\n# =============================================================================\n# 이 스크립트는 Catch2 라이브러리를 외부 패키지로 추가합니다.\n\ninclude(${CMAKE_SOURCE_DIR}/cmake/library/add_external_package.cmake)\n```\n\n#### 2. `add_external_package`를 통해 FetchContent 설정\n\n이 액션은 스크립트에 핵심 로직을 추가합니다. `add_external_package` 함수는 CMake의 `FetchContent`를 감싸는 프로젝트별 래퍼입니다. `REPOSITORY_URL`로 Catch2 Git 저장소의 위치를 지정하고, `REPOSITORY_TAG`로 특정 버전에 의존성을 고정하여 결정적이고 반복 가능한 빌드를 보장하도록 호출됩니다. 이 단일 함수 호출은 외부 라이브러리의 다운로드, 설정 및 타겟 생성을 처리합니다.\n\n**파일**: `dependencies/externals/catch2/CMakeLists.txt`\n\n```cmake\n# ... (이전 액션의 include 문)\n\nadd_external_package(\n REPOSITORY_URL \"https://github.com/catchorg/Catch2.git\"\n REPOSITORY_TAG \"v3.8.1\"\n LIBRARIES catch2::catch2\n)\n```\n\n---\n\n### 단계 3: `catch2::catch2` 라이브러리 타겟 명시\n\n#### 1. 라이브러리 타겟 이름 명시\n\n이 액션은 이전 단계의 `add_external_package` 함수 호출 내에서 수행됩니다. `LIBRARIES` 인자에 `catch2::catch2` 값이 전달됩니다. 이는 Catch2 프로젝트 자체의 `CMakeLists.txt`에 정의된 라이브러리 타겟 중 어느 것을 우리 프로젝트에서 사용할 수 있게 할지를 유틸리티 함수에 알려줍니다. `add_external_package` 유틸리티는 이 타겟과 `Catch2::Catch2WithMain` 같은 관련 타겟들이 올바르게 임포트되어 링크할 수 있도록 보장합니다.\n\n**파일**: `dependencies/externals/catch2/CMakeLists.txt`\n\n```cmake\n# ...\n\nadd_external_package(\n # ...\n LIBRARIES catch2::catch2\n)\n```\n\n---\n\n### 단계 4: Catch2 의존성을 제공하는 발견 가능한 모듈\n\n#### 1. 발견 가능한 모듈 최종화\n\n`dependencies/externals/catch2/` 디렉터리에 `CMakeLists.txt` 파일을 생성하고 설명된 대로 내용을 채움으로써 모듈이 완성됩니다. 최상위 CMake 스크립트는 이미 `dependencies/externals/`의 하위 디렉터리를 순회하며 발견되는 모든 `CMakeLists.txt`를 실행하도록 설정되어 있습니다. 따라서 추가적인 조치는 필요 없으며, 모듈은 기존 빌드 시스템 아키텍처에 의해 본질적으로 발견 가능합니다. 최종적으로 완성된 파일은 모든 완료 조건에 대한 결과물 역할을 합니다.\n\n**파일**: `dependencies/externals/catch2/CMakeLists.txt`\n\n```cmake\n# =============================================================================\n# 외부 패키지 추가: Catch2\n# =============================================================================\n# 이 스크립트는 Catch2 라이브러리를 외부 패키지로 추가합니다.\n\ninclude(${CMAKE_SOURCE_DIR}/cmake/library/add_external_package.cmake)\n\nadd_external_package(\n REPOSITORY_URL \"https://github.com/catchorg/Catch2.git\"\n REPOSITORY_TAG \"v3.8.1\"\n LIBRARIES catch2::catch2\n)\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 구현을 검증하기 위해, 개발자는 프로젝트 설정 시 CMake가 Catch2 의존성을 성공적으로 다운로드하고 설정하는지 확인해야 합니다.\n\n```bash\n# 1. 프로젝트 루트에서 빌드 디렉터리를 생성하고 이동합니다.\nmkdir -p build && cd build\n\n# 2. CMake를 사용하여 프로젝트를 설정합니다. 이 과정에서 FetchContent가 트리거됩니다.\n# 출력에서 Catch2 관련 메시지를 관찰하세요.\ncmake ..\n\n# 3. FetchContent에 의해 Catch2 소스 코드가 다운로드되었는지 확인합니다.\n# 다음 명령어는 다운로드된 소스 디렉터리를 나열해야 합니다.\nls -d _deps/catch2-src\n```\n\n### 4.2. 예상 결과\n\n- `cmake ..` 명령어는 오류 없이 실행되어야 합니다. 출력에는 다음과 유사하게 `catch2`가 채워지고 있음을 나타내는 줄이 포함되어야 합니다:\n\n```\n-- Populating catch2\n-- Configuring done (0.2s)\n-- Generating done (0.0s)\n-- Build files have been written to: /path/to/project/build/_deps/catch2-build\n```\n\n- `ls -d _deps/catch2-src` 명령어는 성공적으로 실행되고 디렉터리 경로를 출력하여 소스 코드가 다운로드되었음을 확인해야 합니다.\n\n```\n_deps/catch2-src\n```\n","FetchContent를 사용하여 `Catch2::Catch2WithMain` 타겟을 사용할 수 있게 하는 Catch2용 `CMakeLists.txt`.",[1335,1337,1339,1341],{"_24":1336,"_83":39,"_84":320,"_85":61},"`dependencies/externals/catch2/` 내의 `CMakeLists.txt` 파일.",{"_24":1338,"_83":39,"_84":320,"_85":88},"Catch2 저장소 URL과 태그를 사용하여 `add_external_package` 호출.",{"_24":1340,"_83":39,"_84":320,"_85":91},"`catch2::catch2` 라이브러리 타겟 명시.",{"_24":1342,"_83":39,"_84":320,"_85":94},"Catch2 의존성을 제공하는 검색 가능한 모듈.","구성 시점에 다운로드되는 의존성으로 Catch2 테스트 프레임워크 통합.",{"_22":1345,"_24":1346,"_75":1347,"_77":1348,"_79":1349,"_51":1362,"_42":99},"task-1750999325299","메인 프로젝트 빌드 스크립트","# 작업: 메인 프로젝트 빌드 스크립트\n\n> **에픽**: 최상위 빌드 오케스트레이션\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 프로젝트 구조를 정의하고 빌드를 오케스트레이션하는 중앙 `CMakeLists.txt` 파일.\n- **근거**: 이 작업은 전체 빌드 시스템의 주 진입점을 구현하는 것입니다. \"계층적 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\" 아키텍처에 따라, 이 최상위 스크립트는 오케스트레이터 역할을 합니다. `cmake/interface` 모듈에서 제공하는 고수준 인터페이스 함수(예: `configure_library`, `configure_executable`)를 사용하여 모든 프로젝트 타겟을 선언적으로 정의합니다. 이는 상위 수준의 프로젝트 구조를 빌드의 하위 수준 구현 세부 사항과 분리하여 가독성과 유지보수성을 향상시킵니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 모든 모듈을 함께 묶어 최종 빌드 구성을 생성하는 최상위 `CMakeLists.txt`.\n- **명세**: 최종 `CMakeLists.txt` 파일은 다음 핵심 요소를 포함해야 합니다:\n - `cmake_minimum_required(VERSION 3.15)`\n - `project(example ...)`\n - `cmake/interface/`의 모든 모듈 포함\n - `configure_project()` 호출\n - `example` 정적 라이브러리를 생성하기 위한 `configure_library()` 호출.\n - `print_math_result` 실행 파일을 생성하기 위한 `configure_executable()` 호출.\n - `configure_tests()`를 통한 테스트 스위트의 조건부 포함.\n - 개발자 도구 타겟을 생성하기 위한 `configure_doxygen()`, `configure_formatter()`, `configure_static_analysis()` 호출.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── CMakeLists.txt <-- 수정됨\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 최상위 `CMakeLists.txt`에 의해 시작되는 오케스트레이션 흐름을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n Developer[\"개발자가 cmake 실행\"] --> TopLevelCMake[\"최상위 CMakeLists.txt\"];\n TopLevelCMake --> IncludeModules[\"cmake/interface/*.cmake 모듈 포함\"];\n IncludeModules --> CallConfigureProject[\"전역 설정을 위해 configure_project() 호출\"];\n CallConfigureProject --> CallConfigureLibrary[\"라이브러리 타겟 정의를 위해 configure_library() 호출\"];\n CallConfigureLibrary --> CallConfigureExecutable[\"실행 파일 타겟 정의를 위해 configure_executable() 호출\"];\n CallConfigureExecutable --> CallConfigureTools[\"configure_tests() 및 기타 도구 함수 호출\"];\n CallConfigureTools --> GenerateBuildSystem[\"빌드 시스템(예: Makefiles) 생성\"];\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] `cmake_minimum_required`와 `project()`를 사용한 프로젝트 정의.\n- [ ] 모든 상위 `cmake/interface` 모듈 포함.\n- [ ] 환경 설정을 위한 `configure_project` 호출.\n- [ ] 'example' 라이브러리 타겟 정의를 위한 `configure_library` 호출.\n- [ ] 주 실행 파일 정의를 위한 `configure_executable` 호출.\n- [ ] 테스팅 및 개발자 도구 타겟 구성을 위한 호출.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층적 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **모듈식 CMake 빌드 시스템**: 이 작업은 이 구성 요소의 최상위 오케스트레이션 계층을 구현합니다. `CMakeLists.txt` 파일은 다른 모든 상위 빌드 함수를 호출하는 주 진입점입니다.\n - **C++ 예제 라이브러리**: 최상위 스크립트는 이 라이브러리 구성 요소의 컴파일을 트리거하는 `configure_library`를 호출할 책임이 있습니다.\n - **테스트 스위트**: 이 스크립트는 조건부로 테스팅을 활성화하고 `configure_tests`를 호출하여 테스트 환경을 설정하고 모든 Catch2 테스트를 찾습니다.\n - **품질 보증 툴체인**: 이 스크립트는 각 `configure_*` 함수를 호출하여 이 툴체인을 위한 `make` 타겟(`format`, `static_analysis`, `create_documentations`)을 생성합니다.\n - **의존성 관리 시스템**: 이 스크립트는 실행 파일의 의존성으로 `spdlog`를 지정함으로써 이 시스템과 간접적으로 상호 작용하며, 기본 모듈이 라이브러리를 찾아 연결하도록 합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `CMakeLists.txt`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `Step`은 **완료 조건**의 항목에 해당합니다. 각 `Step`은 일련의 세부적인 `Action`으로 나뉩니다. 각 `Action`에 대해 제목, 명확한 서술적 설명('무엇'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공하게 됩니다.\n\n---\n\n### Step 1: `cmake_minimum_required`와 `project()`를 사용한 프로젝트 정의\n\n#### 1. 표준 프로젝트 속성 정의\n\n이 작업은 기본적인 프로젝트 메타데이터를 설정합니다. `cmake_minimum_required`는 최소 CMake 버전을 강제하여 호환성을 보장합니다. `project()` 명령어는 프로젝트 이름, 버전 및 기타 메타데이터를 정의하며, 이는 빌드 스크립트 전체에서 접근할 수 있습니다. `option()`은 개발자가 `cmake` 구성 단계에서 테스팅을 켜고 끌 수 있도록 정의됩니다.\n\n**파일**: `CMakeLists.txt`\n\n```cmake\n# =============================================================================\n# 프로젝트 구성\n# =============================================================================\n# --- CMake 버전\ncmake_minimum_required(VERSION 3.15)\n\n# --- 프로젝트 정의\nproject(\n example\n VERSION 1.0.0\n DESCRIPTION \"가독성 높은 코드에 중점을 둔 C++ 프로젝트 템플릿입니다.\"\n HOMEPAGE_URL \"https://github.com/movingChurch/readable-code-cpp-project-template\"\n)\n\n# --- 프로젝트 옵션\noption(ENABLE_TESTING \"테스팅 활성화\" ON)\n```\n\n---\n\n### Step 2: 모든 상위 `cmake/interface` 모듈 포함\n\n#### 1. 커스텀 모듈 경로 추가 및 인터페이스 모듈 포함\n\n이 작업은 프로젝트의 커스텀 CMake 함수를 최상위 스크립트에서 사용할 수 있도록 합니다. 먼저 `cmake/` 디렉토리를 `CMAKE_MODULE_PATH`에 추가하여 CMake의 `include()` 명령어가 모듈을 찾을 수 있게 합니다. 그런 다음 모든 상위 인터페이스 모듈의 목록을 정의하고 반복하여 각 모듈을 포함시킵니다. 이 접근 방식은 새 인터페이스를 목록에 추가하기만 하면 되므로 루프 로직을 변경할 필요 없이 깔끔하고 확장 가능합니다.\n\n**파일**: `CMakeLists.txt`\n\n```cmake\n# =============================================================================\n# 모듈 및 프로젝트 설정\n# =============================================================================\n# --- 커스텀 모듈 포함\nlist(APPEND CMAKE_MODULE_PATH \"${CMAKE_CURRENT_LIST_DIR}/cmake\")\n\nset(interface_modules\n configure_project\n configure_library\n configure_executable\n configure_doxygen\n configure_formatter\n configure_static_analysis\n configure_tests\n)\n\nforeach(module IN LISTS interface_modules)\n include(interface/${module})\nendforeach()\n```\n\n---\n\n### Step 3: 환경 설정을 위한 `configure_project` 호출\n\n#### 1. 프로젝트 전반의 구성 실행\n\n이 작업은 모든 타겟에 적용되는 전역 구성을 설정하는 `configure_project` 함수를 호출합니다. 여기에는 프로젝트 전반의 컴파일러 플래그(예: `-Wall`, `/W4`) 정의, C++ 표준(`cxx_std_20`) 설정, 공통 출력 디렉토리 설정이 포함됩니다. 이 로직을 단일 함수 호출로 중앙 집중화하면 최상위 스크립트가 깔끔하게 유지되고 계층적 아키텍처를 준수하게 됩니다.\n\n**파일**: `CMakeLists.txt`\n\n```cmake\n# --- 프로젝트 구성\n# 필수적인 프로젝트 전반의 구성을 설정합니다.\nconfigure_project(${PROJECT_NAME})\n```\n\n---\n\n### Step 4: 'example' 라이브러리 타겟 정의를 위한 `configure_library` 호출\n\n#### 1. 정적 라이브러리 타겟 정의 및 구성\n\n이 작업은 `example` 정적 라이브러리를 정의합니다. 라이브러리의 소스 파일은 목록 변수에 수집됩니다. 그런 다음 이 목록과 함께 `configure_library` 함수가 호출됩니다. 이 상위 함수는 라이브러리 타겟을 올바르게 정의하고 구성하는 데 필요한 모든 CMake 명령어(`add_library`, `target_include_directories`, `target_compile_features` 등)를 캡슐화합니다.\n\n**파일**: `CMakeLists.txt`\n\n```cmake\n# =============================================================================\n# 타겟 정의\n# =============================================================================\n# --- 라이브러리 추가\nset(source_files\n source/math/add.cpp\n source/math/subtract.cpp\n)\nset(library_dependencies \"\")\n\nconfigure_library(\n TYPE STATIC\n SOURCES ${source_files}\n DEPENDENCIES ${library_dependencies}\n)\n```\n\n---\n\n### Step 5: 주 실행 파일 정의를 위한 `configure_executable` 호출\n\n#### 1. 실행 파일 타겟 정의 및 구성\n\n이 작업은 주 실행 파일 타겟인 `print_math_result`를 정의합니다. `configure_executable` 함수는 주 소스 파일의 경로와 의존성 목록과 함께 호출됩니다. 이 경우 `spdlog`에 의존합니다. 이 함수는 실행 파일 타겟을 생성하고 내부 `example` 라이브러리와 외부 `spdlog` 의존성 모두에 대해 링크하는 세부 사항을 처리합니다.\n\n**파일**: `CMakeLists.txt`\n\n```cmake\n# --- 실행 파일 추가\nconfigure_executable(\n SOURCE executables/print_math_result.cpp\n DEPENDENCIES spdlog\n)\n```\n\n---\n\n### Step 6: 테스팅 및 개발자 도구 타겟 구성을 위한 호출\n\n#### 1. 테스트 스위트 구성\n\n이 작업은 프로젝트의 테스트 스위트를 설정합니다. 이전에 정의된 옵션을 존중하기 위해 `if(ENABLE_TESTING)` 블록으로 감싸져 있습니다. 활성화되면 `enable_testing()`이 프로젝트에 대한 CTest 지원을 활성화합니다. 그런 다음 `configure_tests` 함수가 호출되어 `tests/` 디렉토리 내의 모든 테스트 파일을 자동으로 찾고, 테스트 실행 파일을 생성하고, `example` 라이브러리 및 Catch2에 대해 링크하고, 코드 커버리지 보고를 구성합니다.\n\n**파일**: `CMakeLists.txt`\n\n```cmake\n# =============================================================================\n# 테스팅 및 도구\n# =============================================================================\n# --- 테스팅 구성\nif(ENABLE_TESTING)\n enable_testing()\n\n configure_tests(\n TEST_DIR \"${CMAKE_CURRENT_SOURCE_DIR}/tests\"\n ENABLE_COVERAGE ON\n FUNCTION_COVERAGE 100\n LINE_COVERAGE 90\n )\nendif()\n```\n\n#### 2. 개발자 도구 타겟 구성\n\n이 마지막 작업은 개발자 생산성을 위한 커스텀 `make` 타겟을 설정합니다. `configure_doxygen`, `configure_formatter`, `configure_static_analysis` 함수가 호출됩니다. 각 함수는 개발자가 단일 명령으로 코드베이스 전체에 해당 도구를 실행할 수 있도록 하는 커스텀 타겟(`create_documentations`, `format`, `static_analysis`)을 생성합니다.\n\n**파일**: `CMakeLists.txt`\n\n```cmake\n# --- 도구 구성\nconfigure_doxygen()\nconfigure_formatter()\nconfigure_static_analysis(SOURCES ${source_files})\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n개발자는 최상위 빌드 스크립트의 성공적인 구현을 검증하기 위해 프로젝트 루트 디렉토리에서 다음 셸 명령을 실행해야 합니다.\n\n```bash\n# 1. 이전 빌드 아티팩트 제거 (선택 사항, 깨끗한 테스트를 위해)\nrm -rf build/\n\n# 2. 빌드 디렉토리를 만들고 그 안으로 이동\nmkdir build && cd build\n\n# 3. CMake를 사용하여 프로젝트 구성\n# 이 단계는 CMakeLists.txt에 구문 오류가 있거나 모듈을 찾을 수 없는 경우 실패합니다.\ncmake ..\n\n# 4. 정의된 모든 타겟(라이브러리, 실행 파일, 테스트) 빌드\n# 이 단계는 컴파일 또는 링크 오류가 있는 경우 실패합니다.\nmake -j\n\n# 5. CTest를 사용하여 테스트 스위트 실행\n# 이는 테스트 타겟이 생성되고 올바르게 링크되었는지 확인합니다.\nctest --verbose\n\n# 6. 도구 타겟이 실행될 수 있는지 확인 (예: format)\n# 이는 커스텀 도구 타겟이 생성되었는지 확인합니다.\nmake format\n```\n\n### 4.2. 예상 결과\n\n- `cmake ..` 명령이 오류 없이 완료되고, 구성 정보를 출력하며 \"Build files have been written to: .../build\"로 끝납니다.\n- `make -j` 명령이 모든 타겟(`example`, `print_math_result`, `run_tests`)을 컴파일 및 링크하고 모두에 대해 `[100%] Built target ...`을 보고합니다.\n- `ctest --verbose` 명령이 모든 테스트가 통과했음을 보고합니다. 출력은 다음과 유사해야 합니다:\n\n```\n...\n1: Test command: /path/to/project/build/bin/run_tests\n1: Test timeout computed to be: 10000\n1: ===============================================================================\n1: All tests passed (X assertions in Y test cases)\n1/1 Test #1: RunUnitTests ....................... Passed 0.01 sec\n\n100% tests passed, 0 tests failed out of 1\n\nTotal Test time (real) = 0.02 sec\n```\n\n- `make format` 명령이 오류 없이 실행되며, 프로젝트의 C++ 파일에 대해 clang-format을 실행 중이라고 보고합니다.\n","모든 모듈을 통합하여 최종 빌드 구성을 생성하는 최상위 `CMakeLists.txt`.",[1350,1352,1354,1356,1358,1360],{"_24":1351,"_83":39,"_84":338,"_85":61},"`cmake_minimum_required` 및 `project()`를 사용한 프로젝트 정의.",{"_24":1353,"_83":39,"_84":338,"_85":88},"모든 고수준 `cmake/interface` 모듈 포함.",{"_24":1355,"_83":39,"_84":338,"_85":91},"환경 설정을 위한 `configure_project` 호출.",{"_24":1357,"_83":39,"_84":338,"_85":94},"'example' 라이브러리 타겟을 정의하기 위한 `configure_library` 호출.",{"_24":1359,"_83":39,"_84":338,"_85":97},"메인 실행 파일을 정의하기 위한 `configure_executable` 호출.",{"_24":1361,"_83":39,"_84":338,"_85":176},"테스트 및 개발자 도구 타겟 구성을 위한 호출.","프로젝트 구조를 정의하고 빌드를 총괄하는 중앙 `CMakeLists.txt` 파일.",{"_22":1364,"_24":1365,"_75":1366,"_77":1367,"_79":1368,"_51":1377,"_42":99},"task-1750999402076","정수 덧셈 기능","# 과제: 정수 덧셈 기능\n\n> **에픽**: 핵심 수학 라이브러리 구현\n\n## 1. 과제 정의\n\n### 1.1. 목표\n\n- **목표**: 두 정수의 합을 계산하는 함수.\n- **근거**: 이 과제는 프로젝트 내에서 새로운 라이브러리 구성 요소를 만드는 기본적인 패턴을 확립합니다. 이는 공개 API(`include/`의 헤더 파일)와 비공개 구현(`source/`의 소스 파일)을 분리하는 핵심 아키텍처 원칙을 보여줍니다. 이러한 모듈식 접근 방식은 `readable-code-cpp-project-template`의 핵심 목표인 유지보수 및 확장이 용이한 코드베이스를 만드는 데 필수적입니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: `Add` 함수를 구현하는 헤더 `add.hpp`와 소스 파일 `add.cpp`.\n- **명세**:\n - `함수 시그니처`: `auto Add(int lhs, int rhs) -> int`\n - `네임스페이스`: `example::math`\n - `헤더 가드`: `EXAMPLE_MATH_ADD_HPP`\n - `문서화`: 공개 함수 선언에는 Doxygen 주석 블록이 포함되어야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# ├── include/\n# │ └── example/\n# │ └── math/\n# │ └── add.hpp <-- 신규\n# └── source/\n# └── math/\n# └── add.cpp <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 클라이언트 구성 요소(예: 실행 파일 또는 테스트)가 빌드 시간과 실행 시간에 `Add` 함수를 어떻게 사용하는지 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph 빌드 시간\n Compiler[\"C++ 컴파일러\"]\n CMake[\"CMake 빌드 시스템\"]\n CMake -- \"에 대해 링크\" --> Lib[\"libexample_math.a\"]\n ClientSource[\"클라이언트 코드 (예: main.cpp)\"] -- \"#include \" --> Compiler\n AddCpp[\"source/math/add.cpp\"] -- \"컴파일\" --> Compiler\n Compiler -- \"에 대한 오브젝트 파일 생성\" --> Lib\n end\n \n subgraph 실행 시간\n Executable[\"실행 파일\"] -- \"함수 호출\" --> AddFunction[\"example::math::Add(a, b)\"]\n AddFunction -- \"합계 반환\" --> Executable\n end\n \n ClientSource --> Executable\n```\n\n### 1.3. 인수 기준\n\n개발자는 이 과제를 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] `include/example/math/add.hpp`에 함수 선언.\n- [ ] 함수 선언을 위한 Doxygen 주석 블록.\n- [ ] `source/math/add.cpp`에 함수 정의.\n- [ ] 두 정수의 합을 올바르게 반환하는 함수.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층적 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련된 주요 구성 요소**:\n - **C++ 예제 라이브러리**: 이 과제는 이 데모 라이브러리의 핵심 구성 요소를 직접 생성합니다. `Add` 함수는 라이브러리의 공개 API의 일부가 될 것입니다.\n - **모듈식 CMake 빌드 시스템**: 빌드 시스템은 새로운 `.hpp` 및 `.cpp` 파일을 찾아 컴파일하고 정적 라이브러리 대상(`example_math`)으로 링크하는 역할을 합니다.\n - **테스트 스위트**: 이 과제에서 구현되지는 않지만, `Add` 함수는 단위 테스트(`tests/unit/`)의 직접적인 의존성이 될 것이며, 단위 테스트는 이 함수의 정확성을 검증하기 위해 공개 헤더를 사용합니다.\n - **품질 보증 도구 체인**: 이 도구 체인의 일부로 구성된 Doxygen 도구는 `add.hpp`의 문서 주석을 파싱하여 API 문서를 생성합니다.\n\n### 2.2. 영향을 받는 파일\n\n이 과제를 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `include/example/math/add.hpp`\n- `source/math/add.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 기준**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 1단계: `include/example/math/add.hpp`에 함수 선언\n\n#### 1. 공개 API 헤더 파일 생성\n\n이 작업은 `Add` 기능에 대한 공개 인터페이스를 설정합니다. 파일은 C++ 네임스페이스 `example::math`를 반영하는 깔끔한 네임스페이스 디렉터리 구조를 유지하기 위해 `include/example/math/`에 위치합니다. 헤더 가드(`#ifndef`/`#define`/`#endif`)를 사용하는 것은 컴파일 중 다중 포함 오류를 방지하기 위한 표준 관행입니다.\n\n**파일**: `include/example/math/add.hpp`\n\n```cpp\n/**\n * @file add.hpp\n * @author movingChurch\n * @brief 정수 연산을 위한 add 함수를 선언합니다.\n * @version 0.1\n * @date 2025-06-27\n *\n * @copyright HolyGround (c) 2025\n *\n */\n#ifndef EXAMPLE_MATH_ADD_HPP\n#define EXAMPLE_MATH_ADD_HPP\n\nnamespace example::math {\n\n// 다음 작업에서 함수 선언이 여기에 추가될 것입니다.\n\n} // namespace example::math\n\n#endif // EXAMPLE_MATH_ADD_HPP\n```\n\n#### 2. `Add` 함수 선언\n\n이 작업은 헤더 파일에 함수 시그니처를 추가합니다. 이렇게 하면 이 헤더를 포함하는 코드베이스의 다른 모든 부분에서 함수를 볼 수 있게 됩니다. 후행 반환 형식 구문(`auto ... -> int`)은 현대 C++20 스타일과의 일관성을 위해 사용됩니다.\n\n**파일**: `include/example/math/add.hpp`\n\n```cpp\n...\nnamespace example::math {\n\n/**\n * @brief 두 정수의 합을 계산합니다.\n *\n * 이 함수는 두 정수를 입력으로 받아 그 합을 반환합니다. 이것은 간단한\n * 산술 연산입니다.\n *\n * @param lhs 첫 번째 정수.\n * @param rhs 두 번째 정수.\n * @return 두 정수의 합.\n */\nauto Add(int lhs, int rhs) -> int;\n\n} // namespace example::math\n...\n```\n\n---\n\n### 2단계: 함수 선언을 위한 Doxygen 주석 블록\n\n#### 1. 함수 선언에 Doxygen 문서 추가\n\n이 작업은 함수 선언 위에 형식화된 주석 블록을 추가합니다. 이 문서는 유지보수성에 매우 중요하며, Doxygen에 의해 자동으로 파싱되어 프로젝트의 API 문서를 생성합니다. 이는 프로젝트의 문서화 표준에 따라 함수의 목적, 매개변수 및 반환 값을 명확하게 지정합니다.\n\n**파일**: `include/example/math/add.hpp`\n\n```cpp\n...\nnamespace example::math {\n\n/**\n * @brief 두 정수의 합을 계산합니다.\n *\n * 이 함수는 두 정수를 입력으로 받아 그 합을 반환합니다. 이것은 간단한\n * 산술 연산입니다.\n *\n * @param lhs 첫 번째 정수.\n * @param rhs 두 번째 정수.\n * @return 두 정수의 합.\n */\nauto Add(int lhs, int rhs) -> int;\n\n} // namespace example::math\n...\n```\n\n---\n\n### 3단계: `source/math/add.cpp`에 함수 정의\n\n#### 1. 비공개 구현 소스 파일 생성\n\n이 작업은 해당 소스 파일을 생성합니다. 구현을 `source/` 디렉터리 아래의 `.cpp` 파일에 배치하는 것은 라이브러리 사용자로부터 구현 세부 정보를 숨기고, 컴파일 의존성을 줄이며, 빌드 시간을 개선하므로 핵심적인 아키텍처 원칙입니다. 첫 줄에는 공개 선언과 구현이 일치하도록 해당 헤더를 포함합니다.\n\n**파일**: `source/math/add.cpp`\n\n```cpp\n/**\n * @file add.cpp\n * @author movingChurch\n * @brief 정수 연산을 위한 add 함수를 구현합니다.\n * @version 0.1\n * @date 2025-06-27\n *\n * @copyright HolyGround (c) 2025\n *\n */\n#include \"example/math/add.hpp\"\n\nnamespace example::math {\n\n// 다음 작업에서 함수 정의가 여기에 추가될 것입니다.\n\n} // namespace example::math\n```\n\n---\n\n### 4단계: 두 정수의 합을 올바르게 반환하는 함수\n\n#### 1. `Add` 함수 구현 정의\n\n이 작업은 헤더에 선언된 `Add` 함수에 대한 구체적인 로직을 제공합니다. 함수는 선언과 일치하도록 `example::math` 네임스페이스 내에서 정의됩니다. 로직은 간단한 덧셈으로, 과제의 주요 목표를 달성합니다.\n\n**파일**: `source/math/add.cpp`\n\n```cpp\n...\n#include \"example/math/add.hpp\"\n\nnamespace example::math {\n\nauto Add(int lhs, int rhs) -> int { return lhs + rhs; }\n\n} // namespace example::math\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n과제를 검증하려면 새 코드가 `example_math` 라이브러리의 일부로 올바르게 컴파일되는지 확인하십시오. 이는 CMake로 프로젝트를 구성하고 빌드 명령을 실행하여 수행됩니다. 이는 함수를 실행하지는 않지만 빌드 시스템에 올바르게 통합되었는지 확인합니다.\n\n```bash\n# 1. CMake로 프로젝트를 구성하여 'build' 디렉터리를 생성합니다.\ncmake -S . -B build\n\n# 2. 프로젝트를 빌드합니다. 이 과정에서 add.cpp가 컴파일되고 라이브러리가 생성됩니다.\ncmake --build build\n```\n\n### 4.2. 예상 결과\n\n빌드 명령은 오류 없이 성공적으로 완료되어야 합니다. 출력에는 `add.cpp`가 컴파일되었고 `example_math` 정적 라이브러리가 생성되었음이 표시되어야 합니다.\n\n```\n[..%] Building CXX object source/CMakeFiles/example_math.dir/math/add.cpp.o\n[..%] Built target example_math\n...\n[100%] Built target print_math_result\n```\n","`Add` 함수를 구현하는 헤더 `add.hpp` 및 소스 파일 `add.cpp`.",[1369,1371,1373,1375],{"_24":1370,"_83":39,"_84":356,"_85":61},"`include/example/math/add.hpp`에 함수 선언.",{"_24":1372,"_83":39,"_84":356,"_85":88},"함수 선언을 위한 Doxygen 주석 블록.",{"_24":1374,"_83":39,"_84":356,"_85":91},"`source/math/add.cpp`에 함수 정의.",{"_24":1376,"_83":39,"_84":356,"_85":94},"두 정수의 합을 정확하게 반환하는 함수.","두 정수의 합을 계산하는 함수.",{"_22":1379,"_24":1380,"_75":1381,"_77":1382,"_79":1383,"_51":1391,"_42":99},"task-1750999452285","정수 뺄셈 기능","# 작업: 정수 뺄셈 기능\n\n> **에픽**: 핵심 수학 라이브러리 구현\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 두 정수 간의 차이를 계산하는 함수.\n- **근거**: 이 작업은 기본적인 산술 기능을 추가하여 `Core Math Library`를 확장합니다. 이 함수를 구현하면 공개 인터페이스(`include/`의 헤더)와 비공개 구현(`source/`의 소스 파일)을 분리하는 프로젝트의 아키텍처 패턴이 강화됩니다. 이러한 모듈식 접근 방식은 유지보수 및 확장이 용이한 코드베이스를 만드는 데 필수적이며, 이는 이 C++ 프로젝트 템플릿의 핵심 목표입니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: `Subtract` 함수를 구현하는 헤더 `subtract.hpp`와 소스 파일 `subtract.cpp`.\n- **명세**:\n - 공개 함수 시그니처: `auto Subtract(int lhs, int rhs) -> int`\n - 함수는 `example::math` 네임스페이스 내에 있어야 합니다.\n - 공개 헤더 파일은 함수 선언을 위한 Doxygen 주석 블록을 포함해야 합니다.\n - 헤더 파일은 표준 인클루드 가드를 포함해야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# ├── include/\n# │ └── example/\n# │ └── math/\n# │ └── subtract.hpp <-- 신규\n# └── source/\n# └── math/\n# └── subtract.cpp <-- 신규\n```\n\n- **프로세스 흐름도**\n이 다이어그램은 입력 정수를 출력 정수로 변환하는 순수 함수인 `Subtract` 함수의 데이터 흐름을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"함수: example::math::Subtract\"\n InputA[입력: int lhs]\n InputB[입력: int rhs]\n \n Operation{\"뺄셈 수행
(lhs - rhs)\"}\n \n Output[출력: int result]\n end\n\n InputA --> Operation\n InputB --> Operation\n Operation --> Output\n```\n\n### 1.3. 인수 기준\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] `include/example/math/subtract.hpp`에 함수 선언.\n- [ ] 함수 선언을 위한 Doxygen 주석 블록.\n- [ ] `source/math/subtract.cpp`에 함수 정의.\n- [ ] 두 정수의 차를 정확하게 반환하는 함수.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층형 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **C++ 예제 라이브러리**: 이 작업은 새로운 기능을 추가하여 이 구성 요소를 직접 수정합니다. 새로운 소스 및 헤더 파일은 빌드 시스템에 의해 정의된 정적 라이브러리 대상의 일부가 됩니다.\n - **모듈식 CMake 빌드 시스템**: 이 구성 요소는 새로운 `.cpp` 및 `.hpp` 파일을 발견하고 이를 `example_lib` 정적 라이브러리 대상으로 컴파일하는 역할을 합니다. 개발자는 CMake 파일을 직접 수정할 필요가 없습니다. 시스템이 `source/` 및 `include/` 디렉토리의 새 파일을 자동으로 처리하도록 설계되었기 때문입니다.\n - **테스트 스위트**: 이 작업에서 수정되지는 않지만, `테스트 스위트` 구성 요소는 나중에 단위 및 통합 테스트를 수행하기 위해 `Subtract` 함수의 공개 인터페이스를 사용하게 됩니다.\n - **품질 보증 툴체인**: 새로운 C++ 코드는 이 구성 요소의 도구(`clang-format`, `clang-tidy`)에 의해 시행되는 프로젝트의 코딩 표준을 준수해야 합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `include/example/math/subtract.hpp`\n- `source/math/subtract.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계(Step)`는 **인수 기준**의 항목에 해당합니다. 각 `단계`는 일련의 세부 `조치(Action)`로 나뉩니다. 각 `조치`에 대해 제목, 명확한 서술적 설명('무엇'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `include/example/math/subtract.hpp`에 함수 선언\n\n#### 1. 공개 헤더 파일 생성\n\n이 조치는 `Subtract` 기능에 대한 공개 계약을 설정합니다. 헤더 파일은 실행 파일이나 테스트 스위트와 같은 프로젝트의 다른 구성 요소에서 접근할 수 있도록 `include/example/math/`에 위치합니다. 컴파일 중 다중 포함 오류를 방지하기 위해 표준 헤더 가드(`#ifndef`/`#define`/`#endif`)를 사용합니다. 함수는 논리적 그룹화를 유지하고 이름 충돌을 피하기 위해 `example::math` 네임스페이스 내에 선언됩니다.\n\n**파일**: `include/example/math/subtract.hpp`\n\n```cpp\n/**\n * @file subtract.hpp\n * @author movingChurch\n * @brief 정수 연산을 위한 Subtract 함수를 선언합니다.\n * @version 0.1\n * @date 2025-06-27\n *\n * @copyright HolyGround (c) 2025\n *\n */\n#ifndef EXAMPLE_MATH_SUBTRACT_HPP\n#define EXAMPLE_MATH_SUBTRACT_HPP\n\nnamespace example::math {\n\n/**\n * @brief 두 정수 간의 차이를 계산합니다.\n *\n * @param lhs 뺄셈을 당하는 정수.\n * @param rhs 빼는 정수.\n * @return 두 정수 간의 차이.\n */\nauto Subtract(int lhs, int rhs) -> int;\n\n} // namespace example::math\n\n#endif // EXAMPLE_MATH_SUBTRACT_HPP\n```\n\n---\n\n### 단계 2: 함수 선언을 위한 Doxygen 주석 블록\n\n#### 1. 함수 선언에 Doxygen 문서 추가\n\n이 조치는 프로젝트의 문서화 표준을 충족시킵니다. Doxygen 주석 블록은 공개 헤더 파일의 함수 선언 바로 위에 추가됩니다. 이것은 `품질 보증 툴체인`이 API 문서를 자동으로 생성하는 데 중요합니다. 주석은 함수의 목적(`@brief`), 매개변수(`@param`), 그리고 반환 값(`@return`)을 명확하게 명시하여 인터페이스가 자체적으로 문서화되도록 합니다.\n\n**파일**: `include/example/math/subtract.hpp`\n\n```cpp\n...\nnamespace example::math {\n\n/**\n * @brief 두 정수 간의 차이를 계산합니다.\n *\n * @param lhs 뺄셈을 당하는 정수.\n * @param rhs 빼는 정수.\n * @return 두 정수 간의 차이.\n */\nauto Subtract(int lhs, int rhs) -> int;\n\n} // namespace example::math\n...\n```\n\n---\n\n### 단계 3: `source/math/subtract.cpp`에 함수 정의\n\n#### 1. 비공개 구현 파일 생성\n\n이 조치는 선언된 함수에 대한 구체적인 구현을 제공합니다. 소스 파일은 인터페이스와 구현을 분리하는 프로젝트의 디렉토리 구조에 맞춰 `source/math/`에 위치합니다. 함수 시그니처가 선언과 일치하도록 해당 헤더 `example/math/subtract.hpp`를 포함합니다. 함수는 헤더와 일관되게 `example::math` 네임스페이스 내에서 정의됩니다.\n\n**파일**: `source/math/subtract.cpp`\n\n```cpp\n/**\n * @file subtract.cpp\n * @author movingChurch\n * @brief 정수 연산을 위한 Subtract 함수를 구현합니다.\n * @version 0.1\n * @date 2025-06-27\n *\n * @copyright HolyGround (c) 2025\n *\n */\n#include \"example/math/subtract.hpp\"\n\nnamespace example::math {\n\nauto Subtract(int lhs, int rhs) -> int { return lhs - rhs; }\n\n} // namespace example::math\n```\n\n---\n\n### 단계 4: 두 정수의 차를 정확하게 반환하는 함수\n\n#### 1. 뺄셈 로직 구현\n\n이 조치는 함수의 핵심 비즈니스 로직을 구현합니다. `Subtract` 함수의 본문은 산술 연산 `lhs - rhs`를 수행하고 결과를 반환하도록 정의됩니다. 이것으로 목표에 명시된 기능이 완성됩니다. 구현은 간단하며 함수 본문 내에 독립적으로 포함됩니다.\n\n**파일**: `source/math/subtract.cpp`\n\n```cpp\n...\nnamespace example::math {\n\nauto Subtract(int lhs, int rhs) -> int { return lhs - rhs; }\n\n} // namespace example::math\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n이 작업의 기본 검증은 새 파일이 CMake 빌드 시스템에 의해 `example_lib` 정적 라이브러리로 올바르게 컴파일되는지 확인하는 것입니다. 전체 기능 검증은 단위 테스트가 작성되는 후속 작업에서 수행됩니다.\n\n```bash\n# 1. 빌드 디렉토리로 이동합니다 (없으면 생성).\nmkdir -p build && cd build\n\n# 2. CMake를 사용하여 프로젝트를 구성합니다.\n# 이 단계에서 새로운 소스 파일을 발견합니다.\ncmake ..\n\n# 3. 생성된 빌드 시스템(예: Make)을 사용하여 프로젝트를 빌드합니다.\n# 이 과정에서 subtract.cpp를 컴파일하고 라이브러리에 링크합니다.\nmake\n\n# 4. (선택 사항) 라이브러리를 검사하여 객체 파일이 포함되었는지 확인합니다.\n# 특정 명령어는 운영 체제에 따라 다를 수 있습니다 (예: Linux에서 `ar -t`).\n# Linux/macOS 예시:\nar -t lib/libexample_lib.a | grep subtract\n\n# Windows 예시 (lib.exe 사용):\n# lib.exe /LIST lib\\example_lib.lib | findstr subtract\n```\n\n### 4.2. 예상 결과\n\n`make` 명령어는 종료 코드 `0`으로 성공적으로 완료되어야 합니다. 출력은 `subtract.cpp`가 컴파일되었고 `example_lib` 대상이 빌드되었음을 나타내야 합니다.\n\n```\n[ XX%] Building CXX object source/CMakeFiles/example_lib.dir/math/subtract.cpp.o\n...\n[ XX%] Built target example_lib\n...\n[100%] Built target print_math_result\n```\n\n선택 사항인 `ar` 명령어는 정적 라이브러리 아카이브에 포함되었음을 확인하는 객체 파일의 이름을 출력해야 합니다.\n\n```\nsubtract.cpp.o\n```\n","`Subtract` 함수를 구현하는 헤더 `subtract.hpp` 및 소스 파일 `subtract.cpp`.",[1384,1386,1387,1389],{"_24":1385,"_83":39,"_84":374,"_85":61},"`include/example/math/subtract.hpp`에 함수 선언.",{"_24":1372,"_83":39,"_84":374,"_85":88},{"_24":1388,"_83":39,"_84":374,"_85":91},"`source/math/subtract.cpp`에 함수 정의.",{"_24":1390,"_83":39,"_84":374,"_85":94},"두 정수의 차를 정확하게 반환하는 함수.","두 정수의 차를 계산하는 함수.",{"_22":1393,"_24":1394,"_75":1395,"_77":1396,"_79":1397,"_51":1408,"_42":99},"task-1750999504641","수학 라이브러리 데모 실행 파일","# 과제: 수학 라이브러리 시연 실행 파일\n\n> **에픽**: 예제 애플리케이션 실행 파일\n\n## 1. 과제 정의\n\n### 1.1. 목표\n\n- **목표**: 핵심 수학 라이브러리와 로깅 사용법을 시연하는 애플리케이션.\n- **근거**: 이 과제는 빌드 시스템에 대한 중요한 통합 테스트 역할을 합니다. `모듈식 CMake 빌드 시스템`이 실행 파일 타겟을 내부 프로젝트 라이브러리(`example-math`)와 외부 종속성(`spdlog`) 모두에 대해 올바르게 링크할 수 있는지 검증합니다. 또한, 개발자에게 프로젝트의 핵심 라이브러리를 사용하는 방법에 대한 명확하고 컴파일 가능한 예제를 제공합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 실행 파일로 컴파일되는 `print_math_result.cpp` 소스 파일.\n- **사양**:\n - 소스 파일은 `example/math/add.hpp`, `example/math/subtract.hpp`, `spdlog/spdlog.h`를 포함해야 합니다.\n - 실행 파일 진입점은 `auto main() -> int`여야 합니다.\n - 코드는 `example::math::Add(10, 5)`를 호출해야 합니다.\n - 코드는 `example::math::Subtract(10, 5)`를 호출해야 합니다.\n - 두 연산의 결과는 `spdlog::info`를 사용하여 콘솔에 기록되어야 합니다.\n- **결과 파일 구조**\n\n```bash\n./\n└── executables/\n └── print_math_result.cpp <-- 신규\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"실행 파일 실행\"\n A[\"main() 진입점\"] --> B[\"example::math::Add(10, 5) 호출\"];\n B --> C[\"spdlog::info로 덧셈 결과 로그 기록\"];\n C --> D[\"example::math::Subtract(10, 5) 호출\"];\n D --> E[\"spdlog::info로 뺄셈 결과 로그 기록\"];\n E --> F[\"0 반환\"];\n end\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 과제를 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] `add.hpp`, `subtract.hpp`, `spdlog.h` 포함.\n- [ ] 진입점으로서의 `main` 함수.\n- [ ] 샘플 값으로 `example::math::Add` 호출.\n- [ ] 샘플 값으로 `example::math::Subtract` 호출.\n- [ ] 콘솔에 결과를 출력하기 위해 `spdlog::info` 사용.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층형 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **C++ 예제 라이브러리**: 이 구성 요소는 핵심 `Add` 및 `Subtract` 함수를 제공합니다. 이 과제는 이 라이브러리의 사용법을 시연하기 위해 공개 API(`include/example/math/*.hpp`)를 직접 사용합니다.\n - **의존성 관리 시스템**: 이 구성 요소는 `spdlog` 라이브러리를 링크 가능한 CMake 타겟으로 제공합니다. 이 과제는 이 시스템을 사용하여 `spdlog/spdlog.h` 포함을 해결하고 로깅 기능을 위해 라이브러리에 링크합니다.\n - **모듈식 CMake 빌드 시스템**: 이 구성 요소는 `print_math_result.cpp`를 컴파일하고 C++ 예제 라이브러리 및 spdlog 라이브러리와 링크하여 최종 실행 바이너리를 생성하는 역할을 합니다.\n\n### 2.2. 영향받는 파일\n\n이 과제를 완료하기 위해 다음 파일들이 생성되거나 수정됩니다.\n\n- `executables/print_math_result.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부적인 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `add.hpp`, `subtract.hpp`, `spdlog.h` 포함\n\n#### 1. 필요한 헤더 포함\n\n이 액션은 필요한 헤더 파일들을 소스 파일의 최상단에 추가합니다. `example/math/add.hpp`와 `example/math/subtract.hpp`는 내부 수학 라이브러리 함수들의 선언을 제공합니다. `spdlog/spdlog.h`는 외부 로깅 라이브러리의 선언을 제공합니다. 이는 컴파일러가 파일의 뒷부분에서 사용되는 함수들을 인식하는 데 필수적입니다.\n\n**파일**: `executables/print_math_result.cpp`\n\n```cpp\n/**\n * @file print_math_result.cpp\n * @author movingChurch\n * @brief Demonstrates the use of the Add and Subtract functions.\n * @version 0.1\n * @date 2025-06-27\n *\n * @copyright HolyGround (c) 2025\n *\n */\n#include \"example/math/add.hpp\"\n#include \"example/math/subtract.hpp\"\n#include \"spdlog/spdlog.h\"\n\n// ...\n```\n\n---\n\n### 단계 2: 진입점으로서의 `main` 함수\n\n#### 1. `main` 함수 정의\n\n이 액션은 모든 C++ 실행 파일의 필수 진입점인 `main` 함수를 생성합니다. `auto main() -> int` 시그니처는 최신 C++ 스타일과의 일관성을 위해 사용되며, 함수가 정수 종료 코드를 반환함을 명확히 나타냅니다. 함수의 목적을 문서화하기 위해 Doxygen 주석 블록이 추가됩니다.\n\n**파일**: `executables/print_math_result.cpp`\n\n```cpp\n// ...\n\n/**\n * @brief Main entry point of the program.\n *\n * This function calls the Add and Subtract functions with sample values and\n * prints the results to the standard output using the spdlog library.\n *\n * @return int Returns 0 upon successful execution.\n */\nauto main() -> int {\n // ...\n return 0;\n}\n```\n\n---\n\n### 단계 3: 샘플 값으로 `example::math::Add` 호출\n\n#### 1. 덧셈 결과 실행 및 저장\n\n이 액션은 `example::math` 네임스페이스의 `Add` 함수를 정수 리터럴 `10`과 `5`로 호출합니다. 이는 프로젝트의 내부 정적 라이브러리에서 함수를 호출하는 방법을 보여줍니다. 결과는 불변성과 타입 안정성을 보장하기 위해 `const int`에 저장됩니다.\n\n**파일**: `executables/print_math_result.cpp`\n\n```cpp\n// ...\nauto main() -> int {\n const int AddResult = example::math::Add(10, 5);\n // ...\n return 0;\n}\n```\n\n---\n\n### 단계 4: 샘플 값으로 `example::math::Subtract` 호출\n\n#### 1. 뺄셈 결과 실행 및 저장\n\n이 액션은 `example::math` 네임스페이스의 `Subtract` 함수를 동일한 정수 리터럴로 호출합니다. 이는 수학 라이브러리의 사용법을 추가로 보여줍니다. 결과는 별도의 `const int` 변수에 저장됩니다.\n\n**파일**: `executables/print_math_result.cpp`\n\n```cpp\n// ...\nauto main() -> int {\n const int AddResult = example::math::Add(10, 5);\n // ...\n const int SubtractResult = example::math::Subtract(10, 5);\n // ...\n return 0;\n}\n```\n\n---\n\n### 단계 5: 콘솔에 결과를 출력하기 위해 `spdlog::info` 사용\n\n#### 1. 덧셈 및 뺄셈 결과 로그 기록\n\n이 액션은 `spdlog::info` 함수를 사용하여 수학 연산의 결과를 콘솔에 출력합니다. 이는 외부 `spdlog` 의존성이 올바르게 링크되어 사용 가능한지 검증합니다. 형식 문자열의 `{}` 플레이스홀더는 안전하고 효율적인 인자 포매팅을 위한 `spdlog` API의 일부입니다. 각 결과를 명확하게 기록하기 위해 두 번의 개별 호출이 이루어집니다.\n\n**파일**: `executables/print_math_result.cpp`\n\n```cpp\n// ...\nauto main() -> int {\n const int AddResult = example::math::Add(10, 5);\n spdlog::info(\"10 + 5 = {}\", AddResult);\n\n const int SubtractResult = example::math::Subtract(10, 5);\n spdlog::info(\"10 - 5 = {}\", SubtractResult);\n\n return 0;\n}\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n구현을 검증하려면, 프로젝트를 빌드하고 빌드 디렉터리에서 결과 실행 파일을 실행하십시오.\n\n```bash\n# 1. 빌드 디렉터리를 생성하고 이동합니다\nmkdir -p build && cd build\n\n# 2. CMake를 사용하여 프로젝트를 구성합니다\ncmake ..\n\n# 3. 프로젝트를 컴파일합니다 (예: Make 사용)\nmake\n\n# 4. 시연용 바이너리를 실행합니다\n./bin/print_math_result\n```\n\n### 4.2. 예상 결과\n\n검증 단계를 성공적으로 실행하면 콘솔에 출력이 생성됩니다. 로그 메시지에는 산술 연산의 정확한 결과가 포함되어야 합니다. 타임스탬프와 로그 레벨은 기본 `spdlog` 형식의 일부입니다.\n\n```\n[2025-06-27 10:00:00.000] [info] 10 + 5 = 15\n[2025-06-27 10:00:00.000] [info] 10 - 5 = 5\n```\n\n*참고: 타임스탬프는 실제 실행 시간을 반영합니다.*\n","실행 파일로 컴파일되는 `print_math_result.cpp` 소스 파일.",[1398,1400,1402,1404,1406],{"_24":1399,"_83":39,"_84":392,"_85":61},"`add.hpp`, `subtract.hpp`, `spdlog.h` 포함.",{"_24":1401,"_83":39,"_84":392,"_85":88},"진입점으로서의 `main` 함수.",{"_24":1403,"_83":39,"_84":392,"_85":91},"샘플 값을 사용한 `example::math::Add` 호출.",{"_24":1405,"_83":39,"_84":392,"_85":94},"샘플 값을 사용한 `example::math::Subtract` 호출.",{"_24":1407,"_83":39,"_84":392,"_85":97},"결과를 콘솔에 출력하기 위한 `spdlog::info` 사용.","핵심 수학 라이브러리 및 로깅 사용법을 시연하는 애플리케이션.",{"_22":1410,"_24":1411,"_75":1412,"_77":1413,"_79":1414,"_51":1423,"_42":99},"task-1750999572004","Add 함수를 위한 단위 테스트","# 작업: Add 함수에 대한 단위 테스트\n\n> **에픽**: 테스트 스위트 및 코드 커버리지\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: `Add` 함수의 정확성을 검증하기 위한 테스트 스위트.\n- **근거**: `example::math::Add` 함수가 다양한 조건에서 예상대로 동작하는지 확인하고, 향후의 회귀(regression)를 방지하며, 높은 코드 품질을 유지하기 위함입니다. 이 작업은 프로젝트의 자동화된 품질 보증 전략의 기초적인 부분이며, C++ 예제 라이브러리의 견고성에 직접적으로 기여합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 덧셈에 대한 Catch2 테스트 케이스를 포함하는 `tests/unit/math/add.cpp` 파일.\n- **명세**:\n - 테스트는 Catch2 프레임워크를 사용하여 구현됩니다.\n - `TEST_CASE` 매크로를 사용하여 테스트 시나리오를 정의합니다.\n - 테스트는 단언(assertion)을 위해 `REQUIRE` 매크로를 사용해야 합니다.\n - 핵심 단언은 `REQUIRE(example::math::Add(a, b) == a + b)`가 될 것입니다.\n - 테스트는 명확성을 위해 준비-실행-검증(Arrange-Act-Assert, AAA) 패턴을 사용합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── tests/\n# └── unit/\n# └── math/\n# └── add.cpp <-- New\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 단위 테스트 실행 시의 흐름을 보여줍니다. 이 프로세스는 개발자가 CTest를 통해 시작하며, CTest는 컴파일된 테스트 바이너리를 실행합니다. 해당 바이너리 내의 Catch2 프레임워크는 특정 테스트 케이스를 실행하고, 라이브러리 코드를 호출하여 그 출력을 단언합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph 테스트 실행 환경\n CTest[\"CTest 테스트 드라이버\"]\n TestBinary[\"테스트 실행 파일
(예: 'unit_tests')\"]\n Catch2[\"Catch2 프레임워크\"]\n end\n\n subgraph 코어 라이브러리\n AddFunction[\"example::math::Add(a, b)\"]\n end\n\n Developer -- \"'ctest' 실행\" --> CTest\n CTest -- \"실행\" --> TestBinary\n TestBinary -- \"호출\" --> Catch2\n Catch2 -- \"[add] TEST_CASE 실행\" --> AddFunction\n AddFunction -- \"결과 반환\" --> Catch2\n Catch2 -- \"결과의 정확성 단언\" --> Catch2\n Catch2 -- \"성공/실패 보고\" --> CTest\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이는 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] 덧셈을 위한 `TEST_CASE`.\n- [ ] 포괄적인 테스트를 위한 무작위 입력 사용.\n- [ ] `example::math::Add(a, b)`가 `a + b`와 같다는 단언.\n- [ ] AAA 패턴을 따르는 테스트 케이스.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층화된 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **테스트 스위트**: 이 작업은 테스트 스위트 구성 요소의 핵심 부분을 직접 구현합니다. 그 책임은 Catch2를 사용하여 라이브러리 코드의 정확성을 검증하는 것입니다. 이 새로운 테스트는 CTest에 의해 자동으로 발견되고 실행될 것입니다.\n - **C++ 예제 라이브러리**: 이 테스트는 `include/example/math/add.hpp`에 선언된 `example::math::Add` 함수와 같은 이 구성 요소의 공개 인터페이스를 사용하여 그 구현을 검증합니다.\n - **모듈식 CMake 빌드 시스템**: 빌드 시스템은 이 테스트 소스 파일을 테스트 실행 파일로 컴파일하고 이를 CTest와 통합하는 역할을 합니다. 상위 수준의 `configure_tests` 함수가 이 프로세스를 관리할 것입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `tests/unit/math/add.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부적인 `조치`로 나뉩니다. 각 `조치`에 대해 제목, 명확한 서술적 설명('무엇'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 덧셈을 위한 `TEST_CASE`\n\n#### 1. 테스트 케이스 구조 정의\n\n이 조치는 단위 테스트의 기본 구조를 설정합니다. Catch2의 `TEST_CASE` 매크로를 사용하여 새로운 테스트 시나리오를 정의합니다. 여기에는 테스트에 대한 설명적인 이름과 분류를 위한 태그 집합(예: `[unit]`, `[math]`) 두 개의 인수가 필요합니다. 또한 필요한 헤더인 테스트 프레임워크를 위한 `catch2/catch_test_macros.hpp`와 테스트 대상 함수에 접근하기 위한 `example/math/add.hpp`를 포함할 것입니다.\n\n**파일**: `tests/unit/math/add.cpp`\n\n```cpp\n#include \"example/math/add.hpp\"\n\n#include \n\n// ... other includes will go here\n\nTEST_CASE(\"Add function with random numbers\", \"[unit][math][add]\") {\n // Test implementation will go here\n}\n```\n\n---\n\n### 단계 2: 포괄적인 테스트를 위한 무작위 입력 사용\n\n#### 1. 무작위 테스트 데이터 생성 구현\n\n이 조치는 테스트의 '준비(Arrange)' 단계를 구현합니다. `Add` 함수의 견고성을 보장하기 위해, 몇 개의 정적인 값이 아닌 광범위한 입력에 대해 테스트합니다. C++ `` 라이브러리를 사용하여 정의된 범위 내에서 일련의 무작위 정수를 생성합니다. 이 설정은 `TEST_CASE` 블록 내에 배치됩니다.\n\n**파일**: `tests/unit/math/add.cpp`\n\n```cpp\n// ... includes\n#include \n\nTEST_CASE(\"Add function with random numbers\", \"[unit][math][add]\") {\n // Arrange\n constexpr int kNumIterations = 100;\n constexpr int kRange = 10000;\n std::random_device random_device;\n std::mt19937 generator(random_device());\n std::uniform_int_distribution<> distribution(-kRange, kRange);\n\n for (int i = 0; i < kNumIterations; ++i) {\n const int FirstNumber = distribution(generator);\n const int SecondNumber = distribution(generator);\n\n // Act and Assert will go here\n }\n}\n```\n\n---\n\n### 단계 3: `example::math::Add(a, b)`가 `a + b`와 같다는 단언\n\n#### 1. 함수 실행 및 정확성 단언\n\n이 조치는 테스트 루프 내에서 '실행(Act)' 및 '검증(Assert)' 단계를 구현합니다. 생성된 각 무작위 숫자 쌍에 대해, 먼저 표준 `+` 연산자를 사용하여 예상 결과를 계산합니다. 그런 다음, 동일한 숫자로 `example::math::Add` 함수를 호출합니다(실행). 마지막으로, Catch2의 `REQUIRE` 매크로를 사용하여 우리 함수의 실제 결과가 예상 결과와 일치하는지 확인합니다(검증). 만약 일치하지 않으면 Catch2는 테스트를 실패시킬 것입니다.\n\n**파일**: `tests/unit/math/add.cpp`\n\n```cpp\n// ... inside the for loop\n const int ExpectedResult = FirstNumber + SecondNumber;\n\n // Act\n const int ActualResult = example::math::Add(FirstNumber, SecondNumber);\n\n // Assert\n REQUIRE(ActualResult == ExpectedResult);\n// ...\n```\n\n---\n\n### 단계 4: AAA 패턴을 따르는 테스트 케이스\n\n#### 1. AAA 패턴 주석으로 테스트 최종화\n\n이 조치는 최종 코드가 준비-실행-검증(AAA) 패턴에 따라 명확하게 구조화되도록 보장합니다. 이는 루프 내에서 테스트 로직의 세 가지 개별 단계를 구분하기 위해 주석을 추가함으로써 달성됩니다. 이는 가독성과 유지보수성을 향상시켜 다른 개발자들이 테스트의 목적을 즉시 명확하게 파악할 수 있도록 합니다. 이 단계는 이전의 모든 조치를 최종적이고 완전한 구현으로 통합합니다.\n\n**파일**: `tests/unit/math/add.cpp`\n\n```cpp\n/**\n * @file add.cpp\n * @author movingChurch\n * @brief Unit tests for the Add function.\n * @version 0.2\n * @date 2025-06-27\n *\n * @copyright HolyGround (c) 2025\n *\n */\n#include \"example/math/add.hpp\"\n\n#include \n\n#include \n\nTEST_CASE(\"Add function with random numbers\", \"[unit][math][add]\") {\n // Arrange\n constexpr int kNumIterations = 100;\n constexpr int kRange = 10000;\n std::random_device random_device;\n std::mt19937 generator(random_device());\n std::uniform_int_distribution<> distribution(-kRange, kRange);\n\n for (int i = 0; i < kNumIterations; ++i) {\n const int FirstNumber = distribution(generator);\n const int SecondNumber = distribution(generator);\n const int ExpectedResult = FirstNumber + SecondNumber;\n\n // Act\n const int ActualResult = example::math::Add(FirstNumber, SecondNumber);\n\n // Assert\n REQUIRE(ActualResult == ExpectedResult);\n }\n}\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n- 개발자는 빌드를 구성하고, 코드를 컴파일하며, 테스트를 실행하기 위해 프로젝트의 루트 디렉터리에서 다음 명령을 실행해야 합니다.\n\n```bash\n# 1. 'build' 디렉터리에서 CMake 프로젝트를 구성합니다.\n# Debug 빌드 타입을 사용하여 테스트를 활성화합니다.\ncmake -S . -B build -DCMAKE_BUILD_TYPE=Debug\n\n# 2. 테스트 실행 파일을 포함한 모든 타겟을 빌드합니다.\ncmake --build build\n\n# 3. build 디렉터리로 변경합니다.\ncd build\n\n# 4. CTest를 사용하여 테스트 스위트를 실행합니다. --verbose 플래그는 상세한 출력을 제공합니다.\nctest --verbose\n```\n\n### 4.2. 예상 결과\n\n- `ctest --verbose`를 실행한 후, 출력은 모든 테스트가 통과했음을 나타내야 합니다. `Add` 함수에 대한 특정 테스트 케이스가 목록에 표시되고 `Passed`로 표시되어야 합니다.\n\n```\nUpdateCTestConfiguration from :/home/user/project/build/CTestConfiguration.ini\nUpdateCTestConfiguration from :/home/user/project/build/CTestConfiguration.ini\nTest project /home/user/project/build\nConstructing a list of tests\nDone constructing a list of tests\nUpdating test list for fixtures\nAdded 0 tests to meet fixture requirements\nChecking test dependency graph...\nChecking test dependency graph end\ntest 1\n Start 1: unit_tests\n\n1: Test command: /home/user/project/build/tests/unit/unit_tests\n1: Test timeout computed to be: 10000\n1: ===============================================================================\n1: All tests passed (1 assertion in 1 test case)\n1:\n1/1 Test #1: unit_tests ....................... Passed 0.01 sec\n\n100% tests passed, 0 tests failed out of 1\n\nTotal Test time (real) = 0.02 sec\n```\n","덧셈에 대한 Catch2 테스트 케이스를 포함하는 `tests/unit/math/add.cpp` 파일.",[1415,1417,1419,1421],{"_24":1416,"_83":39,"_84":410,"_85":61},"덧셈을 위한 `TEST_CASE`.",{"_24":1418,"_83":39,"_84":410,"_85":88},"포괄적인 테스트를 위한 무작위 입력 사용.",{"_24":1420,"_83":39,"_84":410,"_85":91},"`example::math::Add(a, b)`가 `a + b`와 같다는 단언.",{"_24":1422,"_83":39,"_84":410,"_85":94},"AAA 패턴을 따르는 테스트 케이스.","`Add` 함수의 정확성을 검증하기 위한 테스트 스위트.",{"_22":1425,"_24":1426,"_75":1427,"_77":1428,"_79":1429,"_51":1436,"_42":99},"task-1750999618306","Subtract 함수를 위한 단위 테스트","# 작업: Subtract 함수에 대한 단위 테스트\n\n> **에픽**: 테스트 스위트 및 코드 커버리지\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: `Subtract` 함수의 정확성을 검증하기 위한 테스트 스위트.\n- **근거**: `example::math::Subtract` 함수의 기능적 정확성과 신뢰성을 보장하기 위함입니다. 이 작업은 코드 품질 강제 자동화라는 프로젝트의 핵심 목표에 필수적입니다. 포괄적인 단위 테스트를 구현함으로써 회귀 방지 안전망을 구축하고 프로젝트의 전반적인 코드 커버리지 목표에 기여하여, 기초 라이브러리 구성 요소가 견고하고 버그가 없도록 보장합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: 뺄셈을 위한 Catch2 테스트 케이스를 포함하는 `tests/unit/math/subtract.cpp` 파일.\n- **사양**:\n - **생성 파일**: `tests/unit/math/subtract.cpp`\n - **테스트 프레임워크**: Catch2\n - **테스트 구조**: 테스트 스위트를 정의하는 데 `TEST_CASE` 매크로를 사용해야 합니다.\n - **테스트 로직**: 구현 시 무작위 정수 입력을 사용하여 광범위한 시나리오를 테스트해야 합니다.\n - **단언(Assertion)**: `REQUIRE` 매크로를 사용하여 `example::math::Subtract(a, b)`의 출력이 `a - b` 표현식과 같은지 단언해야 합니다.\n - **패턴**: 테스트 로직은 명확성을 위해 Arrange-Act-Assert(AAA) 패턴을 준수해야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── tests/\n# └── unit/\n# └── math/\n# └── subtract.cpp <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 새로운 단위 테스트의 빌드 타임 및 런타임 흐름을 보여줍니다. CMake 빌드 시스템은 테스트 소스를 실행 파일로 컴파일하고, CTest는 이 실행 파일을 실행하여 라이브러리의 기능을 검증합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph build_time [\"빌드 타임\"]\n CMake[\"모듈식 CMake 빌드 시스템\"] -- \"발견 및 컴파일\" --> TestExecutable[\"테스트 실행 파일 (subtract.cpp 기반)\"];\n ExampleLib[\"C++ 예제 라이브러리
(libexample.a)\"] -- \"에 링크됨\" --> TestExecutable;\n Catch2Lib[\"Catch2 라이브러리\"] -- \"에 링크됨\" --> TestExecutable;\n end\n\n subgraph test_time [\"테스트 실행 타임\"]\n CTest[\"CTest 테스트 러너\"] -- \"실행\" --> TestExecutable;\n TestExecutable -- \"호출\" --> MathSubtract[\"example::math::Subtract(...)\"];\n MathSubtract -- \"결과 반환\" --> TestExecutable;\n TestExecutable -- \"통과/실패 보고\" --> CTest;\n end\n\n build_time --> test_time;\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이것은 개략적인 체크리스트이며, 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] 뺄셈을 위한 `TEST_CASE`.\n- [ ] 포괄적인 테스트를 위한 무작위 입력 사용.\n- [ ] `example::math::Subtract(a, b)`가 `a - b`와 같다는 단언(Assertion).\n- [ ] AAA 패턴을 따르는 테스트 케이스.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층형 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **테스트 스위트**: 이 작업은 테스트 스위트 구성 요소의 핵심 부분인 새로운 단위 테스트를 직접 구현합니다. 이 스위트는 Catch2와 CTest를 사용하여 라이브러리 기능을 검증할 책임이 있습니다.\n - **C++ 예제 라이브러리**: 이 테스트는 이 라이브러리의 `example::math::Subtract` 함수를 직접 사용합니다. 이를 통해 라이브러리 구성 요소의 공개 인터페이스와 구현을 검증합니다.\n - **모듈식 CMake 빌드 시스템**: 빌드 시스템은 새로운 `tests/unit/math/subtract.cpp` 파일을 발견하고, 컴파일하며, Catch2 프레임워크 및 예제 수학 라이브러리에 대해 링크하여 테스트 실행 파일을 생성할 책임이 있습니다.\n - **의존성 관리 시스템**: 이 구성 요소는 FetchContent를 통해 Catch2 테스트 프레임워크를 빌드 시스템에서 사용할 수 있도록 할 책임이 있으며, 이는 이 테스트를 작성하기 위한 전제 조건입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `tests/unit/math/subtract.cpp`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `Step`은 **인수 조건**의 항목에 해당합니다. 각 `Step`은 일련의 세분화된 `Action`으로 나뉩니다. 각 `Action`에 대해 제목, 명확한 서술적 설명('무엇'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 1단계: 뺄셈을 위한 `TEST_CASE`\n\n#### 1. 테스트 파일 및 기본 구조 생성\n\n이 작업은 단위 테스트를 위한 기본적인 상용구 코드를 설정합니다. 지정된 위치에 새 파일이 생성됩니다. 테스트 대상 함수에 접근하기 위한 `example/math/subtract.hpp`와 테스트 프레임워크 매크로를 위한 `catch2/catch_test_macros.hpp` 등 필요한 헤더가 포함됩니다. 세분화된 테스트 실행을 가능하게 하기 위해 설명적인 이름과 태그(`[unit]`, `[math]`, `[subtract]`)를 가진 `TEST_CASE`가 정의됩니다.\n\n**파일**: `tests/unit/math/subtract.cpp`\n\n```cpp\n/**\n * @file subtract.cpp\n * @author movingChurch\n * @brief Subtract 함수에 대한 단위 테스트입니다.\n * @version 0.1\n * @date 2025-06-27\n *\n * @copyright HolyGround (c) 2025\n *\n */\n#include \"example/math/subtract.hpp\"\n\n#include \n\n// ... 다음 단계에서 난수 생성기 헤더가 추가될 것입니다\n\nTEST_CASE(\"Subtract function with random numbers\", \"[unit][math][subtract]\") {\n // 테스트 로직이 여기에 구현될 것입니다.\n}\n```\n\n---\n\n### 2단계: 포괄적인 테스트를 위한 무작위 입력 사용\n\n#### 1. C++ 난수 생성 통합\n\n`Subtract` 함수의 견고성을 보장하려면, 몇 개의 하드코딩된 값이 아닌 다양한 입력에 대해 테스트해야 합니다. 이 작업은 난수 생성을 위한 표준 C++ 유틸리티를 도입합니다. `std::random_device`는 비결정적 시드를 제공하고, `std::mt19937`은 핵심 의사 난수 생성기이며, `std::uniform_int_distribution`은 지정된 범위에서 숫자가 균등하게 선택되도록 보장합니다. 이 설정은 테스트 단언에 무작위 입력을 제공하기 위해 `TEST_CASE` 내부에 배치됩니다.\n\n**파일**: `tests/unit/math/subtract.cpp`\n\n```cpp\n// ... 헤더 포함\n#include \n\nTEST_CASE(\"Subtract function with random numbers\", \"[unit][math][subtract]\") {\n // 준비(Arrange)\n constexpr int kNumIterations = 100;\n constexpr int kRange = 10000;\n std::random_device random_device;\n std::mt19937 generator(random_device());\n std::uniform_int_distribution<> distribution(-kRange, kRange);\n\n // ... 다음 단계에서 테스트 루프가 추가될 것입니다\n}\n```\n\n---\n\n### 3단계: `example::math::Subtract(a, b)`가 `a - b`와 같다는 단언. 및 4단계: AAA 패턴을 따르는 테스트 케이스\n\n#### 1. AAA 패턴으로 테스트 루프 구현\n\n이 작업은 핵심 검증 로직을 구현하여 테스트를 완료합니다. `for` 루프는 여러 무작위 입력을 확인하기 위해 테스트를 `kNumIterations`번 실행합니다. 루프 내부에서는 명확성을 극대화하기 위해 Arrange-Act-Assert(AAA) 패턴을 엄격하게 따릅니다:\n\n- **준비(Arrange)**: 두 개의 난수를 생성하고 예상되는 차이를 계산합니다. 이는 테스트의 사전 조건을 설정합니다.\n- **실행(Act)**: 생성된 숫자로 `example::math::Subtract` 함수를 호출합니다. 이것이 테스트 대상이 되는 행동입니다.\n- **단언(Assert)**: Catch2의 `REQUIRE` 매크로를 사용하여 함수 호출의 실제 결과가 예상 결과와 일치하는지 확인합니다. 일치하지 않으면 테스트는 실패합니다.\n\n**파일**: `tests/unit/math/subtract.cpp`\n\n```cpp\n// ... 헤더 및 TEST_CASE 설정\n\n for (int i = 0; i < kNumIterations; ++i) {\n const int FirstNumber = distribution(generator);\n const int SecondNumber = distribution(generator);\n const int ExpectedResult = FirstNumber - SecondNumber;\n\n // 실행(Act)\n const int ActualResult = example::math::Subtract(FirstNumber, SecondNumber);\n\n // 단언(Assert)\n REQUIRE(ActualResult == ExpectedResult);\n }\n}\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n이 작업의 올바른 구현을 검증하기 위해, 개발자는 프로젝트를 컴파일하고 CTest를 사용하여 테스트 스위트를 실행해야 합니다. 이를 통해 새 테스트 파일이 빌드 시스템에 올바르게 통합되고 테스트 자체가 통과하는지 확인합니다.\n\n```bash\n# 1. 빌드 디렉터리로 이동합니다 (없으면 생성)\n# (프로젝트 루트에 있다고 가정)\nmkdir -p build && cd build\n\n# 2. CMake로 프로젝트를 구성합니다\n# 이 단계에서 새 테스트 파일을 발견합니다.\ncmake ..\n\n# 3. 프로젝트 타겟을 빌드합니다\n# 이 단계에서 새 테스트 실행 파일을 컴파일합니다.\nmake -j$(nproc)\n\n# 4. CTest를 사용하여 테스트 스위트를 실행합니다\n# 개별 테스트의 출력을 보려면 --verbose 플래그를 사용합니다.\n# 특정 이름과 일치하는 테스트만 실행하려면 -R 플래그를 사용합니다.\nctest --verbose -R \"Subtract function with random numbers\"\n```\n\n### 4.2. 예상 결과\n\n`ctest` 명령어는 성공적으로 실행되어야 하며 \"Subtract function with random numbers\" 테스트가 통과했다고 보고해야 합니다. 출력은 다음과 유사해야 합니다:\n\n```\nUpdateCTestConfiguration from :/home/user/project/build/DartConfiguration.tcl\nUpdateCTestConfiguration from :/home/user/project/build/DartConfiguration.tcl\nTest project /home/user/project/build\nConstructing a list of tests\nDone constructing a list of tests\nUpdating test list for fixtures\nAdded 0 tests to meet fixture requirements\nChecking test dependency graph...\nChecking test dependency graph end\ntest 2/2 Start #2: unit_test_subtract\n2: Test command: /home/user/project/build/bin/unit_test_subtract \"-r\" \"compact\"\n2: Test timeout computed to be: 10000\n2: ===============================================================================\n2: test session starts ==========================================================\n2: \n2: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n2: unit_test_subtract is a Catch2 v3.x.x host application.\n2: Run with -? for options\n2: \n2: -------------------------------------------------------------------------------\n2: Subtract function with random numbers\n2: -------------------------------------------------------------------------------\n2: /home/user/project/tests/unit/math/subtract.cpp:21\n2: ...............................................................................\n2: \n2: /home/user/project/tests/unit/math/subtract.cpp:32:\n2: PASSED:\n2: REQUIRE( ActualResult == ExpectedResult )\n2: with expansion:\n2: -2139 == -2139\n2: \n2: ===============================================================================\n2: test cases: 1 | 1 passed\n2: assertions: 1 | 1 passed\n2: \n 1/1 Test #2: unit_test_subtract ............... Passed 0.01 sec\n\n100% tests passed, 0 tests failed out of 1\n\nTotal Test time (real) = 0.02 sec\n```\n","뺄셈에 대한 Catch2 테스트 케이스를 포함하는 `tests/unit/math/subtract.cpp` 파일.",[1430,1432,1433,1435],{"_24":1431,"_83":39,"_84":428,"_85":61},"뺄셈을 위한 `TEST_CASE`.",{"_24":1418,"_83":39,"_84":428,"_85":88},{"_24":1434,"_83":39,"_84":428,"_85":91},"`example::math::Subtract(a, b)`가 `a - b`와 같다는 단언.",{"_24":1422,"_83":39,"_84":428,"_85":94},"`Subtract` 함수의 정확성을 검증하기 위한 테스트 스위트.",{"_22":1438,"_24":1439,"_75":1440,"_77":1441,"_79":1442,"_51":1453,"_42":99},"task-1750999672120","산술 연산에 대한 통합 테스트","# 작업: 산술 연산을 위한 통합 테스트\n\n> **에픽**: 테스트 스위트 및 코드 커버리지\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: `Add` 및 `Subtract` 함수의 결합된 동작을 검증하는 테스트 스위트.\n- **근거**: 단위 테스트는 `Add` 및 `Subtract` 함수를 개별적으로 검증하지만, 이 함수들이 순서대로 올바르게 작동하는지 확인하려면 통합 테스트가 필요합니다. 이는 `C++ 예제 라이브러리` 내의 개별 기능 단위 간의 상호 작용을 검증하며, 한 함수의 출력이 다른 함수에서 안정적으로 사용될 수 있음을 보장합니다. 이는 복잡한 로직을 구축하는 데 매우 중요합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 결합된 연산에 대한 테스트가 포함된 `tests/integration/math/arithmetic.cpp` 파일.\n- **명세**:\n - 생성 파일: `tests/integration/math/arithmetic.cpp`.\n - 사용 프레임워크: Catch2.\n - 테스트 케이스 매크로: `TEST_CASE`.\n - 테스트 케이스 태그: `[integration][math][arithmetic]`.\n - 포함 헤더: `example/math/add.hpp`, `example/math/subtract.hpp`.\n - 테스트 로직: `(a + b) - c`와 같은 연쇄적인 연산을 검증합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── tests/\n# └── integration/\n# └── math/\n# └── arithmetic.cpp <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 CTest 드라이버에 의해 조율되는 런타임 시 통합 테스트의 실행 흐름을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph CTest 실행\n Start[\"CTest가 테스트 실행 파일 실행\"]\n end\n \n subgraph 테스트 실행 파일: arithmetic_integration_test\n TestCase[\"TEST_CASE: 조합된 산술 연산\"]\n Arrange[\"준비(Arrange): 임의의 정수 a, b, c 생성\"]\n Act[\"실행(Act): example::math::Add(a, b) 호출 -> result1\"]\n Act2[\"실행(Act): example::math::Subtract(result1, c) 호출 -> final_result\"]\n Assert[\"단언(Assert): REQUIRE(final_result == (a + b) - c)\"]\n end\n \n subgraph C++ 예제 라이브러리\n AddFunc[\"example::math::Add\"]\n SubtractFunc[\"example::math::Subtract\"]\n end\n \n Start --> TestCase\n TestCase --> Arrange\n Arrange --> Act\n Act --> AddFunc\n AddFunc --> Act\n Act --> Act2\n Act2 --> SubtractFunc\n SubtractFunc --> Act2\n Act2 --> Assert\n Assert -- \"성공/실패\" --> Start\n\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] 조합된 산술 연산을 위한 `TEST_CASE`.\n- [ ] `add.hpp`와 `subtract.hpp` 모두 포함.\n- [ ] `(a + b) - c`와 같은 연쇄적인 연산에 대한 테스트.\n- [ ] 조합된 결과를 검증하는 단언(assertion).\n- [ ] 통합 테스트용으로 태그된 테스트 케이스.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층화된 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **테스트 스위트**: 이 작업은 이 구성 요소 내에 새로운 테스트를 직접 구현합니다. 테스트 스위트의 책임은 다른 프로젝트 구성 요소의 정확성을 검증하는 것이며, CTest를 통해 실행됩니다.\n - **C++ 예제 라이브러리**: 테스트 대상 구성 요소입니다. 새로운 통합 테스트는 이 라이브러리의 공개 인터페이스(`add.hpp`, `subtract.hpp`)를 사용하여 결합된 동작을 검증합니다.\n - **모듈식 CMake 빌드 시스템**: 이 구성 요소는 새로운 테스트 소스 파일을 발견하고, 컴파일하며, C++ 예제 라이브러리 및 Catch2 프레임워크에 연결하고, 결과 실행 파일을 CTest에 테스트로 등록하는 역할을 합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `tests/integration/math/arithmetic.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공할 것입니다.\n\n---\n\n### 단계 1: 조합된 산술 연산을 위한 `TEST_CASE`\n\n#### 1. Catch2로 테스트 케이스 구조 정의\n\n이 작업은 Catch2의 `TEST_CASE` 매크로를 사용하여 테스트의 기본 구조를 설정합니다. 첫 번째 매개변수는 테스트 목적에 대한 사람이 읽을 수 있는 설명을 제공합니다. 두 번째 매개변수는 CTest가 테스트를 필터링하고 구성하는 데 사용하는 태그를 포함하며, 이는 다음 단계에서 자세히 설명합니다. 이것은 모든 테스트 로직이 포함될 기본 스코프를 생성합니다.\n\n**파일**: `tests/integration/math/arithmetic.cpp`\n\n```cpp\n#include \n\n// ... 여기에 다른 인클루드가 추가될 예정입니다\n\nTEST_CASE(\n \"Integration: Combined Add and Subtract operations with random numbers\",\n \"[integration][math][arithmetic]\") {\n // 여기에 테스트 로직이 구현될 예정입니다.\n}\n```\n\n---\n\n### 단계 2: `add.hpp`와 `subtract.hpp` 모두 포함\n\n#### 1. 테스트할 함수 및 유틸리티 헤더 포함\n\n`Add` 및 `Subtract` 함수를 호출하려면 공개 선언을 스코프 안으로 가져와야 합니다. 이는 `example` 라이브러리에서 각각의 헤더 파일을 포함하여 달성됩니다. 또한, 테스트가 견고하도록 다양한 테스트 데이터 생성을 지원하기 위해 `` 표준 라이브러리 헤더를 포함합니다.\n\n**파일**: `tests/integration/math/arithmetic.cpp`\n\n```cpp\n#include \n\n#include \n\n#include \"example/math/add.hpp\"\n#include \"example/math/subtract.hpp\"\n\nTEST_CASE(\n \"Integration: Combined Add and Subtract operations with random numbers\",\n \"[integration][math][arithmetic]\") {\n // ...\n}\n```\n\n---\n\n### 단계 3: `(a + b) - c`와 같은 연쇄적인 연산에 대한 테스트\n\n#### 1. 데이터 기반 테스트 루프 구현\n\n테스트가 포괄적이도록 몇 개의 하드코딩된 값에 의존해서는 안 됩니다. 이 작업은 각 반복마다 광범위한 임의의 정수를 생성하는 루프를 구현합니다. 테스트의 \"준비(Arrange)\" 단계의 일부인 이 접근 방식은 양수, 음수, 0 값을 포함한 다양한 입력에 대해 산술 로직을 검증합니다.\n\n**파일**: `tests/integration/math/arithmetic.cpp`\n\n```cpp\n// ... 인클루드\n\nTEST_CASE(\n \"Integration: Combined Add and Subtract operations with random numbers\",\n \"[integration][math][arithmetic]\") {\n // 준비 (Arrange)\n constexpr int kNumIterations = 100;\n constexpr int kRange = 10000;\n std::random_device random_device;\n std::mt19937 generator(random_device());\n std::uniform_int_distribution<> distribution(-kRange, kRange);\n\n for (int i = 0; i < kNumIterations; ++i) {\n const int FirstNumber = distribution(generator);\n const int SecondNumber = distribution(generator);\n const int ThirdNumber = distribution(generator);\n\n // 실행(Act) 및 단언(Assert) 로직이 여기에 추가될 예정입니다.\n }\n}\n```\n\n#### 2. 연쇄적인 산술 연산 수행\n\n이 작업은 테스트의 \"실행(Act)\" 단계를 수행합니다. 처음 두 개의 임의의 숫자로 `Add` 함수를 호출한 다음 그 결과를 `Subtract` 함수에 전달합니다. 이것은 연쇄적인 호출 `(a + b) - c`를 명시적으로 테스트하여 구성 요소가 올바르게 통합되는지 확인합니다. 다른 연산 우선순위에서도 정확성을 보장하기 위해 두 번째 연쇄 연산 `a - (b + c)`도 테스트합니다.\n\n**파일**: `tests/integration/math/arithmetic.cpp`\n\n```cpp\n// ...\n for (int i = 0; i < kNumIterations; ++i) {\n const int FirstNumber = distribution(generator);\n const int SecondNumber = distribution(generator);\n const int ThirdNumber = distribution(generator);\n\n // (a + b) - c에 대한 실행(Act)\n const int AddFirstResult = example::math::Add(FirstNumber, SecondNumber);\n const int FinalResult1 =\n example::math::Subtract(AddFirstResult, ThirdNumber);\n // ... FinalResult1에 대한 단언(Assert)\n\n // a - (b + c)에 대한 실행(Act)\n const int AddSecondResult = example::math::Add(SecondNumber, ThirdNumber);\n const int FinalResult2 =\n example::math::Subtract(FirstNumber, AddSecondResult);\n // ... FinalResult2에 대한 단언(Assert)\n }\n// ...\n```\n\n---\n\n### 단계 4: 조합된 결과를 검증하는 단언(assertion)\n\n#### 1. `REQUIRE`로 연산 결과 검증\n\n이 작업은 \"단언(Assert)\" 단계를 구현합니다. Catch2 `REQUIRE` 매크로를 사용하여 연쇄적인 라이브러리 함수 호출의 출력이 직접적인 C++ 산술 표현식의 결과와 일치하는지 확인합니다. `REQUIRE`는 실패 시 즉시 테스트를 중단하므로 이러한 종류의 검증에 적합합니다. 이 단계는 통합이 성공적이라는 궁극적인 증거입니다.\n\n**파일**: `tests/integration/math/arithmetic.cpp`\n\n```cpp\n// ...\n // (a + b) - c에 대한 실행(Act) 및 단언(Assert)\n const int AddFirstResult = example::math::Add(FirstNumber, SecondNumber);\n const int FinalResult1 =\n example::math::Subtract(AddFirstResult, ThirdNumber);\n REQUIRE(FinalResult1 == (FirstNumber + SecondNumber) - ThirdNumber);\n\n // a - (b + c)에 대한 실행(Act) 및 단언(Assert)\n const int AddSecondResult = example::math::Add(SecondNumber, ThirdNumber);\n const int FinalResult2 =\n example::math::Subtract(FirstNumber, AddSecondResult);\n REQUIRE(FinalResult2 == FirstNumber - (SecondNumber + ThirdNumber));\n// ...\n```\n\n---\n\n### 단계 5: 통합 테스트용으로 태그된 테스트 케이스\n\n#### 1. 세분화된 테스트 태그 적용\n\n이 작업은 `TEST_CASE`가 올바르게 태그되었는지 확인합니다. `[integration]` 태그는 이 테스트를 단위 테스트와 구별하는 데 중요하며, 선택적 실행(예: 사전 커밋 확인 중에 빠른 단위 테스트만 실행)을 가능하게 합니다. `[math]` 및 `[arithmetic]` 태그는 집중적인 테스트 실행을 위해 추가적인 세분성을 제공합니다. 이 태그 지정 전략은 확장 가능하고 관리하기 쉬운 테스트 스위트를 유지하는 데 기본입니다.\n\n**파일**: `tests/integration/math/arithmetic.cpp`\n\n```cpp\n// ... 인클루드\n\nTEST_CASE(\n \"Integration: Combined Add and Subtract operations with random numbers\",\n \"[integration][math][arithmetic]\") { // <-- 이 태그들이 테스트를 분류합니다\n // ...\n}\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n이 테스트의 올바른 구현을 확인하려면, 개발자는 프로젝트를 빌드하고 특정 `integration` 태그로 필터링하여 CTest를 사용하여 테스트 스위트를 실행해야 합니다.\n\n```bash\n# 1. 빌드 디렉터리로 이동합니다 (없으면 생성).\nmkdir -p build && cd build\n\n# 2. CMake로 프로젝트를 구성합니다.\n# 이 과정에서 새 테스트를 발견하고 설정합니다.\ncmake ..\n\n# 3. 프로젝트와 모든 테스트 실행 파일을 빌드합니다.\n# Linux/macOS의 경우\nmake\n# Windows Visual Studio의 경우\n# cmake --build .\n\n# 4. 통합 테스트를 필터링하여 CTest를 실행합니다.\n# -R 플래그는 이름/태그로 테스트를 선택하기 위한 정규식을 제공합니다.\nctest -R \"integration\"\n```\n\n### 4.2. 예상 결과\n\nCTest 명령어는 성공적으로 실행되고 단일 통합 테스트가 통과했다고 보고해야 합니다. 출력은 다음과 유사해야 합니다.\n\n```\nTest project /path/to/readable-code-cpp-project-template/build\n Start 1: arithmetic_integration_test\n1/1 Test #1: arithmetic_integration_test ........ Passed 0.01 sec\n\n100% tests passed, 0 tests failed out of 1\n\nTotal Test time (real) = 0.02 sec\n```\n","결합된 연산에 대한 테스트를 포함하는 `tests/integration/math/arithmetic.cpp` 파일.",[1443,1445,1447,1449,1451],{"_24":1444,"_83":39,"_84":446,"_85":61},"결합된 산술을 위한 `TEST_CASE`.",{"_24":1446,"_83":39,"_84":446,"_85":88},"`add.hpp` 및 `subtract.hpp` 모두 포함.",{"_24":1448,"_83":39,"_84":446,"_85":91},"`(a + b) - c`와 같은 연쇄 연산에 대한 테스트.",{"_24":1450,"_83":39,"_84":446,"_85":94},"결합된 결과를 검증하는 단언.",{"_24":1452,"_83":39,"_84":446,"_85":97},"통합 테스트용으로 태그된 테스트 케이스.","`Add` 및 `Subtract` 함수의 결합된 동작을 검증하기 위한 테스트 스위트.",{"_22":1455,"_24":1456,"_75":1457,"_77":1458,"_79":1459,"_51":1468,"_42":99},"task-1750999733318","코드 포맷터 실행 스크립트","# 작업: 코드 포매터 실행 스크립트\n\n> **에픽**: 자동화된 개발자 도구\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 모든 프로젝트 소스 파일에 `clang-format`을 실행하는 셸 스크립트.\n- **근거**: 이 스크립트는 `.clang-format` 설정 파일에 정의된 프로젝트의 C++ 코딩 스타일 강제화를 자동화합니다. 이 프로세스를 자동화하는 것은 프로젝트의 핵심 목표이며, 코드 일관성을 보장하고 가독성을 향상시키며, 도구를 수동으로 실행해야 하는 개발자의 인지적 부담을 줄여줍니다. 이 스크립트는 `품질 보증 도구 체인`의 핵심 부분 역할을 합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: CMake 타겟에서 호출할 수 있는 `run_formatter.sh` 스크립트.\n- **사양**:\n - **스크립트 이름**: `run_formatter.sh`\n - **실행 환경**: POSIX 호환 셸 스크립트.\n - **인자**:\n 1. `clang-format` 실행 파일의 경로.\n 2. 공백으로 구분된 포맷할 파일 경로 목록.\n - **동작**:\n - 제공된 각 파일에 `clang-format -i`(인플레이스 포맷팅)를 적용합니다.\n - `git diff`를 사용하여 포매터에 의해 수정된 파일을 감지하고 보고합니다.\n - 수정된 각 파일에 대해 색상으로 구분된 diff를 출력합니다.\n - 확인 및 포맷된 총 파일 수를 요약하여 출력합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── scripts/\n# └── executables/\n# └── run_formatter.sh <-- 신규\n```\n\n- **프로세스 흐름도**\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n CMake[\"CMake 타겟 ('format')\"] -- \"실행\" --> Script[\"run_formatter.sh\"];\n Script -- \"clang-format 경로
및 파일 목록 수신\" --> Script;\n Script -- \"각 파일에 대해\" --> GitAdd[\"임시로 변경 사항 스테이징
(git add .)\"];\n GitAdd --> ClangFormat[\"'clang-format -i' 적용\"];\n ClangFormat --> GitDiff[\"수정 사항 확인
(git diff --quiet)\"];\n subgraph \"수정된 경우\"\n GitDiff --> ReportDiff[\"색상화된 diff를 콘솔에 출력\"];\n end\n GitDiff --> Loop[\"다음 파일로 계속\"];\n Loop -- \"마지막 파일 이후\" --> GitReset[\"git 인덱스 복원
(git reset)\"];\n GitReset --> Summary[\"실행 요약 출력\"];\n Summary --> Console[\"콘솔에 출력\"];\n\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] clang-format 실행 파일과 파일 목록을 인자로 받는 스크립트.\n- [ ] 각 파일에 `clang-format -i`를 실행하는 로직.\n- [ ] 수정된 파일을 감지하고 보고하는 로직.\n- [ ] 포맷팅 실행에 대한 요약 출력.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층화된 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **품질 보증 도구 체인**: 이 작업은 이 구성 요소의 일부를 직접 구현합니다. 이 스크립트는 프로젝트 표준에 따라 `clang-format` 도구를 적용하는 실행 엔진입니다.\n - **모듈식 CMake 빌드 시스템**: 이 구성 요소는 `run_formatter.sh` 스크립트를 호출합니다. 후속 작업에서 이 스크립트를 올바른 매개변수로 호출하는 커스텀 타겟(예: `make format`)을 정의하기 위한 상위 수준의 CMake 인터페이스 함수가 생성되어, 포맷팅 도구를 개발자 워크플로우에 완전히 통합할 것입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `scripts/executables/run_formatter.sh`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부적인 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: clang-format 실행 파일과 파일 목록을 인자로 받는 스크립트\n\n#### 1. 스크립트 초기화 및 설정\n\n이 액션은 스크립트의 기초를 설정합니다. 셸을 지정하기 위한 셔뱅(shebang), 오류 발생 시 즉시 스크립트가 종료되도록 하는 `set -e` 명령어, 그리고 가독성 있는 색상화된 출력을 위한 ANSI 색상 코드 정의를 포함합니다. 이 설정은 견고하고 사용자 친화적인 스크립트 환경을 만듭니다.\n\n**파일**: `scripts/executables/run_formatter.sh`\n\n```bash\n#!/bin/sh\n\n# ==============================================================================\n#\n# run_formatter.sh\n#\n# 설명:\n# 이 스크립트는 지정된 C++ 파일에 clang-format을 실행하고, 변경 사항을\n# 보고하며, 요약을 제공합니다.\n#\n# 사용법:\n# ./run_formatter.sh ...\n#\n# ==============================================================================\n\n# --- 설정 및 초기화 ---\n\n# 명령이 0이 아닌 상태로 종료되면 즉시 종료합니다.\nset -e\n\n# 가독성 있는 출력을 위한 ANSI 색상 코드입니다.\nCOLOR_RESET='\\x1b[0m'\nCOLOR_GREEN='\\x1b[32m'\nCOLOR_YELLOW='\\x1b[33m'\nCOLOR_CYAN='\\x1b[36m'\nCOLOR_GRAY='\\x1b[90m'\n```\n\n#### 2. 인자 검증 로직\n\n이 액션은 명령줄 인자를 파싱하고 검증하는 로직을 구현합니다. 스크립트는 첫 번째 인자로 `clang-format` 실행 파일의 경로를 받아야 하고, 그 이후 인자들로 확인할 파일 목록을 받아야 합니다. 실행 파일 경로가 없으면 오류와 함께 종료하고, 파일이 제공되지 않으면 정상적으로 종료합니다. 이는 스크립트가 올바르게 사용되도록 보장하고 런타임 오류를 방지합니다.\n\n**파일**: `scripts/executables/run_formatter.sh`\n\n```bash\n# ... (이전 설정 코드)\n\n# --- 인자 검증 ---\n\nif [ -z \"$1\" ]; then\n printf \"오류: clang-format 경로가 제공되지 않았습니다.\\n\" >&2\n exit 1\nfi\nCLANG_FORMAT_EXE=\"$1\"\nshift\n\nif [ $# -eq 0 ]; then\n printf \"확인할 C++ 파일이 없습니다. 종료합니다.\\n\"\n exit 0\nfi\nFILES_TO_CHECK=\"$@\"\n\n# --- 메인 로직 ---\n\nmain() {\n # ... (메인 로직은 다음 단계에서 추가될 것입니다)\n}\n\n# --- 스크립트 실행 ---\n\nmain\n```\n\n---\n\n### 단계 2: 각 파일에 `clang-format -i`를 실행하는 로직\n\n#### 1. 메인 처리 루프 구현\n\n이 액션은 `main` 함수에 핵심 처리 루프를 추가합니다. 스크립트는 `$FILES_TO_CHECK` 변수에 전달된 각 파일 경로를 반복합니다. 이 루프 내에서, 파일에 직접(인플레이스) 포맷팅 변경을 적용하는 `-i` 플래그와 함께 `clang-format` 명령이 실행됩니다. 이것이 코딩 스타일을 강제하는 중심 메커니즘입니다.\n\n**파일**: `scripts/executables/run_formatter.sh`\n\n```bash\n# ... (인자 검증)\n\n# --- 메인 로직 ---\n\nmain() {\n local modified_files=\"\"\n local modified_count=0\n local total_count=0\n\n printf \"%bC++ 코드 포매터를 실행합니다...%b\\n\" \"$COLOR_CYAN\" \"$COLOR_RESET\"\n\n # 현재 모든 변경 사항을 스테이징합니다. 이렇게 하면 다음 단계에서 `git diff`가\n # clang-format에 의해 발생한 변경 사항만 표시하도록 보장합니다.\n git add .\n\n for file in $FILES_TO_CHECK; do\n total_count=$((total_count + 1))\n\n # clang-format을 인플레이스(in-place)로 실행합니다.\n \"$CLANG_FORMAT_EXE\" -i \"$file\"\n\n # ... (변경 감지는 다음 단계에서 추가될 것입니다)\n done\n\n # ... (요약은 이후 단계에서 추가될 것입니다)\n\n # git 인덱스를 원래 상태로 복원합니다.\n printf \"\\n%bgit 인덱스를 복원 중입니다...%b\\n\" \"$COLOR_GRAY\" \"$COLOR_RESET\"\n git reset >/dev/null\n}\n\n# ... (헬퍼 함수 및 스크립트 실행)\n```\n\n---\n\n### 단계 3: 수정된 파일을 감지하고 보고하는 로직\n\n#### 1. `git diff`를 사용한 변경 감지 구현\n\n이 액션은 `clang-format`이 실제로 파일을 수정했는지 감지하는 로직을 추가합니다. `clang-format -i`는 \"파일이 변경됨\"에 대한 상태 코드가 없으므로, `git diff --quiet`를 사용하여 파일의 상태를 git 인덱스와 비교합니다. 포매터의 변경 사항만 분리하기 위해, 먼저 모든 파일이 `git add .`으로 스테이징되고 루프가 끝난 후 `git reset`으로 인덱스가 복원됩니다. 이는 신뢰할 수 있는 변경 감지 방법을 제공합니다.\n\n**파일**: `scripts/executables/run_formatter.sh`\n\n```bash\n# ... (main 함수의 for 루프 내부)\n\n for file in $FILES_TO_CHECK; do\n total_count=$((total_count + 1))\n\n # clang-format을 인플레이스(in-place)로 실행합니다.\n \"$CLANG_FORMAT_EXE\" -i \"$file\"\n\n # clang-format이 파일을 수정했는지 확인합니다.\n if ! git diff --quiet -- \"$file\"; then\n modified_count=$((modified_count + 1))\n modified_files=\"${modified_files}\\n - ${file}\"\n\n # 수정된 파일에 대한 명확한 헤더를 출력합니다.\n printf \"\\n%b--- 포맷팅이 적용된 파일: %s ---%b\\n\" \"$COLOR_YELLOW\" \"$file\" \"$COLOR_RESET\"\n\n # git 관련 헤더 없이 깔끔한 diff를 보여줍니다.\n git --no-pager diff --no-prefix \"$file\" | sed '/^diff --git/d; /^index/d'\n\n printf \"%b----------------------------------------------------%b\\n\" \"$COLOR_YELLOW\" \"$COLOR_RESET\"\n fi\n done\n# ... (main 함수의 나머지 부분)\n```\n\n---\n\n### 단계 4: 포맷팅 실행에 대한 요약 출력\n\n#### 1. `print_summary` 헬퍼 함수 생성\n\n이 액션은 스크립트 실행이 끝날 때 포맷된 요약 보고서를 출력하는 전용 함수를 만듭니다. 이 함수는 총 파일 수, 수정된 파일 수, 그리고 수정된 파일 목록을 인자로 받습니다. 이 정보를 깔끔하고 읽기 쉬운 표 형식으로 제시합니다. 이러한 관심사 분리는 메인 로직을 더 깔끔하게 만들고 요약을 쉽게 수정할 수 있게 합니다.\n\n**파일**: `scripts/executables/run_formatter.sh`\n\n```bash\n# ... (main 함수 이후)\n\n# --- 헬퍼 함수 ---\n\nprint_summary() {\n local total_count=$1\n local modified_count=$2\n local modified_files=$3\n\n printf \"\\n%b=====================================%b\\n\" \"$COLOR_GREEN\" \"$COLOR_RESET\"\n printf \"%b Clang-Format 요약 %b\\n\" \"$COLOR_GREEN\" \"$COLOR_RESET\"\n printf \"%b=====================================%b\\n\" \"$COLOR_GREEN\" \"$COLOR_RESET\"\n printf \" 총 확인 파일 수: %s\\n\" \"$total_count\"\n printf \" 자동 포맷된 파일 수: %s\\n\" \"$modified_count\"\n\n if [ \"$modified_count\" -gt 0 ]; then\n printf \" 수정된 파일 목록:\\\\n\"\n # printf와 %b를 사용하여 modified_files 문자열의 개행 문자를 해석합니다.\n printf \"%b%b%b\\n\" \"$COLOR_YELLOW\" \"$modified_files\" \"$COLOR_RESET\"\n printf \"\\n%b참고: 포맷팅 변경 사항이 적용되었습니다. 검토 후 커밋해 주세요.%b\\n\" \"$COLOR_YELLOW\" \"$COLOR_RESET\"\n else\n printf \"%b모든 파일이 올바르게 포맷되었습니다!%b\\n\" \"$COLOR_GREEN\" \"$COLOR_RESET\"\n fi\n printf \"%b=====================================%b\\n\\n\" \"$COLOR_GREEN\" \"$COLOR_RESET\"\n}\n\n# --- 스크립트 실행 ---\n\nmain\n```\n\n#### 2. 메인 로직에 요약 호출 통합\n\n이 마지막 액션은 요약 함수를 메인 처리 로직에 연결합니다. 파일 루프가 완료된 후, 루프 동안 채워진 카운터와 파일 목록과 함께 `print_summary` 함수가 호출됩니다. 이는 요약이 스크립트가 종료되기 전에 마지막으로 출력되도록 보장하여, 포맷팅 실행에 대한 완전한 보고서를 제공합니다.\n\n**파일**: `scripts/executables/run_formatter.sh`\n\n```bash\n# ... (main 함수 내부, for 루프 이후)\n fi\n done\n\n print_summary \"$total_count\" \"$modified_count\" \"$modified_files\"\n\n # git 인덱스를 원래 상태로 복원합니다.\n printf \"\\n%bgit 인덱스를 복원 중입니다...%b\\n\" \"$COLOR_GRAY\" \"$COLOR_RESET\"\n git reset >/dev/null\n}\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n개발자는 구현을 검증하기 위해 다음 단계를 수행해야 합니다. 이 과정에는 `.clang-format`의 규칙을 위반하는 포맷팅을 가진 C++ 파일이 필요합니다.\n\n```bash\n# 1. 임시 디렉터리를 만들고 git 리포지토리를 초기화합니다.\n# 'git' 명령어는 스크립트의 변경 감지 기능이 작동하는 데 필요합니다.\nmkdir -p /tmp/formatter-test && cd /tmp/formatter-test\ngit init --initial-branch=main\n\n# 2. 의도적으로 포맷팅 오류가 있는 C++ 파일을 생성합니다.\n# 예: 일관성 없는 들여쓰기, 누락된 공백.\necho \"int main(){return 0;}\" > test.cpp\n\n# 3. 파일을 git 인덱스에 추가합니다.\ngit add test.cpp\n\n# 4. 프로젝트 체크아웃에서 스크립트를 실행 가능하게 만듭니다.\n# (필요에 따라 프로젝트 디렉터리 경로를 조정하세요)\nchmod +x /path/to/project/scripts/executables/run_formatter.sh\n\n# 5. 스크립트를 실행하여 clang-format 경로와 테스트 파일을 전달합니다.\n# 'clang-format'이 시스템의 PATH에 있다고 가정합니다.\n/path/to/project/scripts/executables/run_formatter.sh $(which clang-format) test.cpp\n```\n\n### 4.2. 예상 결과\n\n스크립트의 출력은 한 개의 파일이 수정되었다고 보고하고, 변경 사항의 diff를 표시하며, 요약을 출력해야 합니다. `test.cpp` 파일은 올바른 포맷팅으로 업데이트되어야 합니다.\n\n```\nC++ 코드 포매터를 실행합니다...\n\n--- 포맷팅이 적용된 파일: test.cpp ---\n--- a/test.cpp\n+++ b/test.cpp\n@@ -1 +1 @@\n-int main(){return 0;}\n+int main() { return 0; }\n----------------------------------------------------\n\n=====================================\n Clang-Format 요약\n=====================================\n 총 확인 파일 수: 1\n 자동 포맷된 파일 수: 1\n 수정된 파일 목록:\n - test.cpp\n\n참고: 포맷팅 변경 사항이 적용되었습니다. 검토 후 커밋해 주세요.\n=====================================\n\n\ngit 인덱스를 복원 중입니다...\n```\n","CMake 타겟에서 호출할 수 있는 `run_formatter.sh` 스크립트.",[1460,1462,1464,1466],{"_24":1461,"_83":39,"_84":466,"_85":61},"clang-format 실행 파일과 파일 목록을 인수로 받는 스크립트.",{"_24":1463,"_83":39,"_84":466,"_85":88},"각 파일에 `clang-format -i`를 실행하는 로직.",{"_24":1465,"_83":39,"_84":466,"_85":91},"수정된 파일을 감지하고 보고하는 로직.",{"_24":1467,"_83":39,"_84":466,"_85":94},"포맷팅 실행의 요약 출력.","모든 프로젝트 소스 파일에 `clang-format`을 실행하는 셸 스크립트.",{"_22":1470,"_24":1471,"_75":1472,"_77":1473,"_79":1474,"_51":1484,"_42":99},"task-1750999777728","정적 분석 실행 스크립트","# 작업: 정적 분석 실행 스크립트\n\n> **에픽**: 자동화된 개발자 도구\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 모든 프로젝트 소스 파일에 대해 `clang-tidy`를 실행하는 셸 스크립트.\n- **근거**: 이 프로젝트의 핵심 목표인 코드 품질 강제를 자동화합니다. 이 스크립트는 정적 분석을 실행하기 위한 일관되고 반복 가능한 메커니즘을 제공하여, 잠재적 버그를 식별하고, `.clang-tidy`에 정의된 코딩 표준을 강제하며, 변경 사항이 커밋되기 전에 전반적인 코드 상태를 개선하는 데 도움을 줍니다. 이를 빌드 시스템에 통합하면 중요한 품질 검사를 간단한 명령으로 만들어 개발자 생산성을 향상시킵니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: CMake 타겟으로 호출할 수 있는 `run_static_analysis.sh` 스크립트.\n- **명세**:\n - **스크립트 이름**: `run_static_analysis.sh`\n - **권한**: 실행 가능 (`+x`)\n - **인자**:\n 1. `` (문자열, 필수): `clang-tidy` 실행 파일의 절대 경로.\n 2. `` (문자열, 필수): `compile_commands.json`을 포함하는 빌드 디렉터리의 경로.\n 3. ` ...` (문자열 목록, 필수): 분석할 파일들의 공백으로 구분된 목록.\n - **종료 코드**: 모든 파일에서 `clang-tidy`에 의해 보고된 이슈가 없으면 스크립트는 상태 `0`으로 종료해야 합니다. 하나라도 이슈가 보고된 파일이 있으면 상태 `1`로 종료해야 합니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── scripts/\n# └── executables/\n# └── run_static_analysis.sh <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 개발자가 정적 분석 프로세스를 호출할 때의 운영 흐름을 보여줍니다. 이 프로세스는 CMake에 의해 편성되고 이 스크립트에 의해 실행됩니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph 개발자 상호작용\n Dev[\"개발자\"] -- \"1\\. make static_analysis 실행\" --> CMakeTarget\n end\n \n subgraph 빌드 시스템\n CMakeTarget[\"CMake static_analysis 타겟\"] -- \"2\\. 스크립트 호출\" --> Script[\"run_static_analysis.sh\"]\n end\n \n subgraph 스크립트 실행\n Script -- \"3\\. 소스 파일들을 순회\" --> Loop\n Loop -- \"4\\. 각 파일에 대해 clang-tidy 호출\" --> ClangTidy[\"clang-tidy 실행 파일\"]\n end\n \n subgraph 툴링\n ClangTidy -- \"5\\. 컴파일 명령어 읽기\" --> CompileCommands[\"build/compile_commands.json\"]\n ClangTidy -- \"6\\. 분석 규칙 읽기\" --> ClangTidyConfig[\".clang-tidy\"]\n ClangTidy -- \"7\\. 결과 보고\" --> ScriptOutput\n end\n \n subgraph 출력\n ScriptOutput[\"스크립트가 형식화된 출력 인쇄\"] -- \"8\\. 개발자에게 요약 표시\" --> Dev\n end\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 상세 구현은 3절에 있습니다.\n\n- [ ] clang-tidy 실행 파일, 빌드 경로, 파일 목록을 인자로 받는 스크립트.\n- [ ] 각 파일에 대해 `clang-tidy`를 실행하는 로직.\n- [ ] 외부 헤더의 경고를 억제하는 필터링 옵션.\n- [ ] 분석 실행에 대한 요약 출력.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층화된 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련된 주요 컴포넌트**:\n - **품질 보증 툴체인**: 이 작업은 이 컴포넌트의 책임을 직접 구현한 것입니다. 스크립트는 QA 툴체인의 핵심 부분인 `clang-tidy` 도구를 조율합니다.\n - **모듈식 CMake 빌드 시스템**: 이 컴포넌트는 스크립트를 호출하는 역할을 합니다. 커스텀 타겟(예: `static_analysis`)이 상위 수준의 CMake 인터페이스 모듈에 정의되며, 이 모듈은 스크립트에 필요한 인자(도구 경로, 빌드 디렉터리, 파일 목록)를 제공합니다.\n - **C++ 예제 라이브러리 및 테스트 스위트**: 이 컴포넌트들이 관리하는 소스 파일(`.cpp`, `.h`)은 정적 분석 스크립트의 주요 입력으로 사용됩니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `scripts/executables/run_static_analysis.sh`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `조치`로 나뉩니다. 각 `조치`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: clang-tidy 실행 파일, 빌드 경로, 파일 목록을 인자로 받는 스크립트\n\n#### 1. 스크립트 초기화 및 인자 파싱\n\n이 조치는 셸 스크립트를 생성하고 명령줄 인자를 파싱하고 검증하는 초기 로직을 구현합니다. 이는 스크립트가 진행하기 전에 필요한 모든 입력—`clang-tidy` 실행 파일 경로, 빌드 디렉터리(`compile_commands.json`을 포함하는), 그리고 분석할 C++ 파일 목록—을 받도록 보장합니다. 강력한 검증은 런타임 오류를 방지하고 스크립트가 잘못 호출되었을 경우 사용자에게 명확한 피드백을 제공합니다.\n\n**파일**: `scripts/executables/run_static_analysis.sh`\n\n```bash\n#!/bin/sh\n\n# ==============================================================================\n#\n# run_static_analysis.sh\n#\n# 설명:\n# 이 스크립트는 지정된 C++ 파일에 대해 clang-tidy를 실행하여 정적\n# 분석을 수행합니다.\n#\n# 사용법:\n# ./run_static_analysis.sh <빌드-디렉터리-경로> <파일1> <파일2> ...\n#\n# ==============================================================================\n\n# --- 구성 및 설정 ---\nset +e\nCOLOR_RESET='\\x1b[0m'\nCOLOR_CYAN='\\x1b[36m'\nCOLOR_RED='\\x1b[31m'\n\n# --- 인자 검증 ---\nif [ -z \"$1\" ]; then\n printf \"오류: clang-tidy 경로가 제공되지 않았습니다.\\n\" >&2\n exit 1\nfi\nCLANG_TIDY_EXE=\"$1\"\nshift\n\nif [ -z \"$1\" ]; then\n printf \"오류: 빌드 경로(compile_commands.json 포함)가 제공되지 않았습니다.\\n\" >&2\n exit 1\nfi\nBUILD_PATH=\"$1\"\nshift\n\nif [ $# -eq 0 ]; then\n printf \"확인할 C++ 파일이 없습니다. 종료합니다.\\n\"\n exit 0\nfi\nFILES_TO_CHECK=\"$@\"\n\n# ... (주요 로직은 다음 단계에서 추가될 것입니다)\n```\n\n---\n\n### 단계 2: 각 파일에 대해 `clang-tidy`를 실행하는 로직\n\n#### 1. 주 처리 루프\n\n이 조치는 스크립트의 주 처리 루프를 도입합니다. 인자로 제공된 각 파일을 순회합니다. 각 파일에 대해 현재 어떤 파일이 처리 중인지 사용자에게 알리는 상태 메시지를 출력합니다. 그런 다음 `clang-tidy`를 실행하고, 그 상태를 포착하여 이슈가 발견되었는지 판단합니다. 이 반복적인 접근 방식은 지정된 모든 파일이 분석되도록 보장하고 스크립트의 전체 종료 상태에 기여합니다.\n\n**파일**: `scripts/executables/run_static_analysis.sh`\n\n```bash\n# ... (인자 검증)\n\n# --- 주요 로직 ---\n\nmain() {\n local overall_status=0 # 0 => 성공\n local total_count=0\n local total_files=$(echo \"$FILES_TO_CHECK\" | wc -w | tr -d ' ')\n\n for file in $FILES_TO_CHECK; do\n total_count=$((total_count + 1))\n printf \"%b[%3s/%3s] 확인 중 %s%b\\n\" \"$COLOR_CYAN\" \"$total_count\" \"$total_files\" \"$file\" \"$COLOR_RESET\"\n\n # clang-tidy 실행\n tmp_out=$(mktemp)\n \"$CLANG_TIDY_EXE\" $CLANG_TIDY_OPTS -p \"$BUILD_PATH\" \"$file\" >\"$tmp_out\" 2>&1\n local tidy_status=$?\n\n # clang-tidy의 모든 출력을 표시합니다.\n cat \"$tmp_out\"\n rm -f \"$tmp_out\"\n\n if [ $tidy_status -ne 0 ]; then\n overall_status=1\n fi\n done\n \n # ... (요약은 나중에 추가될 것입니다)\n\n if [ $overall_status -ne 0 ]; then\n printf \"%bClang-tidy가 하나 이상의 파일에서 이슈를 보고했습니다.%b\\n\" \"$COLOR_RED\" \"$COLOR_RESET\"\n fi\n\n exit $overall_status\n}\n\n# --- 스크립트 실행 ---\nmain\n```\n\n---\n\n### 단계 3: 외부 헤더의 경고를 억제하는 필터링 옵션\n\n#### 1. 헤더 필터링 구성\n\n이 조치는 `clang-tidy`의 출력을 필터링하는 로직을 추가하여, 진단이 프로젝트 소유의 소스 및 헤더 파일로 제한되도록 합니다. 그 이유는 개발 팀의 통제 범위를 벗어난 서드파티 라이브러리(예: `dependencies/` 또는 `build/_deps`의 라이브러리)에서 발생하는 이슈 보고를 피하기 위함입니다. 프로젝트 루트와 표준 소스 디렉터리(`include`, `source`, `executables`, `tests`)를 기반으로 정규 표현식이 구성되고, `-header-filter` 옵션을 통해 `clang-tidy`에 전달됩니다.\n\n**파일**: `scripts/executables/run_static_analysis.sh`\n\n```bash\n# ... (인자 검증)\nFILES_TO_CHECK=\"$@\"\n\n# 프로젝트 루트 결정 (이 스크립트를 포함하는 디렉터리에서 두 단계 위)\nPROJECT_ROOT=\"$(cd \"$(dirname \"$0\")\"/../.. && pwd)\"\n\n# Clang-tidy 옵션:\n# -header-filter : 진단을 프로젝트 파일로 제한하여, 사실상\n# build/_deps 및 기타 외부 라이브러리를 건너뜁니다.\nHEADER_FILTER_REGEX=\"^${PROJECT_ROOT}/(include|source|executables|tests)/\"\nCLANG_TIDY_OPTS=\"-header-filter=${HEADER_FILTER_REGEX}\"\n\n# --- 주요 로직 ---\n\nmain() {\n # ... (이전 단계에서 정의된 루프)\n}\n\n# ... (스크립트 실행)\n```\n\n---\n\n### 단계 4: 분석 실행에 대한 요약 출력\n\n#### 1. 최종 요약 구현 및 표시\n\n이 조치는 스크립트 실행 마지막에 깔끔하고 읽기 쉬운 보고서를 제공하기 위해 전용 `print_summary` 함수를 생성합니다. 이 함수는 몇 개의 파일이 확인되었는지 명확하게 명시하여 사용자 경험을 향상시킵니다. 또한 `clang-tidy`가 자동으로 수정을 적용했는지(`.clang-tidy`에서 구성된 기능) 감지하는 로직을 추가하고, 사용자에게 알리며, 변경 사항을 표시합니다. 이 요약은 개발자가 분석 실행의 결과를 신속하게 파악할 수 있도록 보장합니다.\n\n**파일**: `scripts/executables/run_static_analysis.sh`\n\n```bash\n# ... (요약 전 주요 로직)\n\n print_summary \"$total_count\"\n\n if [ $overall_status -ne 0 ]; then\n # ...\n fi\n exit $overall_status\n}\n\n# --- 헬퍼 함수 ---\n\nprint_summary() {\n local total_count=$1\n local COLOR_GREEN='\\x1b[32m'\n local COLOR_RESET='\\x1b[0m'\n\n printf \"\\\\n%b=====================================%b\\\\n\" \"$COLOR_GREEN\" \"$COLOR_RESET\"\n printf \"%b Clang-Tidy 요약 %b\\\\n\" \"$COLOR_GREEN\" \"$COLOR_RESET\"\n printf \"%b=====================================%b\\\\n\" \"$COLOR_GREEN\" \"$COLOR_RESET\"\n printf \" 총 확인된 파일 수: %s\\\\n\" \"$total_count\"\n printf \"%b이슈가 발견되지 않았습니다.%b\\\\n\" \"$COLOR_GREEN\" \"$COLOR_RESET\"\n printf \"%b=====================================%b\\\\n\\\\n\" \"$COLOR_GREEN\" \"$COLOR_RESET\"\n}\n\n# --- 스크립트 실행 ---\nmain\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n다음 단계는 프로젝트가 클론되었고 C++ 툴체인(`clang` 및 `clang-tidy` 포함)이 시스템 `PATH`에서 사용 가능하다고 가정합니다.\n\n1. **실행 권한 부여:**\n 프로젝트 루트로 이동하여 새 스크립트를 실행 가능하게 만듭니다.\n\n ```bash\n chmod +x scripts/executables/run_static_analysis.sh\n ```\n\n2. **컴파일 데이터베이스 생성:**\n CMake로 프로젝트를 구성하여 `clang-tidy`에 필요한 `compile_commands.json` 파일을 생성합니다.\n\n ```bash\n # 프로젝트 루트 디렉터리에서\n cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON\n ```\n\n3. **스크립트 실행:**\n 스크립트를 수동으로 실행하여 특정 소스 파일을 대상으로 합니다.\n\n ```bash\n # 이 명령은 PATH에서 clang-tidy를 찾아 단일 소스 파일을 대상으로 합니다\n ./scripts/executables/run_static_analysis.sh $(which clang-tidy) build/ source/math/add.cpp\n ```\n\n### 4.2. 예상 결과\n\n깨끗한 파일에 대해 검증 단계를 실행한 후, 출력은 하나의 파일이 확인되었고 이슈가 발견되지 않았음을 나타내야 합니다. 스크립트는 종료 코드 `0`으로 종료해야 합니다.\n\n```\n[ 1/ 1] 확인 중 source/math/add.cpp\n\n=====================================\n Clang-Tidy 요약\n=====================================\n 총 확인된 파일 수: 1\n이슈가 발견되지 않았습니다.\n=====================================\n\n```\n","CMake 타겟에서 호출할 수 있는 `run_static_analysis.sh` 스크립트.",[1475,1478,1480,1482],{"_24":1476,"_83":39,"_84":1477,"_85":61},"clang-tidy 실행 파일, 빌드 경로, 파일 목록을 인수로 받는 스크립트.",22,{"_24":1479,"_83":39,"_84":1477,"_85":88},"각 파일에 대해 `clang-tidy`를 실행하는 로직.",{"_24":1481,"_83":39,"_84":1477,"_85":91},"외부 헤더의 경고를 억제하는 필터링 옵션.",{"_24":1483,"_83":39,"_84":1477,"_85":94},"분석 실행의 요약 출력.","모든 프로젝트 소스 파일에 `clang-tidy`를 실행하는 셸 스크립트.",{"_22":1486,"_24":1487,"_75":1488,"_77":1489,"_79":1490,"_51":1500,"_42":99},"task-1750999825730","Doxygen 구성 템플릿","# 작업: Doxygen 설정 템플릿\n\n> **에픽**: 자동화된 개발자 도구\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: API 문서를 생성하기 위한 Doxygen 설정 템플릿 파일.\n- **근거**: 이 작업은 Doxygen 문서 생성기를 위한 표준화된, 프로젝트 전반의 설정을 수립합니다. CMake 플레이스홀더가 포함된 템플릿 파일(`doxyfile.in`)을 생성함으로써 빌드 시스템이 프로젝트 이름, 버전, 소스 경로와 같은 프로젝트별 세부 정보를 자동으로 주입할 수 있게 합니다. 이는 문서화 프로세스를 자동화하고, 일관성을 보장하며, 문서 생성을 개발 워크플로우에 긴밀하게 통합하여 높은 개발자 생산성이라는 프로젝트 목표에 부합합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: `assets` 디렉터리에 CMake 변수 플레이스홀더가 포함된 `doxyfile.in` 파일.\n- **명세**:\n - `assets/doxyfile.in`이라는 새 파일이 생성됩니다.\n - 이 파일에는 동적 설정을 위한 CMake 플레이스홀더가 포함됩니다: `@PROJECT_NAME@`, `@PROJECT_VERSION@`, `@PROJECT_DESCRIPTION@`, `@DOXYGEN_INPUT@`, `@DOXYGEN_OUTPUT_DIRECTORY@`, `@PROJECT_SOURCE_DIR@`.\n - Graphviz (`dot`) 통합이 활성화됩니다 (`HAVE_DOT = YES`).\n - 특별 목록 (TODO, BUG, TEST) 생성이 활성화됩니다 (`GENERATE_TODOLIST = YES` 등).\n - 소스 코드 브라우징이 활성화됩니다 (`SOURCE_BROWSER = YES`).\n - 출력 형식은 HTML과 LaTeX로 구성됩니다.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── assets/\n# └── doxyfile.in <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 `doxyfile.in` 템플릿이 빌드 시스템 내에서 문서를 생성하는 데 어떻게 사용되는지 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph 빌드 설정 시간\n CMake[\"CMakeLists.txt\"] -- \"읽기\" --> DoxyfileIn[\"assets/doxyfile.in
(템플릿)\"];\n CMake -- \"@VARS@ 치환\" --> ConfigureFile[\"configure_file()\"];\n ConfigureFile -- \"생성\" --> DoxyfileOut[\"build/Doxyfile
(최종 설정)\"];\n end\n\n subgraph 빌드 실행 시간\n Dev[\"개발자\"] -- \"make create_documentations 실행\" --> Make;\n Make -- \"실행\" --> Doxygen[\"Doxygen 도구\"];\n Doxygen -- \"읽기\" --> DoxyfileOut;\n Doxygen -- \"스캔\" --> SourceFiles[\"프로젝트 소스 파일\"];\n SourceFiles --> Doxygen;\n Doxygen -- \"생성\" --> Docs[\"HTML/LaTeX 문서\"];\n end\n```\n\n### 1.3. 인수 기준\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] 프로젝트 설정 플레이스홀더 (`@PROJECT_NAME@`, `@PROJECT_VERSION@`).\n- [ ] 입/출력 경로 플레이스홀더 (`@DOXYGEN_INPUT@`, `@DOXYGEN_OUTPUT_DIRECTORY@`).\n- [ ] Graphviz/dot을 통한 그래프 생성을 위한 설정.\n- [ ] 소스 브라우징 및 특별 목록(TODO, BUG) 생성을 위한 설정.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 계층형 CMake 빌드 시스템을 갖춘 모듈식 프로젝트 템플릿\n- **관련 주요 구성 요소**:\n - **품질 보증 도구 체인**: 이 작업은 문서화 및 코드 품질의 핵심 도구인 Doxygen의 설정 파일을 제공함으로써 이 구성 요소에 직접 기여합니다.\n - **모듈식 CMake 빌드 시스템**: 이 구성 요소는 `doxyfile.in` 템플릿을 사용합니다. 상위 수준의 CMake 함수(향후 작업에서 생성될 예정)는 `configure_file` 명령을 사용하여 이 템플릿을 처리하고, 플레이스홀더를 치환하여 최종 `Doxyfile`을 생성합니다. 이 파일은 사용자 정의 빌드 타겟(예: `make create_documentations`)을 만드는 데 사용됩니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `assets/doxyfile.in`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 기준**의 항목에 해당합니다. 각 `단계`는 일련의 세부적인 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공할 것입니다.\n\n---\n\n### 단계 1: 프로젝트 설정 플레이스홀더 (`@PROJECT_NAME@`, `@PROJECT_VERSION@`)\n\n#### 1. 프로젝트 메타데이터 플레이스홀더 설정\n\n이 작업은 Doxygen 설정에서 기본적인 프로젝트 식별 설정을 수립합니다. CMake 플레이스홀더(`@PROJECT_NAME@`, `@PROJECT_VERSION@`, `@PROJECT_DESCRIPTION@`)를 사용하면 생성된 문서의 제목과 버전 번호가 항상 중앙 `CMakeLists.txt` 프로젝트 정의와 동기화되도록 보장합니다. 이는 문서에 오래되거나 잘못된 정보가 포함되는 것을 방지합니다. `assets/doxyfile.in` 파일을 다음 내용으로 생성하세요.\n\n**파일**: `assets/doxyfile.in`\n\n```\n# Doxyfile 설정 (정리 및 최적화됨)\n# 이 파일은 doxygen_parameters.md 가이드를 기반으로 최적화되었습니다.\n\n# ---------------------------------------------------------------------------\n# I. 프로젝트 기본 설정\n# ---------------------------------------------------------------------------\nPROJECT_NAME = \"@PROJECT_NAME@\"\nPROJECT_NUMBER = \"@PROJECT_VERSION@\"\nPROJECT_BRIEF = \"@PROJECT_DESCRIPTION@\"\nOUTPUT_LANGUAGE = English\n```\n\n---\n\n### 단계 2: 입/출력 경로 플레이스홀더 (`@DOXYGEN_INPUT@`, `@DOXYGEN_OUTPUT_DIRECTORY@`)\n\n#### 1. 동적 경로 플레이스홀더 정의\n\n이 작업은 CMake 플레이스홀더를 사용하여 Doxygen의 핵심 입출력 위치를 설정합니다. `INPUT = @DOXYGEN_INPUT@`는 빌드 시스템이 모든 소스 및 포함 디렉터리 목록을 동적으로 전달할 수 있게 합니다. `OUTPUT_DIRECTORY = @DOXYGEN_OUTPUT_DIRECTORY@`는 생성된 모든 파일을 지정된 빌드 하위 디렉터리로 보내 소스 트리를 깨끗하게 유지합니다. `STRIP_FROM_PATH = @PROJECT_SOURCE_DIR@`는 문서의 파일 목록에서 절대 프로젝트 경로를 제거하여 깨끗하고 상대적인 경로를 만듭니다.\n\n**파일**: `assets/doxyfile.in`\n\n```\n...\nOUTPUT_DIRECTORY = \"@DOXYGEN_OUTPUT_DIRECTORY@\"\n...\n# ---------------------------------------------------------------------------\n# II. 소스 입력 및 분석 설정\n# ---------------------------------------------------------------------------\nINPUT = @DOXYGEN_INPUT@\nRECURSIVE = YES\nFILE_PATTERNS = *.cpp *.h *.hpp\n...\n# ---------------------------------------------------------------------------\n# VI. 고급 사용자 정의 설정\n# ---------------------------------------------------------------------------\n...\nSTRIP_FROM_PATH = @PROJECT_SOURCE_DIR@\n...\n```\n\n---\n\n### 단계 3: Graphviz/dot을 통한 그래프 생성을 위한 설정\n\n#### 1. Graphviz 기반 다이어그램 생성 활성화\n\n이 작업은 Doxygen이 Graphviz `dot` 도구와 통합하여 시각적 다이어그램을 생성하도록 활성화합니다. `HAVE_DOT`, `CALL_GRAPH` 및 관련 옵션을 활성화하면 클래스 계층 구조, 호출 그래프 및 디렉터리 의존성 그래프가 생성됩니다. 이러한 다이어그램은 소프트웨어 아키텍처와 코드 관계의 이해도를 크게 향상시킵니다. `INTERACTIVE_SVG` 옵션은 HTML 출력에서 사용자 경험을 향상시킵니다.\n\n**파일**: `assets/doxyfile.in`\n\n```\n...\n# ---------------------------------------------------------------------------\n# IV. 다이어그램 및 그래프 설정 (Graphviz)\n# ---------------------------------------------------------------------------\nHAVE_DOT = YES\nUML_LOOK = YES\nGRAPHICAL_HIERARCHY = YES\nDIRECTORY_GRAPH = YES\nCALL_GRAPH = YES\nCALLER_GRAPH = YES\nMAX_DOT_GRAPH_DEPTH = 5\nDOT_IMAGE_FORMAT = svg\nINTERACTIVE_SVG = YES\n...\n```\n\n---\n\n### 단계 4: 소스 브라우징 및 특별 목록(TODO, BUG) 생성을 위한 설정\n\n#### 1. 특별 목록 생성 활성화\n\n이 작업은 Doxygen이 소스 코드에서 `\\todo`, `\\bug`, `\\test`와 같은 특별한 명령을 스캔하도록 설정합니다. `GENERATE_TODOLIST`, `GENERATE_BUGLIST`, `GENERATE_TESTLIST`를 활성화하면 이러한 주석들이 문서 내의 전용 페이지로 집계됩니다. 이를 통해 보류 중인 작업, 알려진 문제 및 테스트 케이스에 대한 중앙 집중식 뷰를 제공하며, 관련 코드에 직접 연결됩니다.\n\n**파일**: `assets/doxyfile.in`\n\n```\n...\n# ---------------------------------------------------------------------------\n# VII. 특별 목록 생성 옵션\n# ---------------------------------------------------------------------------\nGENERATE_TODOLIST = YES\nGENERATE_TESTLIST = YES\nGENERATE_BUGLIST = YES\nGENERATE_DEPRECATEDLIST= YES\n...\n```\n\n#### 2. 소스 코드 브라우징 활성화\n\n이 작업은 Doxygen이 생성된 문서 내에 탐색 가능한 버전의 소스 파일을 포함하도록 설정합니다. `SOURCE_BROWSER = YES`는 개발자가 API 문서에서 구현 파일로 직접 클릭하여 이동할 수 있게 하여 귀중한 컨텍스트를 제공합니다. 이는 깊이 통합되고 독립적인 문서 번들을 생성합니다.\n\n**파일**: `assets/doxyfile.in`\n\n```\n...\n# ---------------------------------------------------------------------------\n# VIII. 소스 브라우징 옵션\n# ---------------------------------------------------------------------------\nSOURCE_BROWSER = YES\nINLINE_SOURCES = YES\nSTRIP_CODE_COMMENTS = YES\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n작업을 검증하기 위해 개발자는 CMake 빌드 시스템이 수행할 작업을 시뮬레이션해야 합니다. 이는 검증 목적으로 최소한의 `CMakeLists.txt`가 임시로 생성되고 `create_documentations` 타겟이 존재한다고 가정합니다.\n\n1. **파일 생성 확인**: `assets/doxyfile.in` 파일이 존재하고 그 내용이 구현 명세와 일치하는지 확인합니다.\n\n2. **프로젝트 설정**: 빌드 디렉터리에서 CMake 설정 단계를 실행합니다.\n\n ```bash\n mkdir -p build && cd build\n cmake ..\n ```\n\n3. **생성된 Doxyfile 검사**: 설정 후, `build/` 디렉터리에 `Doxyfile`이 생성되어야 합니다. 파일을 열어 `@PROJECT_NAME@` 및 `@DOXYGEN_INPUT@`과 같은 플레이스홀더가 CMake 설정의 실제 값으로 대체되었는지 확인합니다.\n\n4. **문서화 타겟 실행**: 문서 생성을 위한 사용자 정의 빌드 타겟을 실행합니다.\n\n ```bash\n # 'build' 디렉터리에서\n make create_documentations\n ```\n\n5. **출력 확인**: 문서 출력 디렉터리(예: `build/docs/doxygen/html`)와 메인 `index.html` 파일이 생성되었는지 확인합니다.\n\n### 4.2. 예상 결과\n\n- `cmake ..` 명령이 오류 없이 완료되어야 합니다.\n- `make create_documentations` 명령이 실행되고 Doxygen이 성공적으로 실행되었음을 나타내는 다음과 유사한 출력을 생성해야 합니다:\n\n ```\n [100%] Generating API documentation with Doxygen\n Searching for files in directory /path/to/project/include\n Searching for files in directory /path/to/project/source\n ...\n Generating docs for file add.h...\n Generating docs for file subtract.h...\n ...\n Generating call graph...\n Generating caller graph...\n [100%] Built target create_documentations\n ```\n\n- `build/docs/doxygen/html` 디렉터리가 존재해야 하며 생성된 HTML 문서 파일들을 포함해야 합니다. 웹 브라우저에서 `build/docs/doxygen/html/index.html`을 열면 프로젝트의 문서 홈페이지가 표시되어야 합니다.\n","`assets` 디렉토리에 CMake 변수 플레이스홀더를 포함하는 `doxyfile.in` 파일.",[1491,1494,1496,1498],{"_24":1492,"_83":39,"_84":1493,"_85":61},"프로젝트 설정 플레이스홀더 (`@PROJECT_NAME@`, `@PROJECT_VERSION@`).",23,{"_24":1495,"_83":39,"_84":1493,"_85":88},"입력/출력 경로 플레이스홀더 (`@DOXYGEN_INPUT@`, `@DOXYGEN_OUTPUT_DIRECTORY@`).",{"_24":1497,"_83":39,"_84":1493,"_85":91},"Graphviz/dot을 통한 그래프 생성 구성.",{"_24":1499,"_83":39,"_84":1493,"_85":94},"소스 브라우징 및 특수 목록(TODO, BUG) 생성을 위한 설정.","API 문서 생성을 위해 Doxygen을 구성하는 템플릿 파일.",[1502,1504],{"_28":29,"_26":1503},499000,{"_28":482,"_26":1115},[1506],{"_22":1507,"_488":1113,"_489":490,"_26":1508,"_492":1509,"_494":1510,"_496":812,"_42":99},"daf8ffd6-e6e3-46ca-be72-e54e85b10ba9",255000,98,"2025-06-27T07:18:00.000Z",{"_22":1512,"_24":1120,"_26":1503,"_28":29,"_30":31,"_32":1116,"_34":1513,"_36":1514,"_38":39,"_40":1515,"_484":1667},"c083ad81-a11a-4b53-b3fd-ac0d25328984","2025-06-26T16:49:59.291Z","2025-06-27T07:16:16.854Z",{"_22":1116,"_24":1120,"_42":1121,"_44":31,"_45":46,"_47":1122,"_49":1123,"_51":1124,"_53":1125,"_55":39,"_56":1126,"_58":59,"_60":61,"_62":61,"_63":1516,"_70":1517,"_478":1501},[1128,1129,1130,1131],[1518,1524,1530,1536,1542,1548,1554,1560,1566,1572,1578,1585,1591,1597,1603,1611,1617,1623,1630,1636,1642,1649,1655,1661],{"_22":1134,"_24":1135,"_75":1136,"_77":1137,"_79":1519,"_51":1147,"_42":99},[1520,1521,1522,1523],{"_24":1140,"_83":39,"_84":61,"_85":61},{"_24":1142,"_83":39,"_84":61,"_85":88},{"_24":1144,"_83":39,"_84":61,"_85":91},{"_24":1146,"_83":39,"_84":61,"_85":94},{"_22":1149,"_24":1150,"_75":1151,"_77":1152,"_79":1525,"_51":1162,"_42":99},[1526,1527,1528,1529],{"_24":1155,"_83":39,"_84":88,"_85":61},{"_24":1157,"_83":39,"_84":88,"_85":88},{"_24":1159,"_83":39,"_84":88,"_85":91},{"_24":1161,"_83":39,"_84":88,"_85":94},{"_22":1164,"_24":296,"_75":1165,"_77":1166,"_79":1531,"_51":1176,"_42":99},[1532,1533,1534,1535],{"_24":1169,"_83":39,"_84":91,"_85":61},{"_24":1171,"_83":39,"_84":91,"_85":88},{"_24":1173,"_83":39,"_84":91,"_85":91},{"_24":1175,"_83":39,"_84":91,"_85":94},{"_22":1178,"_24":1179,"_75":1180,"_77":1181,"_79":1537,"_51":1191,"_42":99},[1538,1539,1540,1541],{"_24":1184,"_83":39,"_84":94,"_85":61},{"_24":1186,"_83":39,"_84":94,"_85":88},{"_24":1188,"_83":39,"_84":94,"_85":91},{"_24":1190,"_83":39,"_84":94,"_85":94},{"_22":1193,"_24":1194,"_75":1195,"_77":1196,"_79":1543,"_51":1206,"_42":99},[1544,1545,1546,1547],{"_24":1199,"_83":39,"_84":97,"_85":61},{"_24":1201,"_83":39,"_84":97,"_85":88},{"_24":1203,"_83":39,"_84":97,"_85":91},{"_24":1205,"_83":39,"_84":97,"_85":94},{"_22":1208,"_24":1209,"_75":1210,"_77":1211,"_79":1549,"_51":1221,"_42":99},[1550,1551,1552,1553],{"_24":1214,"_83":39,"_84":176,"_85":61},{"_24":1216,"_83":39,"_84":176,"_85":88},{"_24":1218,"_83":39,"_84":176,"_85":91},{"_24":1220,"_83":39,"_84":176,"_85":94},{"_22":1223,"_24":1224,"_75":1225,"_77":1226,"_79":1555,"_51":1236,"_42":99},[1556,1557,1558,1559],{"_24":1229,"_83":39,"_84":192,"_85":61},{"_24":1231,"_83":39,"_84":192,"_85":88},{"_24":1233,"_83":39,"_84":192,"_85":91},{"_24":1235,"_83":39,"_84":192,"_85":94},{"_22":1238,"_24":1239,"_75":1240,"_77":1241,"_79":1561,"_51":1251,"_42":99},[1562,1563,1564,1565],{"_24":1244,"_83":39,"_84":212,"_85":61},{"_24":1246,"_83":39,"_84":212,"_85":88},{"_24":1248,"_83":39,"_84":212,"_85":91},{"_24":1250,"_83":39,"_84":212,"_85":94},{"_22":1253,"_24":1254,"_75":1255,"_77":1256,"_79":1567,"_51":1266,"_42":99},[1568,1569,1570,1571],{"_24":1259,"_83":39,"_84":230,"_85":61},{"_24":1261,"_83":39,"_84":230,"_85":88},{"_24":1263,"_83":39,"_84":230,"_85":91},{"_24":1265,"_83":39,"_84":230,"_85":94},{"_22":1268,"_24":1269,"_75":1270,"_77":1271,"_79":1573,"_51":1281,"_42":99},[1574,1575,1576,1577],{"_24":1274,"_83":39,"_84":248,"_85":61},{"_24":1276,"_83":39,"_84":248,"_85":88},{"_24":1278,"_83":39,"_84":248,"_85":91},{"_24":1280,"_83":39,"_84":248,"_85":94},{"_22":1283,"_24":1284,"_75":1285,"_77":1286,"_79":1579,"_51":1298,"_42":99},[1580,1581,1582,1583,1584],{"_24":1289,"_83":39,"_84":266,"_85":61},{"_24":1291,"_83":39,"_84":266,"_85":88},{"_24":1293,"_83":39,"_84":266,"_85":91},{"_24":1295,"_83":39,"_84":266,"_85":94},{"_24":1297,"_83":39,"_84":266,"_85":97},{"_22":1300,"_24":1301,"_75":1302,"_77":1303,"_79":1586,"_51":1313,"_42":99},[1587,1588,1589,1590],{"_24":1306,"_83":39,"_84":284,"_85":61},{"_24":1308,"_83":39,"_84":284,"_85":88},{"_24":1310,"_83":39,"_84":284,"_85":91},{"_24":1312,"_83":39,"_84":284,"_85":94},{"_22":1315,"_24":1316,"_75":1317,"_77":1318,"_79":1592,"_51":1328,"_42":99},[1593,1594,1595,1596],{"_24":1321,"_83":39,"_84":302,"_85":61},{"_24":1323,"_83":39,"_84":302,"_85":88},{"_24":1325,"_83":39,"_84":302,"_85":91},{"_24":1327,"_83":39,"_84":302,"_85":94},{"_22":1330,"_24":1331,"_75":1332,"_77":1333,"_79":1598,"_51":1343,"_42":99},[1599,1600,1601,1602],{"_24":1336,"_83":39,"_84":320,"_85":61},{"_24":1338,"_83":39,"_84":320,"_85":88},{"_24":1340,"_83":39,"_84":320,"_85":91},{"_24":1342,"_83":39,"_84":320,"_85":94},{"_22":1345,"_24":1346,"_75":1347,"_77":1348,"_79":1604,"_51":1362,"_42":99},[1605,1606,1607,1608,1609,1610],{"_24":1351,"_83":39,"_84":338,"_85":61},{"_24":1353,"_83":39,"_84":338,"_85":88},{"_24":1355,"_83":39,"_84":338,"_85":91},{"_24":1357,"_83":39,"_84":338,"_85":94},{"_24":1359,"_83":39,"_84":338,"_85":97},{"_24":1361,"_83":39,"_84":338,"_85":176},{"_22":1364,"_24":1365,"_75":1366,"_77":1367,"_79":1612,"_51":1377,"_42":99},[1613,1614,1615,1616],{"_24":1370,"_83":39,"_84":356,"_85":61},{"_24":1372,"_83":39,"_84":356,"_85":88},{"_24":1374,"_83":39,"_84":356,"_85":91},{"_24":1376,"_83":39,"_84":356,"_85":94},{"_22":1379,"_24":1380,"_75":1381,"_77":1382,"_79":1618,"_51":1391,"_42":99},[1619,1620,1621,1622],{"_24":1385,"_83":39,"_84":374,"_85":61},{"_24":1372,"_83":39,"_84":374,"_85":88},{"_24":1388,"_83":39,"_84":374,"_85":91},{"_24":1390,"_83":39,"_84":374,"_85":94},{"_22":1393,"_24":1394,"_75":1395,"_77":1396,"_79":1624,"_51":1408,"_42":99},[1625,1626,1627,1628,1629],{"_24":1399,"_83":39,"_84":392,"_85":61},{"_24":1401,"_83":39,"_84":392,"_85":88},{"_24":1403,"_83":39,"_84":392,"_85":91},{"_24":1405,"_83":39,"_84":392,"_85":94},{"_24":1407,"_83":39,"_84":392,"_85":97},{"_22":1410,"_24":1411,"_75":1412,"_77":1413,"_79":1631,"_51":1423,"_42":99},[1632,1633,1634,1635],{"_24":1416,"_83":39,"_84":410,"_85":61},{"_24":1418,"_83":39,"_84":410,"_85":88},{"_24":1420,"_83":39,"_84":410,"_85":91},{"_24":1422,"_83":39,"_84":410,"_85":94},{"_22":1425,"_24":1426,"_75":1427,"_77":1428,"_79":1637,"_51":1436,"_42":99},[1638,1639,1640,1641],{"_24":1431,"_83":39,"_84":428,"_85":61},{"_24":1418,"_83":39,"_84":428,"_85":88},{"_24":1434,"_83":39,"_84":428,"_85":91},{"_24":1422,"_83":39,"_84":428,"_85":94},{"_22":1438,"_24":1439,"_75":1440,"_77":1441,"_79":1643,"_51":1453,"_42":99},[1644,1645,1646,1647,1648],{"_24":1444,"_83":39,"_84":446,"_85":61},{"_24":1446,"_83":39,"_84":446,"_85":88},{"_24":1448,"_83":39,"_84":446,"_85":91},{"_24":1450,"_83":39,"_84":446,"_85":94},{"_24":1452,"_83":39,"_84":446,"_85":97},{"_22":1455,"_24":1456,"_75":1457,"_77":1458,"_79":1650,"_51":1468,"_42":99},[1651,1652,1653,1654],{"_24":1461,"_83":39,"_84":466,"_85":61},{"_24":1463,"_83":39,"_84":466,"_85":88},{"_24":1465,"_83":39,"_84":466,"_85":91},{"_24":1467,"_83":39,"_84":466,"_85":94},{"_22":1470,"_24":1471,"_75":1472,"_77":1473,"_79":1656,"_51":1484,"_42":99},[1657,1658,1659,1660],{"_24":1476,"_83":39,"_84":1477,"_85":61},{"_24":1479,"_83":39,"_84":1477,"_85":88},{"_24":1481,"_83":39,"_84":1477,"_85":91},{"_24":1483,"_83":39,"_84":1477,"_85":94},{"_22":1486,"_24":1487,"_75":1488,"_77":1489,"_79":1662,"_51":1500,"_42":99},[1663,1664,1665,1666],{"_24":1492,"_83":39,"_84":1493,"_85":61},{"_24":1495,"_83":39,"_84":1493,"_85":88},{"_24":1497,"_83":39,"_84":1493,"_85":91},{"_24":1499,"_83":39,"_84":1493,"_85":94},[1668],{"_22":1669,"_488":1512,"_489":1109,"_26":1670,"_492":1110,"_494":1111,"_496":812,"_42":99},"d8dcf3e8-8381-4893-8133-a7c394f9046a",424150,{"_22":1672,"_24":1673,"_26":1674,"_28":482,"_30":31,"_32":1675,"_34":1676,"_36":1677,"_38":817,"_40":1678,"_484":2246},"8510f0c5-f843-4d79-a87d-2d785681df58","TitanCore: 견고하고 비동기적인 C++ 애플리케이션 설계 (Source Code)",200000,"d0858abc-86a6-42e2-be13-822e53b2c189","2025-07-05T14:08:25.766Z","2025-07-05T14:58:55.653Z",{"_22":1675,"_24":1679,"_42":1680,"_44":31,"_45":46,"_47":1681,"_49":1682,"_51":1683,"_53":1684,"_55":39,"_56":1685,"_58":59,"_60":61,"_62":61,"_63":1686,"_70":1691,"_478":2242},"TitanCore: 견고하고 비동기적인 C++ 애플리케이션 설계","C++ 동시성이라는 바퀴를 더 이상 재발명하지 마세요. 이 프로젝트는 고성능 비동기 애플리케이션 구축을 위한 프로덕션 수준의 핵심 프레임워크를 제공합니다. 견고한 스레드 풀, 주기적 작업 스케줄러, 데이터 파이프라인 오케스트레이터를 통해 여러분은 고유한 애플리케이션 로직에만 집중하고, 복잡한 시스템을 자신 있게 출시할 수 있습니다.","수년간 모든 복잡한 C++ 프로젝트는 핵심 인프라를 처음부터 구축하는, 좌절스러운 의식으로 시작되었습니다. 저는 끊임없이 또 다른 스레드 풀, 맞춤형 작업 스케줄러, 새로운 로거를 작성하고 있었습니다. 애플리케이션 로직의 첫 줄을 작성하기도 전에 모든 프로젝트에서 한 달간 '기반 다지기 세금'을 내는 기분이었습니다. 이런 반복은 비효율적일 뿐만 아니라, 미묘하고 진단하기 어려운 버그의 온상이었습니다.\n\n> 특히 힘들었던 한 프로젝트가 끝난 후 깨달음을 얻었습니다. 저는 약간의 변형만 있을 뿐, 계속해서 똑같은 아키텍처 문제를 풀고 있다는 사실을 깨달았습니다. 만약 이 문제를 *단 한 번에*, 제대로 해결한다면 어떨까?\n\n바로 그때 이 프레임워크를 설계하기 시작했습니다. 시간과 파일시스템에 대한 추상화와 같이 가장 근본적이고 나눌 수 없는 구성 요소부터 시작했습니다. 거기서부터 시스템의 심장부인 견고하고 스레드에 안전한 `ThreadPool`을 구축했습니다. 그 기반 위에 `Scheduler`와 타입에 안전한 `Pipeline` 오케스트레이터를 신중하게 쌓아 올렸습니다. 목표는 다중 스트림 SLAM 시스템처럼 믿을 수 없을 만큼 복잡한 것을 구축하는 과정을 **선언적이고 관리하기 쉽게** 만드는 것이었습니다. 포괄적인 테스트 스위트는 나중에 추가된 것이 아닙니다. 시스템의 신뢰성을 증명하겠다는 저의 약속이었습니다.\\n\\n이제 새로운 프로젝트를 시작하는 것은 지치는 일이 아니라 활력이 넘칩니다. 몇 달이 아닌 몇 분 만에 정교한 동시성 아키텍처를 구성할 수 있습니다. 실시간 데이터 처리 시스템의 프로토타입을 만드는 것은 몇 시간이면 충분합니다. 이 프레임워크는 제 워크플로우를 근본적으로 바꾸어 놓았고, 여러분도 동일한 가속을 경험할 수 있도록 만들었습니다.\",\n ","# 프로젝트 명세서: readable-code-cpp-core-framework\n\n## 1. 프로젝트 정의\n\n### 1.1. 주요 목표\n\n- 복잡한 애플리케이션을 위한 기본 유틸리티와 고성능 동시 데이터 처리 시스템을 갖춘 C++ 코어 프레임워크를 개발합니다.\n\n### 1.2. 핵심 기능\n\n- 로깅, YAML 설정, 파일 시스템 I/O, 고정밀 시간을 위한 재사용 가능한 코어 유틸리티\n- 동시 작업 실행을 위한 강력한 스레드 풀\n- 주기적인 작업 관리를 위한 상위 레벨 스케줄러\n- 복잡한 비동기 데이터 처리 파이프라인 구성\n- 포괄적인 단위, 통합, 종단 간 테스트 시스템\n\n### 1.3. 결과물\n\n- 다른 애플리케이션에 통합할 수 있는 재사용 가능한 C++ 코어 프레임워크 라이브러리\n- `include/` 디렉터리의 헤더 파일을 통한 완전한 공개 API\n- 컴포넌트의 정확성을 검증하고 라이브러리 사용법을 시연하는 포괄적인 테스트 스위트\n\n## 2. 시스템 아키텍처\n\n### 2.1. 아키텍처 패턴\n\n- **모듈식 코어 프레임워크**: 계층적 아키텍처로, 독립적이고 재사용 가능한 코어 유틸리티(예: Logging, Config) 세트를 제공합니다. 이는 더 높은 수준의 상호 연결된 동시성 기본 요소(예: ThreadPool, Scheduler, Pipeline)의 기반이 됩니다.\n\n### 2.2. 의존성 다이어그램\n\n- 개발 에픽 간의 빌드 순서 의존성을 시각화한 다이어그램입니다. 기반 유틸리티는 이를 사용하는 상위 수준 컴포넌트보다 먼저 완성되어야 합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"기반 유틸리티\"\n direction LR\n FPA[\"파일 시스템 경로
추상화\"]\n TDR[\"시간 간격
표현\"]\n PNR[\"파이프라인 노드 결과
및 제어 흐름\"]\n SEE[\"스케줄러
실행 엔트리\"]\n end\n \n subgraph \"코어 동시성 엔진\"\n CTPE[\"코어 스레드 풀
실행기\"]\n end\n\n subgraph \"상위 레벨 컴포넌트\"\n direction LR\n FIO[\"파일 입출력
작업\"]\n YCR[\"YAML 설정
리더\"]\n MSL[\"다중 싱크 로깅
프레임워크\"]\n HPT[\"고정밀
타임스탬핑\"]\n TPN[\"타입 소거된
파이프라인 노드\"]\n PTS[\"주기적 작업
스케줄러\"]\n ADPO[\"비동기 데이터
파이프라인 오케스트레이터\"]\n end\n\n subgraph \"검증\"\n CSV[\"포괄적인
시스템 검증\"]\n end\n\n FPA --> FIO\n FPA --> YCR\n FPA --> MSL\n TDR --> HPT\n PNR --> TPN\n CTPE --> PTS\n CTPE --> ADPO\n SEE --> PTS\n TPN --> ADPO\n\n FIO --> CSV\n YCR --> CSV\n MSL --> CSV\n HPT --> CSV\n PTS --> CSV\n ADPO --> CSV\n```\n\n### 2.3. 프로그램 흐름\n\n- 스케줄링된 파이프라인 기반 작업의 상위 수준 오케스트레이션을 보여주는 시퀀스 다이어그램입니다. `Scheduler`는 타이밍을 관리하고, `ThreadPool`은 모든 비동기 작업에 대한 실행 컨텍스트를 제공합니다.\n\n```mermaid\n%%{ init: { \"sequence\": { \"htmlLabels\": true } } }%%\nsequenceDiagram\n participant App as \"애플리케이션\"\n participant Scheduler as \"스케줄러\"\n participant ThreadPool as \"스레드 풀\"\n participant Pipeline as \"파이프라인\"\n \n App->>Scheduler: \"AddTask(pipeline.RunCycle, 10Hz)\"\n App->>Scheduler: \"Start()\"\n \n loop 실행 루프\n Scheduler->>Scheduler: \"다음 작업 시간까지 대기\"\n Scheduler->>ThreadPool: \"작업 큐에 추가(pipeline.RunCycle)\"\n \n ThreadPool->>Pipeline: \"작업 실행: RunCycle()\"\n Pipeline->>ThreadPool: \"작업 큐에 추가(Node1.Execute)\"\n \n ThreadPool->>Pipeline: \"작업 실행: Node1.Execute()\"\n Pipeline->>ThreadPool: \"작업 큐에 추가(Node2.Execute)\"\n \n Note over ThreadPool, Pipeline: \"파이프라인의 모든 노드에 대해
실행이 계속됨\"\n end\n```\n\n### 2.4. 컴포넌트별 역할 및 책임\n\n- **ThreadPool**\n - **역할**: 기반이 되는 동시성 엔진.\n - **상호작용**: 워커 스레드 풀을 관리합니다. `Scheduler`나 `Pipeline` 같은 상위 레벨 컴포넌트가 제출한 비동기 작업을 실행합니다.\n\n- **Scheduler**\n - **역할**: 주기적 작업 관리자.\n - **상호작용**: 사용자가 정의한 정기적인 간격으로 공유 `ThreadPool`에 작업을 제출하여 실행합니다. `ExecutionEntry`를 사용해 작업 우선순위를 정합니다.\n\n- **Pipeline**\n - **역할**: 순차적 데이터 프로세서.\n - **상호작용**: `pipeline::Node`의 선형 시퀀스를 조율하고, 노드 간에 데이터를 전달합니다. 각 노드의 실행 작업을 공유 `ThreadPool`에 제출합니다.\n\n- **pipeline::Node**\n - **역할**: 단일, 타입 소거된 처리 단위.\n - **상호작용**: 애플리케이션 로직의 일부를 캡슐화합니다. `Pipeline`에 의해 `ThreadPool`에서 실행됩니다. 데이터와 `ControlFlow` 상태를 반환합니다.\n\n- **config::Reader**\n - **역할**: 시스템 설정 제공자.\n - **상호작용**: 시작 시 파일 시스템에서 YAML 파일을 로드하고 파싱하여 시스템 매개변수를 설정합니다.\n\n- **Logger**\n - **역할**: 이벤트 기록 유틸리티.\n - **상호작용**: 모든 컴포넌트가 상태 메시지, 경고, 오류를 다양한 싱크(예: 콘솔, 파일)에 기록할 수 있도록 전역적인 다중 레벨 인터페이스를 제공합니다.\n\n### 2.5. 기술 스택\n\n- **언어:**\n - C++\n- **프레임워크:**\n - C++ 표준 라이브러리 (filesystem, chrono)\n - YAML 파서 라이브러리\n\n## 3. 디렉터리 구조\n\n### 3.1. 개요\n\n- 이 구조는 공개 API(`include`), 비공개 구현(`source`), 검증 스위트(`tests`) 간의 관심사를 명확하게 분리합니다.\n\n### 3.2. 폴더 트리\n\n```bash\n/\n├── include/\n│ └── core/\n│ ├── concurrency/\n│ ├── config/\n│ ├── filesystem/\n│ └── time/\n├── source/\n│ ├── concurrency/\n│ ├── config/\n│ ├── filesystem/\n│ └── time/\n└── tests/\n ├── unit/\n ├── integration/\n └── e2e/\n```\n\n## 4. 실행 계획\n\n실행 계획은 기반이 되는 독립형 유틸리티(예: 파일 시스템, 시간 추상화) 생성을 우선순위로 둡니다. 그 다음 모든 상위 레벨 비동기 컴포넌트(`Scheduler`, `Pipeline`)가 구축되는 기반인 코어 동시성 엔진(`ThreadPool`)을 만듭니다. 마지막 단계는 이전에 구축된 모든 컴포넌트를 통합하고 테스트하여 시스템 전반의 정확성과 신뢰성을 보장하는 포괄적인 검증 에픽을 포함합니다.\n\n---\n\n### 에픽 1: 파일 시스템 경로 추상화\n\n- **목표:** 모든 파일 I/O의 전제 조건으로, 파일 시스템 경로 조작을 위한 간단하고 플랫폼 독립적인 클래스를 구축합니다.\n- **작업**\n - **1.1 파일 시스템 경로 클래스 인터페이스 정의:** 헤더 파일에 `core::filesystem::Path` 공개 API를 생성합니다.\n - **1.2 파일 시스템 경로 클래스 로직 구현:** `std::filesystem` 호출을 래핑하여 `Path` 클래스 메서드를 구현합니다.\n\n---\n\n### 에픽 2: 시간 간격 표현\n\n- **목표:** 시간 기반 계산 및 변환을 위한 고정밀 `Duration` 클래스를 정의합니다.\n- **작업**\n - **2.1 시간 간격 클래스 인터페이스 정의:** API와 비교 연산자를 포함하는 `core::time::Duration` 클래스 헤더를 생성합니다.\n - **2.2 시간 간격 클래스 로직 구현:** 시간 단위 간 변환을 위한 `Duration` 메서드를 구현합니다.\n\n---\n\n### 에픽 3: 코어 스레드 풀 실행기\n\n- **목표:** 비동기 작업을 실행하기 위한 기본적이고 스레드 안전한 워커 풀을 구현합니다.\n- **작업**\n - **3.1 스레드 풀 클래스 인터페이스 정의:** 공개 API와 내부 작업 큐 구조를 정의하는 `ThreadPool` 클래스 헤더를 생성합니다.\n - **3.2 스레드 풀 생명주기 및 작업 큐 추가 구현:** 스레드 풀의 생성자, 소멸자, 그리고 스레드 안전한 `EnqueueJob` 메서드를 구현합니다.\n - **3.3 워커 스레드 루프 구현:** 각 워커 스레드가 큐에서 작업을 가져와 실행하는 메인 루프를 구현합니다.\n\n---\n\n### 에픽 4: 파이프라인 노드 결과 및 제어 흐름\n\n- **목표:** 파이프라인 단계 간의 통신을 가능하게 하는 파이프라인 노드 출력의 표준 데이터 구조(`NodeResult`, `ControlFlow`)를 정의합니다.\n- **작업**\n - **4.1 NodeResult 및 ControlFlow 구조 정의:** `ControlFlow` 열거형과 `NodeResult` 구조체를 정의하는 헤더 전용 파일을 생성합니다.\n\n---\n\n### 에픽 5: 스케줄러 실행 엔트리\n\n- **목표:** 스케줄러가 다음 실행 시간을 기준으로 작업의 우선순위를 정할 수 있도록 `ExecutionEntry` 데이터 구조를 정의합니다.\n- **작업**\n - **5.1 ExecutionEntry 클래스 인터페이스 정의:** 데이터 멤버와 비교 연산자를 정의하는 `ExecutionEntry` 클래스 헤더를 생성합니다.\n - **5.2 ExecutionEntry 클래스 로직 구현:** `ExecutionEntry` 생성자와 메서드를 구현합니다.\n\n---\n\n### 에픽 6: 파일 입출력 작업\n\n- **목표:** 기본적인 읽기, 쓰기, 존재 확인 작업을 위한 고수준 `File` 유틸리티를 제공합니다.\n- **작업**\n - **6.1 파일 작업 클래스 인터페이스 정의:** I/O 메서드를 포함하는 `core::filesystem::File` 클래스 헤더를 생성합니다.\n - **6.2 파일 작업 로직 구현:** 표준 C++ 파일 스트림을 사용하여 `File` 클래스 메서드를 구현합니다.\n\n---\n\n### 에픽 7: YAML 설정 리더\n\n- **목표:** YAML 파일에서 설정 데이터를 로드하고 접근하기 위한 강력한 `Reader` 클래스를 구현합니다.\n- **작업**\n - **7.1 YAML 리더 클래스 인터페이스 정의:** pImpl 이디엄을 사용하여 YAML 라이브러리 세부 정보를 숨기는 `Reader` 클래스 헤더를 생성합니다.\n - **7.2 YAML 리더 비공개 구현:** `fkyaml` 라이브러리 로직을 래핑하는 비공개 `Implementation` 클래스를 구현합니다.\n - **7.3 YAML 리더 공개 메서드 로직 구현:** pImpl 인스턴스에 호출을 위임하는 `Reader`의 공개 메서드를 구현합니다.\n\n---\n\n### 에픽 8: 다중 싱크 로깅 프레임워크\n\n- **목표:** 파일과 같은 다양한 출력 싱크를 지원하는 유연한 다중 레벨 `Logger`를 구현합니다.\n- **작업**\n - **8.1 Logger 클래스 인터페이스 정의:** pImpl 이디엄을 사용하여 기반 로깅 라이브러리를 추상화하는 `Logger` 클래스 헤더를 생성합니다.\n - **8.2 spdlog를 사용한 Logger 비공개 구현:** `spdlog` 기능을 래핑하는 비공개 `Implementation` 클래스를 구현합니다.\n - **8.3 Logger 공개 메서드 로직 구현:** 로깅 호출을 pImpl 인스턴스에 위임하는 `Logger`의 공개 메서드를 구현합니다.\n\n---\n\n### 에픽 9: 고정밀 타임스탬핑\n\n- **목표:** 성능 측정을 가능하게 하는 고해상도 타임스탬프를 캡처하기 위한 `Stamp` 클래스를 구현합니다.\n- **작업**\n - **9.1 타임스탬프 클래스 인터페이스 정의:** 시간 캡처 API를 포함하는 `core::time::Stamp` 클래스 헤더를 생성합니다.\n - **9.2 타임스탬프 클래스 로직 구현:** `std::chrono`를 사용하여 시간을 캡처하고 차이를 계산하는 `Stamp` 클래스 메서드를 구현합니다.\n\n---\n\n### 에픽 10: 타입 소거된 파이프라인 노드\n\n- **목표:** 데이터 처리 파이프라인의 기본적이고 타입 안전한 구성 요소 역할을 하는 `Node` 클래스를 생성합니다.\n- **작업**\n - **10.1 파이프라인 노드 클래스 인터페이스 정의:** 프로듀서 및 트랜스포머 노드를 생성하기 위한 정적 팩토리를 포함하는 `Node` 클래스 헤더를 생성합니다.\n - **10.2 파이프라인 노드 로직 구현:** 안전한 작업 호출을 위해 런타임 타입 검사를 포함하는 `Node`의 `Execute` 메서드를 구현합니다.\n\n---\n\n### 에픽 11: 주기적 작업 스케줄러\n\n- **목표:** `ThreadPool`을 사용하여 지정된 간격으로 반복 작업을 실행하기 위한 고수준 `Scheduler`를 구현합니다.\n- **작업**\n - **11.1 주기적 스케줄러 클래스 인터페이스 정의:** 공개 API와 내부 데이터 구조를 정의하는 `Scheduler` 클래스 헤더를 생성합니다.\n - **11.2 스케줄러 작업 관리 구현:** 스케줄러의 작업 목록을 관리하기 위한 `AddTask` 및 `CancelTask`를 구현합니다.\n - **11.3 스케줄러 실행 루프 및 생명주기 구현:** 스케줄러의 실행을 제어하기 위한 메인 `Loop`, `Start`, `Stop` 메서드를 구현합니다.\n\n---\n\n### 에픽 12: 비동기 데이터 파이프라인 오케스트레이터\n\n- **목표:** `ThreadPool`에서 `Node` 시퀀스를 비동기적으로 관리하고 실행하는 `Pipeline` 클래스를 구현합니다.\n- **작업**\n - **12.1 파이프라인 오케스트레이터 클래스 인터페이스 정의:** 노드 관리 및 실행 메서드를 포함하는 `Pipeline` 클래스 헤더를 생성합니다.\n - **12.2 파이프라인 노드 관리 및 실행 사이클 구현:** 타입 불일치 검증을 포함하는 `AddNode`와 처리 시작을 위한 `RunCycle` 메서드를 구현합니다.\n - **12.3 비동기 노드 스케줄링 구현:** 스레드 풀의 작업 큐에 노드 작업을 재귀적으로 추가하는 비공개 `ScheduleNextNode` 메서드를 구현합니다.\n\n---\n\n### 에픽 13: 포괄적인 시스템 검증\n\n- **목표:** 프레임워크가 견고하고, 정확하며, 신뢰할 수 있도록 보장하기 위해 전체 단위, 통합, 종단 간 테스트 스위트를 개발합니다.\n- **작업**\n - **13.1 파일 시스템 및 설정 유틸리티에 대한 단위 테스트:** `Path`, `File`, `Reader` 컴포넌트를 독립적으로 검증합니다.\n - **13.2 시간 및 로깅 유틸리티에 대한 단위 및 통합 테스트:** `Duration`, `Stamp`, `Logger` 컴포넌트를 검증합니다.\n - **13.3 동시성 기본 요소에 대한 단위 테스트:** 기반이 되는 `ThreadPool` 및 `ExecutionEntry`의 정확성과 스레드 안전성을 검증합니다.\n - **13.4 파이프라인 및 스케줄러 프레임워크에 대한 단위 테스트:** 고수준 `Node`, `Pipeline`, `Scheduler` 컴포넌트를 검증합니다.\n - **13.5 종단 간 SLAM 시나리오 테스트:** 여러 동시 파이프라인을 갖춘 시뮬레이션된 실제 애플리케이션 환경에서 전체 프레임워크를 검증합니다.\n","> 내장된 동시성으로 복잡하고 고성능인 C++ 애플리케이션을 구축할 수 있는 확고한 기반을 제공합니다.\n\n이 프레임워크는 기반 시스템을 처음부터 구현하는 반복적이고 오류 발생 쉬운 작업을 없애기 위해 설계되었습니다. 자신만의 스레드 풀, 스케줄러, 또는 설정 파서를 작성하고 디버깅하는 데 몇 주를 소비하는 대신, 응집력 있고 모듈화된 툴킷을 사용할 수 있습니다. 고정밀 타이머부터 비동기 데이터 파이프라인에 이르기까지 각 구성 요소는 독립적으로 사용 가능하면서도 완벽하게 통합되도록 설계되어, 로보틱스, SLAM, 또는 실시간 데이터 프로세서와 같은 정교한 애플리케이션을 안정적이고 예측 가능한 코어로 구축할 수 있게 해줍니다.","### 제공 사항\n\n- 깔끔한 공개 API(`include/`)를 갖춘 프로덕션 수준의 모듈형 C++ 라이브러리\n- 스레드 풀, 주기적 작업 스케줄러, 비동기 데이터 파이프라인 오케스트레이터를 특징으로 하는 강력한 동시성 엔진\n- YAML 설정, 다중 싱크 로깅, 고정밀 타이밍을 위한 완전한 기반 유틸리티 세트\n- 사용 예제로도 활용 가능한 단위, 통합, 엔드투엔드 테스트를 포함한 포괄적인 검증 스위트\n\n### 기대 효과\n\n- 복잡한 동시성 및 유틸리티 코드를 직접 작성할 필요가 없어져 개발 시간을 획기적으로 단축합니다.\n- 검증된 아키텍처 패턴으로 더 안정적이고, 확장 가능하며, 유지보수하기 쉬운 시스템을 구축합니다.\n- 로우레벨 인프라에서 벗어나 애플리케이션의 핵심 가치를 담은 고유 로직에 집중할 수 있습니다.\n- 정교한 데이터 처리 애플리케이션을 더 큰 자신감을 갖고 더 빠르게 출시할 수 있습니다.","2025-07-05T14:58:55.394Z",[1687,1688,1689,1690],"로보틱스 엔지니어: 여러 개의 고주파 센서 데이터 스트림을 관리하고 동기화하는 데 어려움을 겪는 분","C++ 시스템 개발자: 표준 아키텍처 패턴 없이 고성능 멀티스레드 애플리케이션을 구축해야 하는 분","고성능 컴퓨팅 개발자: 복잡한 연산 워크로드를 병렬화하기 위해 견고한 작업 실행 엔진이 필요한 분","소프트웨어 아키텍트: 팀 전체에 일관되고 안정적인 동시성 패턴을 적용하기 위한 기본 라이브러리를 찾는 분",[1692,1709,1726,1745,1760,1779,1792,1809,1824,1841,1856,1873,1888,1909,1926,1943,1962,1981,1994,2009,2022,2039,2056,2073,2090,2108,2128,2144,2164,2178,2194,2208,2222],{"_22":1693,"_24":1694,"_75":1695,"_77":1696,"_79":1697,"_51":1708,"_42":99},"task-1751724495832","파일시스템 경로 클래스 인터페이스 정의","# 작업: 파일 시스템 경로 클래스 인터페이스 정의\n\n> **에픽**: 파일 시스템 경로 추상화\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: `std::filesystem::path`를 캡슐화하고 경로 연산을 위한 단순화된 API를 노출하는 `core::filesystem::Path` 클래스 인터페이스 정의.\n- **근거**: 이 작업은 프레임워크의 기반이 되는 유틸리티를 구축합니다. `std::filesystem::path` 주변에 래퍼(wrapper)를 생성하여, 모든 경로 관련 작업을 위한 단순화되고 일관되며 제어된 API를 제공합니다. 이러한 추상화는 상위 레벨 컴포넌트(예: `File` I/O 및 `config::Reader`)의 복잡성을 줄이고, 일관된 동작을 강제하며, 핵심 로직을 표준 라이브러리의 특정 사항에 대한 직접적인 의존성으로부터 분리하여 향후 유지보수를 더 쉽게 만듭니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: 모든 공개 메서드 시그니처, 멤버 변수, 그리고 필요한 include를 포함한 Path 클래스의 완전한 헤더 파일.\n- **명세**:\n - **클래스**: `core::filesystem::Path`\n - **생성자**: `explicit Path(const std::string& path_string);`\n - **메서드**:\n - `[[nodiscard]] auto ConvertToString() const -> std::string;`\n - `[[nodiscard]] auto operator/(const Path& appended_path) const -> Path;`\n - `[[nodiscard]] auto GetFilename() const -> Path;`\n - `[[nodiscard]] auto GetExtension() const -> std::string;`\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── include/\n# └── core/\n# └── filesystem/\n# └── path.hpp <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 `Path` 클래스가 다른 프레임워크 컴포넌트에서 사용되는 기초 데이터 타입으로서의 역할을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"애플리케이션 계층\"\n AppCode[\"애플리케이션 코드\"]\n end\n subgraph \"코어 프레임워크\"\n Reader[\"config::Reader\"]\n Path[\"core::filesystem::Path\"]\n end\n subgraph \"표준 라이브러리\"\n StdPath[\"std::filesystem::path\"]\n StdString[\"std::string\"]\n end\n\n AppCode -- \"로 생성\" --> StdString\n StdString -- \"초기화\" --> Path\n Reader -- \"파일 위치에 사용\" --> Path\n Path -- \"래핑 및 단순화\" --> StdPath\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트입니다. 각 항목에 대한 상세 구현은 섹션 3에 있습니다.\n\n- [ ] `Path` 클래스 정의\n- [ ] 문자열 기반 생성자 선언\n- [ ] `ConvertToString` 메서드 선언\n- [ ] 경로 연결을 위한 `operator/` 선언\n- [ ] `GetFilename` 및 `GetExtension` 메서드 선언\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈식 코어 프레임워크\n- **관련된 주요 컴포넌트**:\n - **`core::filesystem::Path` (이 작업)**: 생성될 컴포넌트입니다. 이 컴포넌트의 책임은 파일 시스템 경로 조작을 위한 깨끗하고 플랫폼에 독립적인 인터페이스를 제공하여 전체 프레임워크의 기초 데이터 타입 역할을 하는 것입니다.\n - **향후 사용자 (예: `core::filesystem::File`, `core::config::Reader`)**: 이 작업으로 직접 수정되지는 않지만, 이 컴포넌트들이 존재하는 주된 이유입니다. `Path` 클래스는 이들의 구현에 필수적인 전제 조건이 되며, 프로젝트의 의존성 다이어그램에 설명된 대로 파일 위치를 처리하는 신뢰할 수 있는 방법을 제공할 것입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정될 것입니다.\n\n- `include/core/filesystem/path.hpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 1단계: `Path` 클래스 정의\n\n#### 1. 헤더 파일 및 클래스 골격 생성\n\n이 액션은 컴포넌트의 기본 구조를 설정합니다. 다중 포함 오류를 방지하기 위해 표준 헤더 가드를 포함하여 `path.hpp` 파일을 생성합니다. `core::filesystem` 네임스페이스는 프레임워크 내에서 코드를 논리적으로 구성하며, `Path` 클래스는 그 목적을 설명하는 Doxygen 스타일 주석과 함께 선언됩니다. 이 초기 골격은 모든 후속 선언을 담을 컨테이너를 제공합니다.\n\n**파일**: `include/core/filesystem/path.hpp`\n\n```cpp\n#ifndef CORE__FILESYSTEM__PATH_HPP\n#define CORE__FILESYSTEM__PATH_HPP\n\n#include \n#include \n\nnamespace core::filesystem {\n\n/**\n * @brief std::filesystem::path를 감싸 경로 조작을 위한 단순하고\n * 일관된 인터페이스를 제공하는 래퍼 클래스.\n * @details 이 클래스는 경로 생성, 연결, 그리고 구성 요소(파일명, 확장자)\n * 추출과 같은 일반적인 작업을 단순화합니다.\n */\nclass Path {\n public:\n // ... 공개 인터페이스가 여기에 추가될 것입니다\n\n private:\n std::filesystem::path path_; ///< 파일 시스템 경로를 위한 내부 저장소.\n};\n\n} // namespace core::filesystem\n\n#endif // CORE__FILESYSTEM__PATH_HPP\n```\n\n---\n\n### 2단계: 문자열 기반 생성자 선언\n\n#### 1. 공개 생성자 선언 및 기본 생성자 삭제\n\n이 액션은 `Path` 객체가 생성되는 방법을 정의합니다. `std::string`을 받는 `explicit` 생성자가 선언되며, 이는 유효한 `Path` 객체를 생성하는 유일한 진입점입니다. `explicit`를 사용하면 위험한 암시적 타입 변환을 방지합니다. `Path` 객체가 초기화되지 않거나 비어 있는 상태로 존재할 수 없다는 규칙을 강제하기 위해 기본 생성자는 명시적으로 삭제되어 타입 안전성을 향상시킵니다. 복사/이동 시맨틱을 위한 기본 특수 멤버 함수들도 적절한 리소스 관리를 위해 포함됩니다.\n\n**파일**: `include/core/filesystem/path.hpp`\n\n```cpp\nclass Path {\n public:\n /**\n * @brief std::string으로부터 Path를 생성합니다.\n * @param path_string [in] 경로의 문자열 표현.\n */\n explicit Path(const std::string& path_string);\n\n /**\n * @brief 기본 생성자는 삭제됩니다.\n * @details Path 객체는 반드시 문자열 표현으로부터 생성되어야 합니다.\n * 이는 비어 있거나 초기화되지 않은 경로의 생성을 방지합니다.\n */\n Path() = delete;\n\n /**\n * @brief 기본 복사 생성자.\n */\n Path(const Path&) = default;\n\n /**\n * @brief 기본 복사 대입 연산자.\n * @return 이 인스턴스에 대한 참조.\n */\n auto operator=(const Path&) -> Path& = default;\n\n /**\n * @brief 기본 이동 생성자.\n */\n Path(Path&&) noexcept = default;\n\n /**\n * @brief 기본 이동 대입 연산자.\n * @return 이 인스턴스에 대한 참조.\n */\n auto operator=(Path&&) noexcept -> Path& = default;\n\n /**\n * @brief 기본 소멸자.\n */\n ~Path();\n\n // ... 다른 메서드들\n...\n```\n\n---\n\n### 3단계: `ConvertToString` 메서드 선언\n\n#### 1. `ConvertToString` 메서드 선언\n\n이 액션은 경로의 문자열 표현을 검색하기 위한 공개 접근자를 정의합니다. 이 메서드는 `std::string`을 요구하는 다른 라이브러리나 함수와의 상호 운용성에 필수적입니다. `[[nodiscard]]` 속성은 반환 값이 무시될 경우 컴파일러 경고를 발생시키는 데 사용되며, 프로그래머가 부수 효과를 기대하며 함수를 호출할 수 있는 잠재적인 논리 오류를 방지합니다.\n\n**파일**: `include/core/filesystem/path.hpp`\n\n```cpp\n...\n /**\n * @brief 경로를 문자열 표현으로 변환합니다.\n * @details 내부 경로를 표준 문자열로 제공하며, 이는 표시용이나 문자열 입력을\n * 요구하는 다른 API와 함께 사용될 수 있습니다.\n * @return 경로를 std::string으로 반환합니다.\n */\n [[nodiscard]] auto ConvertToString() const -> std::string;\n...\n```\n\n---\n\n### 4단계: 경로 연결을 위한 `operator/` 선언\n\n#### 1. `operator/` 오버로드 선언\n\n이 액션은 경로를 구성하기 위한 직관적이고 관용적인 C++ 인터페이스를 제공합니다. 경로 연결을 위해 나누기 연산자를 오버로딩하는 것은 `std::filesystem`에 의해 정립된 일반적인 관례입니다. 이 연산자를 제공함으로써 `Path` 클래스를 더 쉽고 자연스럽게 사용할 수 있습니다. 이는 새로운 `Path` 객체를 반환하여 원본 객체들이 불변(immutable)임을 보장합니다. `[[nodiscard]]`는 새로 생성된 경로가 실수로 버려지는 것을 방지합니다.\n\n**파일**: `include/core/filesystem/path.hpp`\n\n```cpp\n...\n /**\n * @brief / 연산자를 사용하여 경로 구성 요소를 추가합니다.\n * @details 이 연산자는 셸에서 경로를 작성하는 방식과 유사하게 세그먼트를\n * 추가하여 새로운 경로를 구성하는 직관적인 방법을 제공합니다.\n * 경로 구분자가 올바르게 처리되도록 보장합니다.\n * @param appended_path [in] 추가할 경로 구성 요소.\n * @return 결합된 경로를 나타내는 새로운 Path 객체.\n */\n [[nodiscard]] auto operator/(const Path& appended_path) const -> Path;\n...\n```\n\n---\n\n### 5단계: `GetFilename` 및 `GetExtension` 메서드 선언\n\n#### 1. `GetFilename` 및 `GetExtension` 메서드 선언\n\n이 액션은 일반적인 경로 구성 요소를 추출하기 위한 유틸리티 메서드를 추가합니다. `GetFilename`은 경로의 마지막 요소를 반환하고, `GetExtension`은 파일 확장자를 반환합니다. 이를 단순화된 API의 일부로 제공함으로써 사용자가 수동으로 문자열을 조작하거나 `std::filesystem::path` 메서드와 직접 상호작용할 필요가 없게 하여 추상화를 유지합니다. 두 메서드 모두 `[[nodiscard]]`로 표시됩니다.\n\n**파일**: `include/core/filesystem/path.hpp`\n\n```cpp\n...\n /**\n * @brief 경로에서 파일명 구성 요소를 추출합니다.\n * @details 파일명은 경로의 마지막 구성 요소이며, 확장자를 포함합니다\n * (예: \\\"/path/to/file.txt\\\"에서 \\\"file.txt\\\").\n * @return 파일명만 포함하는 새로운 Path 객체.\n */\n [[nodiscard]] auto GetFilename() const -> Path;\n\n /**\n * @brief 경로의 파일명에서 확장자를 추출합니다.\n * @details 확장자는 파일명의 마지막 점(.) 뒤의 부분입니다. 만약 파일명이\n * 점으로 시작하고 다른 점이 없다면(예: \\\".bashrc\\\"),\n * 확장자가 없는 것으로 간주됩니다.\n * @return 점을 포함한 확장자를 담은 문자열(예: \\\".txt\\\").\n * 확장자가 없으면 빈 문자열을 반환합니다.\n */\n [[nodiscard]] auto GetExtension() const -> std::string;\n...\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 이 작업은 인터페이스를 정의하는 헤더 파일 생성만 포함하므로, 주요 검증은 C++ 컴파일러에 의해 성공적으로 포함되고 컴파일될 수 있는지, 그리고 문법적으로 올바른지를 확인하는 것입니다.\n\n1. 루트 디렉터리에 `verification.cpp`라는 이름의 **임시 테스트 파일을 생성**합니다.\n2. 파일에 **다음 내용을 추가**합니다. 이 코드는 새 헤더를 포함하고 클래스를 참조하여 제대로 정의되었는지 확인합니다.\n\n ```cpp\n #include \"include/core/filesystem/path.hpp\"\n #include \n\n int main() {\n // 이 프로그램은 path.hpp 헤더가 컴파일되는지만 검증합니다.\n // 런타임 로직을 테스트하지는 않습니다.\n core::filesystem::Path p(\"/tmp/test.txt\");\n std::cout << \"Verification successful: path.hpp header is compilable.\" << std::endl;\n return 0;\n }\n ```\n\n3. C++17(또는 그 이상) 컴파일러를 사용하여 **검증 파일을 컴파일**합니다.\n\n ```bash\n # 컴파일을 확인하는 명령어\n g++ -std=c++17 -I. verification.cpp -o verification_build\n ```\n\n4. 임시 파일들을 삭제하여 **정리**합니다.\n\n ```bash\n rm verification.cpp verification_build\n ```\n\n### 4.2. 예상 결과\n\n- 3단계의 컴파일 명령어는 어떠한 오류나 경고 없이 완료되어야 합니다.\n- 이 명령어는 `verification_build`라는 이름의 실행 파일을 생성해야 합니다.\n- 이는 `include/core/filesystem/path.hpp` 헤더 파일이 문법적으로 유효하고 독립적으로 완전함을 확인합니다.\n","모든 public 메서드 시그니처, 멤버 변수, 필수 include를 포함하는 Path 클래스의 완전한 헤더 파일",[1698,1700,1702,1704,1706],{"_24":1699,"_83":39,"_84":61,"_85":61},"`Path` 클래스 정의",{"_24":1701,"_83":39,"_84":61,"_85":88},"문자열 기반 생성자 선언",{"_24":1703,"_83":39,"_84":61,"_85":91},"`ConvertToString` 메서드 선언",{"_24":1705,"_83":39,"_84":61,"_85":94},"경로 결합을 위한 `operator/` 선언",{"_24":1707,"_83":39,"_84":61,"_85":97},"`GetFilename` 및 `GetExtension` 메서드 선언","std::filesystem::path`를 캡슐화하고 경로 작업을 위한 단순화된 API를 노출하는 `core::filesystem::Path` 클래스 인터페이스를 정의",{"_22":1710,"_24":1711,"_75":1712,"_77":1713,"_79":1714,"_51":1725,"_42":99},"task-1751725645718","파일시스템 경로 클래스 로직 구현","# 작업: 파일시스템 경로 클래스 로직 구현\n\n> **에픽**: 파일시스템 경로 추상화\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: `std::filesystem` 호출을 래핑하여 경로 조작 로직을 제공하는 `core::filesystem::Path` 클래스 메서드를 구현합니다.\n- **근거**: 이 작업은 프레임워크 내 모든 파일 I/O 작업의 기반이 됩니다. `std::filesystem::path`를 캡슐화하는 커스텀 `Path` 클래스를 생성함으로써, 안정적이고 프로젝트에 특화된 인터페이스를 구축합니다. 이러한 추상화는 프레임워크를 특정 C++ 표준 라이브러리 구현 세부 사항으로부터 분리하여 향후 유지보수를 간소화하고, `config::Reader`나 파일 기반 `Logger` 싱크와 같은 상위 컴포넌트에 일관된 API를 보장합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: `path.hpp`에 선언된 모든 메서드의 전체 구현을 포함하는 소스 파일.\n- **명세**:\n - `Path::Path(const std::string& path_string)`\n - `auto Path::ConvertToString() const -> std::string`\n - `auto Path::operator/(const Path& appended_path) const -> Path`\n - `auto Path::GetFilename() const -> Path`\n - `auto Path::GetExtension() const -> std::string`\n- **결과 파일 구조**\n\n```bash\n# ./\n# ├── include/\n# │ └── ...\n# └── source/\n# └── filesystem/\n# └── path.cpp <-- 수정됨\n```\n\n- **프로세스 흐름도**\n이 다이어그램은 `YAML Configuration Reader`와 같은 상위 레벨 컴포넌트가 `core::filesystem::Path` 클래스를 사용하여 파일 경로를 구성하고 관리하는 방법을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"config::Reader 로직\"\n direction LR\n A[\"기본 설정 디렉터리 Path 생성\"] -- \"/sub_dir\" --> B(\"operator/를 사용해 하위 디렉터리 추가\");\n B -- \"/config.yaml\" --> C(\"operator/를 사용해 파일명 추가\");\n C --> D{\"최종 경로
.../sub_dir/config.yaml\"};\n end\n\n subgraph \"core::filesystem::Path\"\n P1[\"Path(\\path/to/config\\)\"]\n P2[\"Path::operator/\"]\n P3[\"Path::ConvertToString()\"]\n end\n \n A --> P1;\n B --> P2;\n D -- \"ifstream을 위한 문자열 가져오기\" --> P3;\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이것은 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] `Path` 생성자 구현.\n- [ ] `ConvertToString` 메서드 구현.\n- [ ] `std::filesystem::path::operator/`를 사용한 `operator/` 구현.\n- [ ] `path::filename()`을 사용한 `GetFilename` 구현.\n- [ ] `path::extension()`을 사용한 `GetExtension` 구현.\n\n## 2. 기술적 컨텍스트\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - `core::filesystem::Path`: 현재 구현 중인 컴포넌트입니다. `std::filesystem::path`에 대한 플랫폼 독립적인 추상화 역할을 합니다. 이 클래스는 경로 조작을 위한 깔끔하고 제어된 인터페이스를 제공하는 책임을 가집니다. 프로젝트의 의존성 다이어그램에서 볼 수 있듯이, 이 클래스는 기본적인 유틸리티이며 파일 I/O를 수행하는 모든 컴포넌트에서 사용될 것입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `source/filesystem/path.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을', '왜'), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `Path` 생성자 구현\n\n#### 1. 생성자 및 소멸자 구현\n\n이 액션은 `Path` 클래스 생성자를 구현하는 작업을 포함하며, 주어진 `std::string`으로부터 내부 `std::filesystem::path` 멤버(`path_`)를 초기화합니다. 특별한 리소스 관리가 필요 없으므로 기본 소멸자도 정의됩니다. 이를 통해 `Path` 클래스의 기본 객체 생명주기가 설정됩니다.\n\n**파일**: `source/filesystem/path.cpp`\n\n```cpp\n#include \"core/filesystem/path.hpp\"\n\n#include \n\nnamespace core::filesystem {\n\nPath::Path(const std::string& path_string) : path_(path_string) {}\n\nPath::~Path() = default;\n\n// ...\n} // namespace core::filesystem\n```\n\n---\n\n### 단계 2: `ConvertToString` 메서드 구현\n\n#### 1. 문자열 변환 메서드 구현\n\n이 액션은 `ConvertToString` 메서드를 구현합니다. 이 메서드의 목적은 경로를 `std::string`으로 가져오는 표준화된 방법을 제공하는 것입니다. 로직은 변환을 내부 `std::filesystem::path::string()` 메서드에 직접 위임하여 정확하고 이식성 있는 문자열 표현을 보장합니다.\n\n**파일**: `source/filesystem/path.cpp`\n\n```cpp\n// ...\n\nauto Path::ConvertToString() const -> std::string { return path_.string(); }\n\n// ...\n```\n\n---\n\n### 단계 3: `std::filesystem::path::operator/`를 사용한 `operator/` 구현\n\n#### 1. 경로 추가 연산자 구현\n\n이 액션은 `Path` 클래스의 `operator/`를 구현합니다. 이는 경로 세그먼트를 결합하기 위한 직관적이고 관습적인 구문을 제공합니다. 구현은 `std::filesystem::path` 클래스의 해당 `operator/`를 활용하고 그 결과로 새로운 `Path` 객체를 생성하여, 유연한 경로 구성을 촉진합니다.\n\n**파일**: `source/filesystem/path.cpp`\n\n```cpp\n// ...\n\nauto Path::operator/(const Path& appended_path) const -> Path {\n return Path((path_ / appended_path.path_).string());\n}\n\n// ...\n```\n\n---\n\n### 단계 4: `path::filename()`을 사용한 `GetFilename` 구현\n\n#### 1. 파일 이름 접근자 구현\n\n이 액션은 `GetFilename` 메서드를 구현합니다. 전체 경로에서 마지막 구성 요소(파일 이름)를 추출하도록 설계되었습니다. 구현은 표준 라이브러리의 `path_.filename()`을 호출하고, 결과로 나온 `std::filesystem::path` 객체를 새로운 `core::filesystem::Path` 인스턴스로 감싸 반환합니다.\n\n**파일**: `source/filesystem/path.cpp`\n\n```cpp\n// ...\n\nauto Path::GetFilename() const -> Path {\n return Path(path_.filename().string());\n}\n\n// ...\n```\n\n---\n\n### 단계 5: `path::extension()`을 사용한 `GetExtension` 구현\n\n#### 1. 확장자 접근자 구현\n\n이 액션은 경로에서 파일 확장자를 분리하는 `GetExtension` 메서드를 구현합니다. 이는 파일 형식 유효성 검사 및 처리 로직에서 흔히 요구되는 기능입니다. 구현은 `path_.extension().string()` 호출에 위임하여 확장자를 `std::string`으로 가져옵니다.\n\n**파일**: `source/filesystem/path.cpp`\n\n```cpp\n// ...\n\nauto Path::GetExtension() const -> std::string {\n return path_.extension().string();\n}\n\n} // namespace core::filesystem\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n- `core::filesystem::Path`에 대한 유닛 테스트를 작성하고 통과시켜야 합니다. 프로젝트 명세 `13.1`에 따라, 이 테스트는 구현된 각 메서드를 개별적으로 검증해야 합니다. 다음 명령어는 `build/` 디렉터리에 위치한 CMake 기반 빌드 시스템을 가정합니다.\n\n```bash\n# 1. 빌드 디렉터리로 이동\ncd build/\n\n# 2. 테스트를 포함하여 프로젝트를 구성하고 빌드\ncmake .. -DENABLE_TESTS=ON\nmake\n\n# 3. 코어 라이브러리의 유닛 테스트 실행\n# (테스트 실행 파일의 정확한 이름은 CMake 구성에 따라 다를 수 있음)\n./tests/unit/core_unit_tests\n```\n\n### 4.2. 예상 결과\n\n- 테스트 실행기는 `core::filesystem::Path`에 대한 모든 테스트 케이스가 통과했다고 보고해야 합니다. 출력은 다음과 유사해야 합니다(GoogleTest 예시):\n\n```\n[==========] Running 5 tests from 1 test suite.\n[----------] Global test environment set-up.\n[----------] 5 tests from PathTest\n[ RUN ] PathTest.Constructor\n[ OK ] PathTest.Constructor (0 ms)\n[ RUN ] PathTest.ConvertToString\n[ OK ] PathTest.ConvertToString (0 ms)\n[ RUN ] PathTest.AppendOperator\n[ OK ] PathTest.AppendOperator (0 ms)\n[ RUN ] PathTest.GetFilename\n[ OK ] PathTest.GetFilename (0 ms)\n[ RUN ] PathTest.GetExtension\n[ OK ] PathTest.GetExtension (0 ms)\n[----------] 5 tests from PathTest (0 ms total)\n\n[----------] Global test environment tear-down\n[==========] 5 tests from 1 test suite ran. (0 ms total)\n[ PASSED ] 5 tests.\n```\n","`path.hpp`에 선언된 모든 메서드의 전체 구현을 포함하는 소스 파일",[1715,1717,1719,1721,1723],{"_24":1716,"_83":39,"_84":88,"_85":61},"`Path` 생성자 구현",{"_24":1718,"_83":39,"_84":88,"_85":88},"`ConvertToString` 메서드 구현",{"_24":1720,"_83":39,"_84":88,"_85":91},"`std::filesystem::path::operator/`를 사용한 `operator/` 구현",{"_24":1722,"_83":39,"_84":88,"_85":94},"`path::filename()`을 사용한 `GetFilename` 구현",{"_24":1724,"_83":39,"_84":88,"_85":97},"`path::extension()`을 사용한 `GetExtension` 구현","`std::filesystem` 호출을 래핑하여 경로 조작 로직을 제공하는 `core::filesystem::Path` 클래스 메서드를 구현",{"_22":1727,"_24":1728,"_75":1729,"_77":1730,"_79":1731,"_51":1744,"_42":99},"task-1751725713219","시간 간격 클래스 인터페이스 정의","# 작업: 시간 기간 클래스 인터페이스 정의\n\n> **에픽**: 시간 기간 표현\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 나노초 정밀도와 변환 기능을 갖춘 시간 범위를 표현하기 위한 `core::time::Duration` 클래스 인터페이스를 정의합니다.\n- **근거**: 이 클래스는 고성능 애플리케이션에 필요한 시간 범위를 타입-세이프(type-safe) 방식으로 표현하는 기본적인 방법을 제공합니다. `Scheduler`가 주기적인 작업을 관리하고 `Stamp` 클래스가 실행 시간을 측정하는 데 필수적인 시간 계산을 표준화합니다. 이 로직을 `Duration` 클래스에 중앙화함으로써 코드의 명확성을 높이고, 변환 오류를 방지하며, 프레임워크의 고정밀 타이밍 유틸리티를 구축하기 위한 전제 조건이 됩니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 비교 연산자, `Unit` 열거형, 생성자, `Get` 메서드를 포함한 Duration 클래스의 완전한 헤더 파일.\n- **명세**:\n - `클래스`: `core::time::Duration`\n - `공개 열거형(Enum)`: `Unit` - 나노초, 마이크로초, 밀리초, 초 값을 가짐.\n - `공개 생성자`: 기본 생성자 및 `(int64_t value, Unit unit)`을 받는 생성자.\n - `공개 메서드`: `[[nodiscard]] auto Get(Unit unit) const -> int64_t`.\n - `공개 연산자`: `==`, `!=`, `<`, `>`, `<=`, `>=`.\n - `비공개 멤버`: `std::chrono::duration nanoseconds_`.\n - `프렌드 클래스`: `core::time::Stamp`.\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── include/\n# └── core/\n# └── time/\n# └── duration.hpp <-- 신규\n```\n\n- **프로세스 흐름도**\n `Duration` 클래스는 주로 `Stamp` 뺄셈의 결과로 사용되도록 의도되었습니다. 이 다이어그램은 핵심 사용 사례를 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"시간 측정\"\n Stamp1[\"start = Stamp::Now()\"]\n Work[\"... 작업 수행 ...\"]\n Stamp2[\"end = Stamp::Now()\"]\n Subtract[\"duration = end - start\"]\n GetValue[\"ms = duration.Get(Unit::kMilliseconds)\"]\n\n Stamp1 --> Work --> Stamp2 --> Subtract\n Subtract -- \"Duration 객체 반환\" --> GetValue\n end\n\n subgraph \"간격 정의\"\n DefineInterval[\"timeout = Duration(100, Unit::kMilliseconds)\"]\n end\n```\n\n### 1.3. 인수 기준\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트입니다. 각 항목에 대한 상세 구현은 섹션 3에 있습니다.\n\n- [ ] `Duration` 클래스 정의.\n- [ ] 모든 비교 연산자(`==`, `!=`, `<`, 등) 선언.\n- [ ] 시간 단위를 위한 `Unit` 열거형 정의.\n- [ ] 생성자(기본 및 값/단위 기반) 선언.\n- [ ] 단위 변환을 위한 `Get` 메서드 선언.\n- [ ] `Stamp`의 전방 선언 및 프렌드 클래스 선언.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 구성요소**:\n - `core::time::Duration` (이 작업): 시간 범위를 나타내는 기본 데이터 구조.\n - `core::time::Stamp` (예정): 고정밀 타임스탬프를 캡처하기 위한 클래스. `Duration`은 두 `Stamp` 객체를 뺀 결과가 되도록 설계되었습니다. 이 관계는 기본 `Duration` 생성자를 비공개로 만들고 `friend class Stamp`를 통해서만 접근 가능하게 하여 강제됩니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `include/core/time/duration.hpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 기준**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `Duration` 클래스 정의\n\n#### 1. 헤더 파일 및 네임스페이스 구조 생성\n\n이 액션은 `duration.hpp` 파일을 생성합니다. 표준 헤더를 포함하고, 중복 포함을 방지하기 위한 인클루드 가드를 설정하며, 프로젝트의 디렉터리 구조에 맞춰 `core::time` 네임스페이스를 정의합니다.\n\n**파일**: `include/core/time/duration.hpp`\n\n```cpp\n/**\n * @file duration.hpp\n * @author movingChurch (yes@holyground.world)\n * @brief 고정밀 시간 기간을 표현하기 위한 클래스를 정의합니다.\n * @version 1.0.0\n * @date 2025-06-30\n * @copyright movingChurch (c) 2025, All Rights Reserved.\n */\n#ifndef CORE__TIME__DURATION_HPP\n#define CORE__TIME__DURATION_HPP\n\n#include \n#include \n\nnamespace core::time {\n\n// 전방 선언은 다음 단계에서 여기에 추가될 것입니다.\n\nclass Duration {\n public:\n // 공개 인터페이스는 후속 단계에서 정의될 것입니다.\n \n private:\n // 비공개 멤버는 후속 단계에서 정의될 것입니다.\n\n std::chrono::duration nanoseconds_;\n};\n\n} // namespace core::time\n\n#endif // CORE__TIME__DURATION_HPP\n```\n\n---\n\n### 단계 2: 모든 비교 연산자(`==`, `!=`, `<`, 등) 선언\n\n#### 1. 인라인 비교 연산자 구현\n\n이 액션은 여섯 개의 모든 비교 연산자를 추가합니다. 이들은 `const` 멤버 함수로 구현되며 효율성을 위해 클래스 정의 내에 인라인으로 정의됩니다. 비교는 비공개 멤버인 `nanoseconds_`에서 직접 작동하여 `Duration` 객체를 비교하는 견고하고 성능 좋은 방법을 제공합니다.\n\n**파일**: `include/core/time/duration.hpp`\n\n```cpp\nclass Duration {\n public:\n auto operator==(const Duration& other) const -> bool {\n return nanoseconds_ == other.nanoseconds_;\n }\n\n auto operator!=(const Duration& other) const -> bool {\n return !(*this == other);\n }\n\n auto operator<(const Duration& other) const -> bool {\n return nanoseconds_ < other.nanoseconds_;\n }\n\n auto operator>(const Duration& other) const -> bool {\n return nanoseconds_ > other.nanoseconds_;\n }\n\n auto operator<=(const Duration& other) const -> bool {\n return !(*this > other);\n }\n\n auto operator>=(const Duration& other) const -> bool {\n return !(*this < other);\n }\n\n // ... 다른 공개 멤버들\n};\n```\n\n---\n\n### 단계 3: 시간 단위를 위한 `Unit` 열거형 정의\n\n#### 1. 공개 `Unit` 열거형 정의\n\n이 액션은 `Duration` 클래스 내에 `Unit`이라는 이름의 공개 `enum`을 정의합니다. 이는 `Duration`을 생성하거나 `Get` 메서드를 통해 값을 검색할 때 시간 단위를 지정하기 위한 강력한 타입의 명확한 인터페이스를 제공하여, 매직 넘버 사용을 방지하고 가독성을 향상시킵니다.\n\n**파일**: `include/core/time/duration.hpp`\n\n```cpp\nclass Duration {\n public:\n // ... 연산자들\n \n enum Unit : std::uint8_t {\n kNanoseconds = 0,\n kMicroseconds = 1,\n kMilliseconds = 2,\n kSeconds = 3\n };\n\n // ... 다른 공개 멤버들\n};\n```\n\n---\n\n### 단계 4: 생성자(기본 및 값/단위 기반) 선언\n\n#### 1. 공개 및 비공개 생성자 선언\n\n이 액션은 클래스 생성자들을 선언합니다. 공개 기본 생성자는 0-기간(zero-duration)으로 초기화합니다. 값과 `Unit`을 받는 공개 생성자는 (예: 타임아웃 용도로) 기간을 명시적으로 생성할 수 있게 합니다. `std::chrono::duration`을 받는 비공개 `explicit` 생성자 또한 선언됩니다. 이는 `friend class Stamp`에 의해서만 호출될 수 있으므로 의도된 생성 패턴을 강제하는 설계의 핵심입니다.\n\n**파일**: `include/core/time/duration.hpp`\n\n```cpp\nclass Duration {\n public:\n // ... 연산자 및 열거형\n \n Duration();\n\n Duration(int64_t value, Unit unit);\n \n // ... 다른 공개 멤버들\n\n private:\n // ... 프렌드 클래스 선언은 여기에 추가될 것입니다.\n\n explicit Duration(std::chrono::duration duration)\n : nanoseconds_(duration) {}\n\n std::chrono::duration nanoseconds_;\n};\n```\n\n---\n\n### 단계 5: 단위 변환을 위한 `Get` 메서드 선언\n\n#### 1. 공개 `Get` 메서드 선언\n\n이 액션은 사용자가 지정된 `Unit`으로 기간의 값을 검색할 수 있는 `Get` 메서드를 선언합니다. 이 메서드는 객체의 상태를 수정하지 않으므로 `const`로 표시되고, 호출자가 반환 값을 사용하도록 권장하여 잠재적인 버그를 방지하기 위해 `[[nodiscard]]`로 표시됩니다. 편의를 위해 메서드에 기본 인수가 제공될 것입니다.\n\n**파일**: `include/core/time/duration.hpp`\n\n```cpp\nclass Duration {\n public:\n // ... 연산자, 열거형 및 생성자\n\n [[nodiscard]] auto Get(Unit unit = kNanoseconds) const -> int64_t;\n\n private:\n // ... 비공개 멤버들\n};\n```\n\n---\n\n### 단계 6: `Stamp`의 전방 선언 및 프렌드 클래스 선언\n\n#### 1. `Stamp` 전방 선언 추가\n\n이 액션은 `Duration` 클래스 정의 전에 `class Stamp`에 대한 전방 선언을 추가합니다. 이는 `Duration` 클래스가 `Stamp`가 완전히 정의되기 전에 `Stamp`를 `friend`로 참조하여 발생할 수 있는 순환 종속성을 깨기 위해 필요합니다.\n\n**파일**: `include/core/time/duration.hpp`\n\n```cpp\n// ... 인클루드 및 네임스페이스 시작\n\nnamespace core::time {\n\nclass Stamp; // 전방 선언\n\nclass Duration {\n// ...\n};\n\n} // namespace core::time\n```\n\n#### 2. `Stamp`를 프렌드 클래스로 추가\n\n이 액션은 `Stamp`가 `Duration`의 비공개 멤버, 특히 비공개 생성자에 접근할 수 있도록 허용합니다. 이는 측정된 시간을 나타내는 `Duration` 객체가 오직 두 `Stamp` 인스턴스를 빼서 생성되도록 보장하여 타입 안전성을 강화하고 명확한 의도를 표현하는 설계 패턴의 초석입니다.\n\n**파일**: `include/core/time/duration.hpp`\n\n```cpp\nclass Duration {\n // ... 공개 멤버들\n\n private:\n friend class Stamp;\n\n explicit Duration(std::chrono::duration duration)\n : nanoseconds_(duration) {}\n\n std::chrono::duration nanoseconds_;\n};\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 이 헤더 전용 인터페이스의 주요 검증은 성공적인 컴파일입니다. 새 헤더를 포함하는 임시 C++ 파일을 생성하여 자체적으로 완전하고 구문적으로 올바른지 확인합니다.\n\n```bash\n# 1. 소스 디렉터리로 이동\ncd \n\n# 2. 임시 테스트 파일 생성\necho '#include \"include/core/time/duration.hpp\"' > temp_verifier.cpp\n\n# 3. 임시 파일 컴파일 시도 (프로젝트에 맞게 컴파일러 및 플래그 조정)\n# 이 명령어는 실행 파일을 생성할 필요 없이 컴파일 오류만 확인합니다.\ng++ -std=c++17 -c temp_verifier.cpp -o temp_verifier.o\n\n# 4. 임시 파일 정리\nrm temp_verifier.cpp temp_verifier.o\n```\n\n### 4.2. 예상 결과\n\n- 3단계의 컴파일 명령어는 종료 코드 0으로 성공적으로 완료되어야 합니다.\n- 표준 오류(standard error)로 컴파일 오류나 경고가 보고되지 않아야 합니다. 성공적으로 컴파일되면 터미널은 조용해야 합니다.\n","비교 연산자, `Unit` 열거형, 생성자, `Get` 메서드를 포함하는 Duration 클래스의 완전한 헤더 파일",[1732,1734,1736,1738,1740,1742],{"_24":1733,"_83":39,"_84":91,"_85":61},"`Duration` 클래스 정의",{"_24":1735,"_83":39,"_84":91,"_85":88},"모든 비교 연산자(`==`, `!=`, `<`, 등) 선언",{"_24":1737,"_83":39,"_84":91,"_85":91},"시간 단위를 위한 `Unit` 열거형 정의",{"_24":1739,"_83":39,"_84":91,"_85":94},"생성자(기본 및 값/단위 기반) 선언",{"_24":1741,"_83":39,"_84":91,"_85":97},"단위 변환을 위한 `Get` 메서드 선언",{"_24":1743,"_83":39,"_84":91,"_85":176},"`Stamp`의 전방 선언 및 friend 클래스 선언","나노초 정밀도와 변환 기능을 갖춘 시간 범위를 표현하기 위한 `core::time::Duration` 클래스 인터페이스를 정의",{"_22":1746,"_24":1747,"_75":1748,"_77":1749,"_79":1750,"_51":1759,"_42":99},"task-1751725773251","시간 간격 클래스 로직 구현","# 작업: 시간 Duration 클래스 로직 구현\n\n> **에픽**: 시간 Duration 표현\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 생성자와 내부 나노초 값을 다른 단위로 변환하기 위한 `Get` 메서드를 포함한 `core::time::Duration` 클래스 로직 구현.\n- **근거**: 이 작업은 프레임워크 내 모든 시간 기반 작업을 위한 핵심 데이터 타입을 구축합니다. 고정밀 내부 표현(나노초)을 갖춘 표준화된 `Duration` 클래스는 `Scheduler`(작업 간격 정의) 및 `Stamp`(성능 지표 계산)와 같은 컴포넌트의 기본이 됩니다. 이는 전체 시스템에 걸쳐 일관되고 정확한 시간 처리를 보장하며, 핵심 프로젝트 목표를 달성합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: `Duration` 클래스 메서드의 전체 구현을 포함하는 소스 파일.\n- **사양**:\n - `구현될 클래스`: `core::time::Duration`\n - `소스 파일에 구현될 메서드`:\n - `Duration()`\n - `Duration(int64_t value, Unit unit)`\n - `auto Get(Unit unit) const -> int64_t`\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── source/\n# └── time/\n# └── duration.cpp <-- 수정됨\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 `Duration` 객체를 생성하고 그 값을 다른 단위로 조회하는 내부 로직을 보여줍니다. 핵심 원칙은 모든 입력을 단일 내부 표현(나노초)으로 표준화한 다음, 필요에 따라 해당 표준에서 변환하는 것입니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"생성: Duration(1, Unit::kSeconds)\"\n Input[\"입력: (1, kSeconds)\"] --> Constructor[\"생성자 로직 (switch-case)\"];\n Constructor --> UseChrono[\"std::chrono::seconds(1) 사용\"];\n UseChrono --> Store[\"내부 값을 1,000,000,000 나노초로 저장\"];\n end\n\n subgraph \"조회: Get(Unit::kMilliseconds)\"\n CallGet[\"Get(kMilliseconds) 호출\"] --> Getter[\"Getter 로직 (switch-case)\"];\n Getter --> Retrieve[\"내부 값 (1,000,000,000 ns) 조회\"];\n Retrieve --> Convert[\"kNanosecondsPerMillisecond (1,000,000)로 나누기\"];\n Convert --> Output[\"반환 값: 1000\"];\n end\n\n Store --> CallGet;\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] 0으로 초기화하는 기본 생성자 구현.\n- [ ] switch 문을 사용한 값/단위 생성자 구현.\n- [ ] 변환 로직을 포함한 `Get` 메서드 구현.\n- [ ] 변환 계수를 위한 컴파일 타임 상수 정의.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - `core::time::Duration` (자체): 이 클래스는 `time` 모듈 내의 기초 유틸리티입니다.\n - `core::time::Stamp`: 이 컴포넌트는 두 `Stamp` 객체 간의 시간 차이를 계산하기 위해 `Duration`에 의존하게 됩니다.\n - `core::concurrency::Scheduler`: 이 상위 수준 컴포넌트는 `Duration` 객체를 사용하여 주기적인 작업의 실행 빈도를 정의합니다. `Duration` 클래스는 `Scheduler`의 내부 타이밍 로직에 필요한 정밀도와 변환 유틸리티를 제공합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `source/time/duration.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을', '왜'), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 0으로 초기화하는 기본 생성자 구현\n\n#### 1. 기본 생성자 구현\n\n이 액션은 기본 생성자를 구현합니다. 목적은 `Duration` 객체가 아무 인자 없이 생성될 때, 알려진 중립 상태(0 시간)로 초기화되도록 보장하는 것입니다. 이는 멤버 초기화 리스트를 사용하여 private 멤버 `nanoseconds_`를 `0`으로 초기화함으로써 달성됩니다. 이는 초기화되지 않은 상태를 방지하고 이 타입의 클래스 멤버에 대한 안전한 기본값을 제공합니다.\n\n**파일**: `source/time/duration.cpp`\n\n```cpp\n// ... (includes and namespace)\n\ncore::time::Duration::Duration() : nanoseconds_(0) {}\n\n// ... (other method implementations)\n```\n\n---\n\n### 단계 2: switch 문을 사용한 값/단위 생성자 구현\n\n#### 1. 값 기반 생성자 구현\n\n이 액션은 숫자 값과 `Unit`을 인자로 받는 생성자를 구현합니다. 목적은 다양한 표준 시간 단위로부터 `Duration`을 생성하는 편리하고 명시적인 방법을 제공하는 것입니다. `switch` 문은 다른 `Unit` 열거형을 처리하는 데 사용됩니다. 각 케이스마다 입력 `value`는 `std::chrono::nanoseconds` 객체로 변환되며, 이는 내부 `nanoseconds_` 멤버로의 변환 및 할당을 견고하게 처리합니다. 이는 생성 시 변환 로직을 중앙 집중화하고 C++ 표준 라이브러리의 타입 안전성을 활용합니다.\n\n**파일**: `source/time/duration.cpp`\n\n```cpp\n// ...\n\ncore::time::Duration::Duration(int64_t value, Unit unit) : nanoseconds_(0) {\n switch (unit) {\n case Unit::kSeconds:\n nanoseconds_ = std::chrono::seconds(value);\n break;\n case Unit::kMilliseconds:\n nanoseconds_ = std::chrono::milliseconds(value);\n break;\n case Unit::kMicroseconds:\n nanoseconds_ = std::chrono::microseconds(value);\n break;\n case Unit::kNanoseconds:\n nanoseconds_ = std::chrono::nanoseconds(value);\n break;\n }\n}\n\n// ...\n```\n\n---\n\n### 단계 3: 변환 로직을 포함한 `Get` 메서드 구현\n\n#### 1. `Get` 접근자 메서드 구현\n\n이 액션은 클래스 소비자가 지정된 `Unit`으로 duration 값을 검색할 수 있게 해주는 `Get` 메서드를 구현합니다. 일관성과 정확성을 보장하기 위해, 모든 변환은 단일 진실 공급원(single source of truth)인 내부 `nanoseconds_` 멤버로부터 수행됩니다. `switch` 문은 원시 나노초 카운트를 적절한 컴파일 타임 상수로 나누어 요청된 단위로의 변환을 처리합니다. 이 접근 방식은 변환 로직을 캡슐화하고 데이터 조회를 위한 간단하고 통일된 인터페이스를 제공합니다.\n\n**파일**: `source/time/duration.cpp`\n\n```cpp\n// ...\n\nauto core::time::Duration::Get(Unit unit) const -> int64_t {\n int64_t result = 0;\n switch (unit) {\n case Unit::kNanoseconds:\n result = nanoseconds_.count();\n break;\n case Unit::kMicroseconds:\n result = nanoseconds_.count() / kNanosecondsPerMicrosecond;\n break;\n case Unit::kMilliseconds:\n result = nanoseconds_.count() / kNanosecondsPerMillisecond;\n break;\n case Unit::kSeconds:\n result = nanoseconds_.count() / kNanosecondsPerSecond;\n break;\n }\n return result;\n}\n```\n\n---\n\n### 단계 4: 변환 계수를 위한 컴파일 타임 상수 정의\n\n#### 1. 내부 변환 상수 정의\n\n이 액션은 소스 파일 상단의 익명 네임스페이스 내에 `constexpr` 상수 집합을 정의합니다. 이 상수들의 목적은 `Get` 메서드에서 사용되는 변환 계수에 대해 명확하고 이름 있는 값을 제공하여 코드에서 \"매직 넘버\"를 제거하는 것입니다. 익명 네임스페이스에 배치하면 이들의 연결을 현재 번역 단위(`duration.cpp`)로 제한하여 프로젝트의 다른 부분에서 발생할 수 있는 이름 충돌을 방지합니다. `constexpr`를 사용하면 이 값들이 컴파일 타임에 평가되도록 보장합니다.\n\n**파일**: `source/time/duration.cpp`\n\n```cpp\n/**\n * @file duration.cpp\n * ...\n */\n#include \"core/time/duration.hpp\"\n\n#include \n#include \n\nnamespace {\n/**\n * @brief 시간 단위 변환을 위한 컴파일 타임 상수를 정의합니다.\n * @details 이 상수들은 이 파일 내에서 나노초를 다른 시간 단위로\n * 변환하는 데 사용되며, 매직 넘버를 피하여 가독성을\n * 향상시킵니다.\n */\nconstexpr int64_t kNanosecondsPerMicrosecond = 1000;\nconstexpr int64_t kNanosecondsPerMillisecond = 1000 * 1000;\nconstexpr int64_t kNanosecondsPerSecond = 1000 * 1000 * 1000;\n} // namespace\n\n// ... (class method implementations)\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n`Duration` 클래스 로직을 검증하기 위해 유닛 테스트를 작성해야 합니다. 개발자는 새 테스트 파일을 생성하고 모든 public 메서드를 다루는 테스트 케이스를 구현해야 합니다.\n\n1. **유닛 테스트 파일 생성**: `tests/unit/time_duration_test.cpp` 새 파일을 생성합니다.\n2. **테스트 케이스 구현**:\n - **기본 생성자**: `Duration().Get(Unit::kNanoseconds)`가 `0`을 반환하는지 확인합니다.\n - **값 생성자**: 각 `Unit`에 대해 `Duration`을 생성하고 내부 나노초 표현이 올바른지 확인합니다.\n - **Get 메서드**: `Duration`을 생성(예: `Duration(1, Unit::kSeconds)`)하고 다른 모든 단위에 대해 `Get`을 호출하여 반환된 값이 올바른지(예: 밀리초의 경우 `1000`, 마이크로초의 경우 `1000000`) 단언(assert)합니다.\n - **비교 연산자**: 헤더 파일에 정의된 `==`, `!=`, `<`, `>`, `<=`, `>=` 연산자를 다양한 `Duration` 값으로 테스트합니다.\n3. **테스트 실행**: 유닛 테스트를 컴파일하고 실행합니다. 정확한 명령어는 프로젝트의 빌드 시스템(예: CMake)에 따라 다릅니다.\n\n```bash\n# 1. 빌드 디렉토리로 이동\ncd build/\n\n# 2. 프로젝트와 테스트 빌드\ncmake ..\nmake\n\n# 3. 코어 라이브러리에 대한 특정 테스트 실행 파일 실행\n# 이름은 CMake 구성에 따라 다를 수 있습니다.\n./tests/unit/core_unit_tests\n```\n\n### 4.2. 예상 결과\n\n유닛 테스트 실행기는 `Duration` 클래스에 대한 모든 테스트가 성공적으로 통과했다고 보고해야 합니다. 출력은 다음(Google Test 예시)과 유사해야 합니다.\n\n```\n[==========] Running all tests from test suite TimeDurationTest.\n[----------]\n[ RUN ] TimeDurationTest.DefaultConstructorIsZero\n[ OK ] TimeDurationTest.DefaultConstructorIsZero (0 ms)\n[ RUN ] TimeDurationTest.ValueConstructorConvertsCorrectly\n[ OK ] TimeDurationTest.ValueConstructorConvertsCorrectly (0 ms)\n[ RUN ] TimeDurationTest.GetMethodConvertsCorrectly\n[ OK ] TimeDurationTest.GetMethodConvertsCorrectly (0 ms)\n[ RUN ] TimeDurationTest.ComparisonOperatorsWorkAsExpected\n[ OK ] TimeDurationTest.ComparisonOperatorsWorkAsExpected (0 ms)\n[----------]\n[==========] All tests passed.\n```\n","`Duration` 클래스 메서드의 전체 구현이 담긴 소스 파일",[1751,1753,1755,1757],{"_24":1752,"_83":39,"_84":94,"_85":61},"0으로 초기화하는 기본 생성자 구현",{"_24":1754,"_83":39,"_84":94,"_85":88},"switch 문을 사용한 값/단위 기반 생성자 구현",{"_24":1756,"_83":39,"_84":94,"_85":91},"변환 로직을 포함한 `Get` 메서드 구현",{"_24":1758,"_83":39,"_84":94,"_85":94},"변환 계수를 위한 컴파일 타임 상수 정의","생성자와 내부 나노초 값을 다른 단위로 변환하는 `Get` 메서드를 포함한 `core::time::Duration` 클래스 로직을 구현",{"_22":1761,"_24":1762,"_75":1763,"_77":1764,"_79":1765,"_51":1778,"_42":99},"task-1751725813699","스레드 풀 클래스 인터페이스 정의","# 작업: Thread Pool 클래스 인터페이스 정의\n\n> **에픽**: 코어 스레드 풀 실행기\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: `core::concurrency::ThreadPool` 클래스 인터페이스 정의. 작업 큐(job queue) 구조와 생성 및 작업 제출을 위한 공개 API를 포함합니다.\n- **근거**: `ThreadPool`은 전체 프레임워크의 기반이 되는 동시성 엔진입니다. 명확하고 견고한 인터페이스를 구축하는 것은 `Scheduler` 및 `Pipeline`과 같은 모든 상위 수준 비동기 컴포넌트를 위한 핵심 전제 조건입니다. 이러한 컴포넌트들은 계산량이 많거나 블로킹(blocking)이 발생하는 작업을 오프로드하여 메인 애플리케이션 스레드가 멈추는 것을 방지하기 위해 이 인터페이스에 의존하게 됩니다. 이 정의는 향후 모든 동시성 작업에 대한 계약(contract) 역할을 합니다.\n\n### 1.2. 결과물\n\n- **예상 결과물**: 완전한 `ThreadPool` 클래스 정의, 중첩된 `JobQueue` 구조체, 그리고 모든 멤버 변수 및 메서드 선언이 포함된 헤더 파일.\n- **명세**:\n - `Class`: `core::concurrency::ThreadPool`\n - `Type Alias`: `using Job = std::function;`\n - `Internal Struct`: `JobQueue`\n - `Constructor`: `ThreadPool(uint32_t number_of_threads, uint32_t queue_capacity)`\n - `Destructor`: `~ThreadPool()`\n - `Public Method`: `void EnqueueJob(Job job)`\n - `Private Method`: `void LoopForWorker()`\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── include/\n# └── core/\n# └── concurrency/\n# └── thread_pool.hpp <-- 신규\n```\n\n### 1.3. 인수 기준\n\n개발자는 이 작업을 완료된 것으로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] `ThreadPool` 클래스 정의\n- [ ] `Job` 타입 별칭(type alias) 정의\n- [ ] 내부 `JobQueue` 구조체 정의\n- [ ] 생성자 및 소멸자 선언\n- [ ] 공개 `EnqueueJob` 메서드 선언\n- [ ] 비공개 `LoopForWorker` 메서드 선언\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - `ThreadPool`: 현재 정의하고 있는 컴포넌트입니다. 공유 큐로부터 작업을 가져와 동시 실행하기 위해 작업자 스레드 풀을 관리하는 책임을 가집니다. 이 작업은 `ThreadPool`의 공개 및 비공개 인터페이스를 생성합니다.\n - `Scheduler` / `Pipeline`: 향후 클라이언트가 될 컴포넌트들입니다. 이들은 주기적인 작업과 파이프라인 단계를 비동기적으로 실행하기 위해 `ThreadPool`의 공개 메서드인 `EnqueueJob`을 통해 상호작용할 것입니다. 이 작업은 그들이 기반으로 할 정확한 인터페이스를 정의합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `include/core/concurrency/thread_pool.hpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계(Step)`는 **인수 기준**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업(Action)`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `ThreadPool` 클래스 정의\n\n#### 1. 헤더 파일 및 기본 클래스 뼈대 생성\n\n이 작업은 헤더 파일의 기본 구조를 설정합니다. 중복 포함을 방지하기 위한 표준 인클루드 가드(include guard), 필요한 C++ 표준 라이브러리 헤더, 그리고 `core::concurrency` 네임스페이스를 정의합니다. 비어 있는 `ThreadPool` 클래스 선언은 이후의 모든 멤버와 메서드를 담는 컨테이너 역할을 합니다.\n\n**파일**: `include/core/concurrency/thread_pool.hpp`\n\n```cpp\n/**\n * @file thread_pool.hpp\n * @author movingChurch (yes@holyground.world)\n * @brief 작업자 스레드 풀을 관리하는 ThreadPool 클래스를 정의합니다.\n * @version 1.0.0\n * @date 2025-07-02\n * @copyright movingChurch (c) 2025, All Rights Reserved.\n */\n\n#ifndef CORE__CONCURRENCY__THREAD_POOL_HPP_\n#define CORE__CONCURRENCY__THREAD_POOL_HPP_\n\n#include \n#include \n#include \n#include \n#include \n#include \n#include \n\nnamespace core::concurrency {\n\n/**\n * @brief 작업자 스레드 컬렉션을 관리하여 작업을 동시 실행하는 스레드 풀입니다.\n * @details 이 클래스는 고정된 크기의 스레드 풀을 간단하고 효율적으로 관리하는\n * 방법을 제공합니다. 작업 큐를 사용하여 작업자 스레드 간에 태스크를 분배합니다.\n */\nclass ThreadPool {\n // ... 이후 단계에서 내용 추가 예정\n};\n\n} // namespace core::concurrency\n\n#endif // CORE__CONCURRENCY__THREAD_POOL_HPP_\n\n```\n\n---\n\n### 단계 2: `Job` 타입 별칭(type alias) 정의\n\n#### 1. `Job` 타입 별칭 정의\n\n이 작업은 `std::function`에 대한 공개 타입 별칭 `Job`을 정의합니다. 이는 `ThreadPool`이 실행할 작업의 종류에 대해 명확하고 서술적인 이름을 제공합니다. `std::function`을 사용하면 스레드 풀이 모든 호출 가능한 대상(자유 함수, 람다, 멤버 함수)을 작업으로 받을 수 있어 인터페이스가 매우 유연해집니다.\n\n**파일**: `include/core/concurrency/thread_pool.hpp`\n\n```cpp\nclass ThreadPool {\n public:\n using Job = std::function; ///< 실행될 작업을 나타내는 호출 가능한 객체.\n // ...\n};\n```\n\n---\n\n### 단계 3: 내부 `JobQueue` 구조체 정의\n\n#### 1. `JobQueue` 구조체 및 클래스 멤버 변수 정의\n\n이 작업은 `ThreadPool` 운영에 필요한 비공개 멤버들을 추가합니다. `JobQueue` 구조체는 버퍼 자체, 상태 변수(`head_`, `tail_`, `count_`), 동기화 프리미티브(`mutex_`, `condition_variable`들)를 포함하여, 스레드 안전하고 고정된 크기의 원형 버퍼에 대한 모든 로직과 데이터를 캡슐화합니다. `stop_flag_`와 `workers_` 벡터는 `ThreadPool` 자체의 핵심 상태를 구성하므로 함께 선언됩니다.\n\n**파일**: `include/core/concurrency/thread_pool.hpp`\n\n```cpp\nclass ThreadPool {\n // ... public 멤버들\n private:\n /**\n * @brief 작업을 보관하는 스레드 안전 큐.\n */\n struct JobQueue {\n uint32_t capacity_{0}; ///< 큐의 최대 아이템 수.\n std::vector buffer_; ///< 큐의 기반이 되는 버퍼.\n uint32_t head_{0}; ///< 큐에서 다음에 꺼내올 작업의 인덱스.\n uint32_t tail_{0}; ///< 다음에 작업이 추가될 인덱스.\n uint32_t count_{0}; ///< 현재 큐에 있는 작업의 수.\n std::atomic jobs_in_progress_{\n 0}; ///< 현재 실행 중인 작업의 수.\n\n std::mutex mutex_; ///< 큐 접근을 보호하기 위한 뮤텍스.\n std::condition_variable\n enqueue_condition_; ///< 작업이 큐에 추가될 수 있을 때 신호를 보내는 조건 변수.\n std::condition_variable\n dequeue_condition_; ///< 작업이 큐에서 꺼내질 수 있을 때 신호를 보내는 조건 변수.\n };\n\n JobQueue job_queue_; ///< 작업 큐.\n std::atomic stop_flag_{\n false}; ///< 작업자 스레드들에게 중지를 알리는 플래그.\n\n std::vector workers_; ///< 작업자 스레드 컬렉션.\n};\n```\n\n---\n\n### 단계 4: 생성자 및 소멸자 선언\n\n#### 1. 공개 생성자, 소멸자 및 삭제된 특수 멤버 선언\n\n이 작업은 `ThreadPool`의 생명 주기 관리를 위한 공개 인터페이스를 선언합니다. 생성자는 작업자 스레드와 작업 큐를 초기화하는 역할을 담당합니다. 소멸자는 스레드의 정상적인 종료를 처리합니다. 복사 및 이동 생성자/대입 연산자는 명시적으로 삭제하여 `ThreadPool` 인스턴스가 고유하며 복사하거나 이동할 수 없도록 강제합니다. 이는 스레드와 같은 기본 시스템 리소스를 관리하는 클래스의 표준적인 관행입니다.\n\n**파일**: `include/core/concurrency/thread_pool.hpp`\n\n```cpp\nclass ThreadPool {\n public:\n // ... using Job\n /**\n * @brief ThreadPool을 생성합니다.\n * @details 작업 큐를 초기화하고, 작업자 스레드를 위한 공간을 예약하며,\n * 스레드를 생성합니다.\n * @param number_of_threads 생성할 작업자 스레드의 수.\n * @param queue_capacity 작업 큐의 최대 용량.\n */\n ThreadPool(uint32_t number_of_threads, uint32_t queue_capacity);\n /**\n * @brief 모든 작업자 스레드가 종료되기를 기다린 후 ThreadPool을 소멸시킵니다.\n */\n ~ThreadPool();\n\n ThreadPool(const ThreadPool&) = delete;\n auto operator=(const ThreadPool&) -> ThreadPool& = delete;\n ThreadPool(ThreadPool&&) = delete;\n auto operator=(ThreadPool&&) -> ThreadPool& = delete;\n\n // ... 다른 public 및 private 멤버들\n};\n```\n\n---\n\n### 단계 5: 공개 `EnqueueJob` 메서드 선언\n\n#### 1. `EnqueueJob` 메서드 선언\n\n이 작업은 `ThreadPool`에 작업을 제출하기 위한 주된 공개 메서드를 선언합니다. `EnqueueJob` 메서드는 `Job` 객체를 받아 내부 `JobQueue`에 스레드 안전한 방식으로 추가하는 역할을 합니다. 이는 클라이언트가 스레드 풀과 상호작용하는 주요 진입점입니다.\n\n**파일**: `include/core/concurrency/thread_pool.hpp`\n\n```cpp\nclass ThreadPool {\n public:\n // ... 생성자, 소멸자 등\n\n /**\n * @brief 작업자 스레드가 실행할 작업을 큐에 추가합니다.\n *\n * @param job 큐에 추가할 작업.\n */\n void EnqueueJob(Job job);\n\n // ... 삭제된 특수 멤버들\n private:\n // ... private 멤버들\n};\n```\n\n---\n\n### 단계 6: 비공개 `LoopForWorker` 메서드 선언\n\n#### 1. `LoopForWorker` 메서드 선언\n\n이 작업은 각 작업자 스레드의 주 실행 루프 역할을 할 비공개 메서드를 선언합니다. 이 메서드는 `ThreadPool` 생성 시 각 작업자를 위한 새 스레드에서 실행됩니다. 이 메서드의 로직은 큐에 작업이 나타나기를 기다렸다가, 작업을 꺼내고, 실행한 다음, `stop_flag_`가 설정될 때까지 이 과정을 반복하는 것으로 구성됩니다.\n\n**파일**: `include/core/concurrency/thread_pool.hpp`\n\n```cpp\nclass ThreadPool {\n // ... public 멤버들\n private:\n /**\n * @brief 각 작업자 스레드를 위한 메인 루프.\n * @details 큐에서 작업이 사용 가능해질 때까지 기다린 후, 작업을 실행하고,\n * 다음 작업을 기다립니다.\n */\n void LoopForWorker();\n\n // ... private 멤버들\n};\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n이 작업은 헤더 파일 생성만을 포함하므로 직접적인 실행은 불가능합니다. 검증은 새 헤더가 구문적으로 올바르며 프로젝트의 빌드 시스템 내에서 성공적으로 포함되고 컴파일될 수 있는지 확인하는 것으로 이루어집니다.\n\n1. **새 헤더를 빌드 시스템에 통합합니다.**\n - 일반적으로 `CMakeLists.txt`가 해당 헤더를 라이브러리의 공개 인터페이스 일부로 올바르게 식별하도록 해야 합니다.\n2. **전체 프레임워크 라이브러리의 컴파일을 시도합니다.**\n - 프로젝트의 빌드 디렉터리에서 빌드 명령을 실행합니다.\n\n```bash\n# 빌드 디렉터리로 이동합니다 (이미 설정되었다고 가정)\ncd build/\n\n# 'core' 라이브러리 타겟 빌드를 시도합니다\ncmake --build . --target readable-code-cpp-core-framework\n```\n\n### 4.2. 예상 결과\n\n빌드 명령어는 종료 코드 0으로 성공적으로 완료되어야 합니다. 출력 결과는 빌드가 컴파일 오류 없이 완료되었음을 나타내야 하며, 이는 새 `thread_pool.hpp` 헤더가 올바르게 구성되었음을 확인시켜 줍니다.\n\n```\n[100%] Built target readable-code-cpp-core-framework\nBuild finished\n```\n","완전한 `ThreadPool` 클래스 정의, 중첩된 `JobQueue` 구조체, 모든 멤버 변수 및 메서드 선언이 포함된 헤더 파일",[1766,1768,1770,1772,1774,1776],{"_24":1767,"_83":39,"_84":97,"_85":61},"`ThreadPool` 클래스 정의",{"_24":1769,"_83":39,"_84":97,"_85":88},"`Job` 타입 별칭 정의",{"_24":1771,"_83":39,"_84":97,"_85":91},"내부 `JobQueue` 구조체 정의",{"_24":1773,"_83":39,"_84":97,"_85":94},"생성자 및 소멸자 선언",{"_24":1775,"_83":39,"_84":97,"_85":97},"public `EnqueueJob` 메서드 선언",{"_24":1777,"_83":39,"_84":97,"_85":176},"private `LoopForWorker` 메서드 선언","작업 큐 구조와 생성 및 작업 제출을 위한 public API를 포함하는 `core::concurrency::ThreadPool` 클래스 인터페이스를 정의",{"_22":1780,"_24":1781,"_75":1782,"_77":1783,"_79":1784,"_51":1791,"_42":99},"task-1751725883655","스레드 풀 생명주기 및 작업 큐잉 구현","# 작업: 스레드 풀 생명주기 및 작업 큐 추가(Enqueue) 구현\n\n> **에픽**: 코어 스레드 풀 실행기\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 스레드 관리, 작업 제출, 종료를 위한 `ThreadPool`의 핵심 로직 구현.\n- **근거**: `ThreadPool`은 전체 `readable-code-cpp-core-framework`의 기반이 되는 동시성 엔진입니다. 비동기 작업의 병렬 실행을 가능하게 하며, 이는 `Scheduler`나 `Pipeline`과 같은 상위 레벨 컴포넌트의 핵심 요구사항입니다. 생명주기(생성, 종료)와 작업 제출 메커니즘을 정확하고 견고하게 구현하는 것은 시스템 안정성과 성능에 매우 중요합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 생성자, 소멸자, `EnqueueJob` 메서드가 구현되어 스레드 안전한 작업 제출 메커니즘을 확립한 소스 파일.\n- **명세**:\n - `class ThreadPool`:\n - `ThreadPool::ThreadPool(uint32_t number_of_threads, uint32_t queue_capacity)`\n - `ThreadPool::~ThreadPool()`\n - `void ThreadPool::EnqueueJob(Job job)`\n- **결과 파일 구조**\n\n```bash\n# ./\n# └── source/\n# └── concurrency/\n# └── thread_pool.cpp <-- 수정됨\n```\n\n- **프로세스 흐름 다이어그램**\n `ThreadPool`에 작업을 제출하는 생산자(producer) 로직을 설명하는 다이어그램입니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"ThreadPool::EnqueueJob\"\n direction LR\n Start[\"EnqueueJob(job) 시작\"] --> Lock[\"std::unique_lock 획득\"];\n Lock --> Wait[\"enqueue_condition_ 대기
(큐가 가득 찼고 중단 상태가 아닐 동안)\"];\n Wait --> CheckStop[\"stop_flag_ 확인\"];\n CheckStop -- \"중단 중\" --> Stop[\"반환\"];\n CheckStop -- \"중단 아님\" --> AddJob[\"원형 버퍼에 작업 추가\"];\n AddJob --> Notify[\"dequeue_condition_ 통해
워커 하나에 알림\"];\n Notify --> End[\"EnqueueJob 종료\"];\n end\n\n Client[\"클라이언트 (예: Scheduler)\"] --> Start;\n```\n\n### 1.3. 인수 기준\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 레벨의 체크리스트이며, 각 항목에 대한 상세 구현은 섹션 3에 있습니다.\n\n- [ ] 워커 스레드를 초기화하고 시작하는 생성자 구현.\n- [ ] 중지를 신호하고 모든 워커 스레드를 조인하는 소멸자 구현.\n- [ ] 스레드 안전한 큐잉을 위해 뮤텍스와 조건 변수를 사용한 `EnqueueJob` 구현.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - **`ThreadPool`**: 현재 구현 중인 컴포넌트입니다. 아키텍처에서 정의된 대로, 공유 큐로부터 동시 작업 실행을 위해 워커 스레드 풀을 관리하는 책임을 가집니다. 이 작업은 핵심 생명주기와 제출 로직을 구현합니다.\n - **`Scheduler`**: `ThreadPool`의 주요 소비자입니다. `Scheduler`는 `EnqueueJob`을 사용하여 반복적인 작업을 워커 스레드에서 실행하도록 제출합니다.\n - **`Pipeline`**: `ThreadPool`의 주요 소비자입니다. `Pipeline`은 `EnqueueJob`을 사용하여 개별 처리 `Node`들을 비동기 실행을 위해 제출합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `source/concurrency/thread_pool.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 기준**의 항목에 해당합니다. 각 `단계`는 일련의 세부 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 워커 스레드를 초기화하고 시작하는 생성자 구현\n\n#### 1. 상태 초기화 및 워커 실행\n\n이 액션은 `ThreadPool` 생성자를 구현합니다. 로직은 먼저 생성자 인자를 기반으로 작업 큐의 내부 상태를 초기화해야 합니다. 큐의 용량을 설정하고 버퍼 크기를 조정합니다. 그 다음, 재할당을 방지하기 위해 워커 스레드 객체들을 위한 메모리를 예약합니다. 이 함수의 핵심은 지정된 수의 `std::thread` 객체를 생성하는 루프입니다. 각 스레드는 `LoopForWorker` 멤버 함수를 실행하며 즉시 시작됩니다. 스레드 생성자에 `this`를 인자로 전달하면 각 워커가 `ThreadPool` 인스턴스의 공유 상태(예: 작업 큐, 중단 플래그)에 접근할 수 있게 됩니다.\n\n**파일**: `source/concurrency/thread_pool.cpp`\n\n```cpp\n#include \"core/concurrency/thread_pool.hpp\"\n// ... other includes\n\nnamespace core::concurrency {\n\nThreadPool::ThreadPool(uint32_t number_of_threads, uint32_t queue_capacity) {\n job_queue_.capacity_ = queue_capacity;\n job_queue_.buffer_.resize(queue_capacity);\n workers_.reserve(number_of_threads);\n for (uint32_t index_of_thread = 0; index_of_thread < number_of_threads;\n ++index_of_thread) {\n workers_.emplace_back(&ThreadPool::LoopForWorker, this);\n }\n}\n\n// ...\n} // namespace core::concurrency\n```\n\n---\n\n### 단계 2: 중지를 신호하고 모든 워커 스레드를 조인하는 소멸자 구현\n\n#### 1. 종료 신호 및 모든 스레드에 알림\n\n이 액션은 `ThreadPool` 소멸자의 첫 부분을 구현하며, 정상적인 종료 절차를 시작하는 역할을 합니다. 공유 상태에 접근할 수 있는 다른 스레드와의 경쟁 상태를 방지하기 위해 공유 뮤텍스에 대한 잠금을 먼저 획득하는 것이 중요합니다. 잠금 내에서 `stop_flag_`를 `true`로 설정합니다. 이 원자적 플래그는 모든 워커 스레드와 작업 생산자에게 풀이 종료되고 있음을 알리는 신호 역할을 합니다. 플래그를 설정한 후에는 `notify_all()`을 사용하여 모든 조건 변수(`enqueue_condition_` 및 `dequeue_condition_`)에 알립니다. 이는 현재 이 조건들에서 대기 중인 모든 스레드를 깨워 `stop_flag_`를 다시 확인하고 종료 시퀀스를 시작할 수 있도록 하는 데 필수적입니다. 잠금은 스코프를 벗어날 때 해제됩니다.\n\n**파일**: `source/concurrency/thread_pool.cpp`\n\n```cpp\n// ... constructor ...\n\nThreadPool::~ThreadPool() {\n {\n const std::unique_lock Lock(job_queue_.mutex_);\n stop_flag_.store(true);\n }\n job_queue_.enqueue_condition_.notify_all();\n job_queue_.dequeue_condition_.notify_all();\n\n // ... joining logic follows ...\n}\n\n// ...\n```\n\n#### 2. 모든 워커 스레드가 종료될 때까지 대기\n\n이 액션은 소멸자의 마지막 부분을 구현합니다. 종료 신호가 보내진 후, 메인 스레드는 모든 워커 스레드가 현재 작업을 완료하고 루프를 깔끔하게 빠져나올 때까지 기다려야 합니다. 이는 `workers_` 벡터를 순회하며 각 스레드에 대해 `join()`을 호출함으로써 달성됩니다. `joinable()` 확인은 유효하고 실행 중인 스레드에 대해서만 `join()`이 호출되도록 보장하는 안전장치입니다. 이 블로킹 연산은 모든 워커 스레드가 완전히 종료될 때까지 `ThreadPool` 객체와 관련 리소스(작업 큐 등)가 파괴되지 않도록 보장하여 리소스 누수와 미정의 동작을 방지합니다.\n\n**파일**: `source/concurrency/thread_pool.cpp`\n\n```cpp\n// ... destructor signaling logic ...\n\n for (auto& worker : workers_) {\n if (worker.joinable()) {\n worker.join();\n }\n }\n}\n\n// ...\n```\n\n---\n\n### 단계 3: 스레드 안전한 큐잉을 위해 뮤텍스와 조건 변수를 사용한 `EnqueueJob` 구현\n\n#### 1. 스레드 안전한 작업 제출 구현\n\n이 액션은 클라이언트가 풀에 작업을 제출할 수 있도록 하는 `EnqueueJob` 메서드를 구현합니다. 전체 작업은 스레드로부터 안전해야 합니다. `std::unique_lock`은 공유 작업 큐를 보호하는 데 사용됩니다. 그런 다음, 이 메서드는 람다를 술어(predicate)로 사용하여 `enqueue_condition_`에서 대기합니다. 스레드는 큐에 여유 공간이 있거나(`JobsInSystem < job_queue_.capacity_`) 풀이 중단 중일 때(`stop_flag_`)만 진행합니다. 이 생산자-소비자 패턴은 큐가 오버플로우되는 것을 방지하고 낭비적인 바쁜 대기(busy-waiting)를 피합니다. 깨어났을 때 `stop_flag_`를 즉시 확인하여 종료가 시작된 후에는 작업이 큐에 추가되지 않도록 보장합니다.\n\n**파일**: `source/concurrency/thread_pool.cpp`\n\n```cpp\n// ... destructor ...\n\nvoid ThreadPool::EnqueueJob(Job job) {\n {\n std::unique_lock lock(job_queue_.mutex_);\n job_queue_.enqueue_condition_.wait(lock, [this] {\n const uint32_t JobsInSystem =\n job_queue_.count_ + job_queue_.jobs_in_progress_.load();\n return JobsInSystem < job_queue_.capacity_ || stop_flag_.load();\n });\n\n if (stop_flag_.load()) {\n return;\n }\n\n job_queue_.buffer_[job_queue_.tail_] = std::move(job);\n job_queue_.tail_ = (job_queue_.tail_ + 1U) % job_queue_.capacity_;\n ++job_queue_.count_;\n }\n job_queue_.dequeue_condition_.notify_one();\n}\n\n// ... LoopForWorker ...\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n`ThreadPool`의 생명주기와 작업 큐잉의 올바른 구현을 검증하기 위해, 단위 테스트를 작성하고 실행해야 합니다. 다음 단계는 GTest 기반 테스트 프레임워크를 가정합니다.\n\n1. **테스트 파일 생성**: `tests/unit/concurrency/test_thread_pool.cpp`.\n2. **테스트 케이스 추가**: `ThreadPoolTest.LifecycleAndJobSubmission`.\n3. **테스트 로직 구현**:\n - 고정된 수의 스레드와 큐 용량으로 `ThreadPool`을 인스턴스화합니다.\n - `std::atomic`를 카운터로 사용합니다.\n - 여러 개의 작업을 큐에 추가합니다. 각 작업은 원자적 카운터를 증가시키는 람다입니다.\n - `std::promise`와 `std::future`를 사용하여 마지막 작업이 완료되었을 때 신호를 보냅니다.\n - `ThreadPool`이 스코프를 벗어나게 하여 소멸자를 트리거합니다.\n - 소멸자가 모든 스레드를 조인하고 멈추지 않는지 단언(assert)합니다.\n - 원자적 카운터가 예상 값을 가지는지 단언하여 모든 작업이 실행되었음을 증명합니다.\n4. **테스트 빌드 및 실행**:\n\n```bash\n# 빌드 디렉토리로 이동\ncd build/\n\n# 프로젝트 빌드 (새 테스트 포함)\ncmake --build .\n\n# 특정 테스트 실행 파일 실행\n./bin/unit_tests --gtest_filter=ThreadPoolTest.LifecycleAndJobSubmission\n```\n\n### 4.2. 예상 결과\n\n테스트 실행기는 테스트 케이스가 통과했다고 보고해야 하며, 이는 작업이 성공적으로 큐에 추가되고 실행되었으며, `ThreadPool`이 정상적으로 종료되었음을 나타냅니다.\n\n```\n[==========] Running 1 test from 1 test suite.\n[----------] Global test environment set-up.\n[----------] 1 test from ThreadPoolTest\n[ RUN ] ThreadPoolTest.LifecycleAndJobSubmission\n[ OK ] ThreadPoolTest.LifecycleAndJobSubmission (XX ms)\n[----------] 1 test from ThreadPoolTest (XX ms total)\n\n[----------] Global test environment tear-down\n[==========] 1 test from 1 test suite ran. (XX ms total)\n[ PASSED ] 1 test.\n```","스레드 안전한 작업 제출 메커니즘을 구축하는, 구현된 생성자, 소멸자, `EnqueueJob` 메서드를 포함하는 소스 파일",[1785,1787,1789],{"_24":1786,"_83":39,"_84":176,"_85":61},"워커 스레드를 초기화하고 시작하는 생성자 구현",{"_24":1788,"_83":39,"_84":176,"_85":88},"정지 신호를 보내고 모든 워커 스레드를 조인하는 소멸자 구현",{"_24":1790,"_83":39,"_84":176,"_85":91},"스레드 안전한 큐잉을 위해 뮤텍스와 조건 변수를 사용하는 `EnqueueJob` 구현","스레드 관리, 작업 제출, 종료를 위한 `ThreadPool`의 핵심 로직을 구현",{"_22":1793,"_24":1794,"_75":1795,"_77":1796,"_79":1797,"_51":1808,"_42":99},"task-1751725921684","워커 스레드 루프 구현","# 작업: 워커 스레드 루프 구현\n\n> **에픽**: 코어 스레드 풀 실행기\n\n## 1. 작업 정의\n\n### 1.1. 목표\n\n- **목표**: 풀의 각 스레드에 대한 메인 실행 루프를 구성하는 `LoopForWorker` 메서드를 구현합니다.\n- **근거**: 이 메서드는 `ThreadPool`의 핵심 운영 구성 요소입니다. 각 워커 스레드는 이 루프를 실행하며, 공유된 동시성 큐에서 작업을 안전하게 가져와 실행하는 책임을 집니다. `Scheduler`나 `Pipeline`과 같은 고수준 컴포넌트들이 비동기 워크로드를 처리하기 위해 이 루프에 의존하므로, 정확하고 효율적인 구현은 전체 프레임워크의 동시성 모델에 있어 매우 중요합니다.\n\n### 1.2. 결과물\n\n- **예상 결과**: 풀이 중지될 때까지 작업을 안전하게 디큐하고 실행하는, 완벽히 기능하는 워커 루프.\n- **명세**:\n - **수정될 함수 시그니처**: `void ThreadPool::LoopForWorker()`\n - **동기화**: 공유 데이터를 보호하기 위해 `job_queue_.mutex_`와 함께 `std::unique_lock`을 사용해야 합니다.\n - **대기**: 작업이 사용 가능하거나(`job_queue_.count_ > 0`) `stop_flag_`가 설정될 때까지 `job_queue_.dequeue_condition_`에서 대기해야 합니다.\n - **상태 관리**: 순환 버퍼(`head_`, `tail_`, `count_`)와 `jobs_in_progress_` 카운터를 올바르게 관리해야 합니다.\n - **종료**: `stop_flag_`가 true이고 작업 큐가 비어 있을 때 루프를 깔끔하게 종료해야 합니다.\n - **알림**: 작업이 디큐된 후와 작업이 완전히 실행된 후, 대기 중인 생산자(producer)의 블로킹을 해제하기 위해 `job_queue_.enqueue_condition_`에 알려야 합니다.\n- **결과 파일 구조**\n\n```bash\n./\n└── source/\n └── concurrency/\n └── thread_pool.cpp <-- 수정됨\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 `LoopForWorker` 메서드를 실행하는 단일 워커 스레드의 생명주기를 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph 워커 스레드\n direction TB\n A[\"루프 시작\"] --> B{\"뮤텍스 잠금\"};\n B --> C{\"작업 대기
(조건 변수에서)\"};\n C --> D{\"중지 플래그 설정
AND 큐 비어있음?\"};\n D -- \"예\" --> E[\"루프 종료\"];\n D -- \"아니요\" --> F[\"작업 디큐\"];\n F --> G[\"큐 상태 업데이트
(head, count)\"];\n G --> H[\"진행 중 작업 카운터 증가\"];\n H --> I{\"뮤텍스 해제\"};\n I --> J[\"인큐 조건 알림\"];\n J --> K[\"작업 실행\"];\n K --> L[\"진행 중 작업 카운터 감소\"];\n L --> M[\"인큐 조건 다시 알림\"];\n M --> A;\n end\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 개략적인 체크리스트이며, 각 항목에 대한 자세한 구현은 3절에 설명되어 있습니다.\n\n- [ ] 메인 `while(true)` 루프 구현\n- [ ] 사용 가능한 작업 또는 중지 신호를 위한 조건 변수 대기\n- [ ] 공유 버퍼에서 작업을 디큐하는 로직\n- [ ] 디큐된 작업 실행\n- [ ] 큐 상태 관리를 위한 조건 변수 알림\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - **`ThreadPool`**: 구현 대상이 되는 주요 컴포넌트입니다. 기본적인 동시성 엔진으로서 워커 스레드를 관리하고 작업을 실행하는 역할을 합니다. 이 작업에서는 해당 워커 스레드들의 핵심 로직을 구현합니다.\n - **`Scheduler` / `Pipeline`**: 이 고수준 컴포넌트들은 `ThreadPool`의 주요 소비자입니다. 이들은 `LoopForWorker` 메서드가 최종적으로 디큐하여 실행할 작업(예: 주기적 태스크, 파이프라인 노드 실행)을 제출합니다. 이 루프의 정확성은 전체 비동기 처리 시스템의 기능을 직접적으로 좌우합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `source/concurrency/thread_pool.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 각 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉘어 있습니다. 각 `액션`은 제목, 명확한 서술적 설명('무엇을', '왜'를 포함), 그리고 정확한 코드 구현으로 구성됩니다.\n\n---\n\n### 단계 1: 메인 `while(true)` 루프 구현\n\n#### 1. 코어 루프와 범위 지정 잠금(Scoped Lock) 정의\n\n이 액션은 워커 생명주기의 기본 구조, 즉 지속적으로 작업을 획득하려는 무한 루프를 만듭니다. 이 루프 안에서, 디큐된 태스크를 보관할 로컬 `Job` 객체를 선언합니다. 작업을 검색하는 임계 구역이 실행되는 동안 공유 데이터 구조인 `job_queue_`를 보호하기 위해 즉시 `std::unique_lock`을 생성합니다.\n\n**파일**: `source/concurrency/thread_pool.cpp`\n\n```cpp\nvoid ThreadPool::LoopForWorker() {\n while (true) {\n Job job;\n {\n std::unique_lock lock(job_queue_.mutex_);\n // ... 조건 대기 및 디큐 로직이 여기에 추가될 것입니다\n }\n // ... 작업 실행 로직이 여기에 추가될 것입니다\n }\n}\n```\n\n---\n\n### 단계 2: 사용 가능한 작업 또는 중지 신호를 위한 조건 변수 대기\n\n#### 1. 조건 대기 구현\n\n이 액션은 핵심 동기화 메커니즘을 도입합니다. 스레드는 깨어날 때까지 CPU를 양보하고 `job_queue_.dequeue_condition_.wait()`에서 블록됩니다. 이 대기에는 예측자 람다인 `[this] { return job_queue_.count_ > 0 || stop_flag_.load(); }`가 포함되어, 가짜 각성(spurious wakeup)을 방지하고 스레드가 처리할 작업이 있거나 스레드 풀이 종료되는 경우에만 진행하도록 보장합니다.\n\n**파일**: `source/concurrency/thread_pool.cpp`\n\n```cpp\n// ... LoopForWorker 내부\n{\n std::unique_lock lock(job_queue_.mutex_);\n job_queue_.dequeue_condition_.wait(\n lock, [this] { return job_queue_.count_ > 0 || stop_flag_.load(); });\n\n // ... 종료 및 디큐 로직이 여기에 추가될 것입니다\n}\n// ...\n```\n\n#### 2. 종료 검사 구현\n\n이 액션은 종료 로직을 추가합니다. 깨어난 후, 스레드는 깨어난 이유가 중지 신호 때문인지 확인해야 합니다. 만약 `stop_flag_`가 참이고 큐가 비어 있다면, 이는 더 이상 작업이 인큐되지 않을 것이며 모든 기존 작업이 처리되었음을 의미합니다. 스레드는 `return`을 호출하여 루프를 종료하고 `ThreadPool` 소멸자가 해당 스레드에 join할 수 있도록 해야 합니다.\n\n**파일**: `source/concurrency/thread_pool.cpp`\n\n```cpp\n// ... LoopForWorker의 잠금 범위 내부\njob_queue_.dequeue_condition_.wait(\n lock, [this] { return job_queue_.count_ > 0 || stop_flag_.load(); });\n\nif (stop_flag_.load() && job_queue_.count_ == 0) {\n return;\n}\n\n// ... 디큐 로직이 여기에 추가될 것입니다\n```\n\n---\n\n### 단계 3: 공유 버퍼에서 작업을 디큐하는 로직\n\n#### 1. 작업 디큐 및 큐 상태 업데이트\n\n이 액션은 순환 버퍼에서 작업을 가져오는 것을 구현합니다. 큐의 `head_`에 위치한 작업이 로컬 `job` 변수로 이동됩니다. 그 후 `head_` 인덱스는 다음 위치로 이동하며, 필요 시 버퍼의 끝에서 처음으로 순환합니다. 큐의 항목 수인 `count_`는 감소합니다. 생산자에게 역압(backpressure) 정보를 제공하기 위해, 원자적 카운터인 `jobs_in_progress_`를 증가시켜 현재 워커가 작업 중임을 알립니다.\n\n**파일**: `source/concurrency/thread_pool.cpp`\n\n```cpp\n// ... LoopForWorker의 종료 검사 후\nif (stop_flag_.load() && job_queue_.count_ == 0) {\n return;\n}\n\njob = std::move(job_queue_.buffer_[job_queue_.head_]);\njob_queue_.head_ = (job_queue_.head_ + 1U) % job_queue_.capacity_;\n--job_queue_.count_;\njob_queue_.jobs_in_progress_.fetch_add(1, std::memory_order_relaxed);\n```\n\n---\n\n### 단계 4: 디큐된 작업의 실행\n\n#### 1. 잠금 외부에서 작업 실행\n\n이 액션은 주된 작업을 수행합니다. 결정적으로, 작업은 잠금이 해제된 후(즉, `std::unique_lock`의 범위를 벗어난 후)에 호출됩니다. 이는 잠재적으로 오래 걸릴 수 있는 작업이 다른 워커 스레드의 큐 접근을 막지 않도록 보장하는 핵심적인 성능 최적화입니다.\n\n**파일**: `source/concurrency/thread_pool.cpp`\n\n```cpp\n// ... LoopForWorker 내부\n{\n std::unique_lock lock(job_queue_.mutex_);\n // ... 모든 디큐 로직\n}\n// 이제 잠금이 해제됨\njob_queue_.enqueue_condition_.notify_one();\njob();\n// ... 최종 상태 업데이트가 여기에 추가될 것입니다\n```\n\n---\n\n### 단계 5: 큐 상태 관리를 위한 조건 변수 알림\n\n#### 1. 디큐 후 생산자에게 알림\n\n이 액션은 대기 중인 생산자 스레드(`EnqueueJob`에 있는)에게 큐에 방금 빈 슬롯이 생겼다는 신호를 보냅니다. `notify_one()` 호출은 임계 구역 바로 다음에 실행되어 생산자 하나를 깨우고, 그 생산자가 새 작업을 인큐할 수 있도록 허용합니다. 동시성을 극대화하기 위해 이 작업은 현재 작업이 실행되기 전에 수행됩니다.\n\n**파일**: `source/concurrency/thread_pool.cpp`\n\n```cpp\n// ... LoopForWorker 내부\n{\n // ... 모든 디큐 로직\n}\njob_queue_.enqueue_condition_.notify_one();\njob();\n// ...\n```\n\n#### 2. 실행 후 상태 업데이트 및 생산자에게 알림\n\n이 마지막 액션은 작업의 생명주기를 마무리합니다. 작업이 실행된 후 `jobs_in_progress_` 카운터가 감소합니다. `enqueue_condition_`에 두 번째 `notify_one()` 호출을 합니다. `EnqueueJob`의 대기 조건이 큐의 `count_`와 `jobs_in_progress_` 모두에 의존하기 때문에 이 과정은 필수적입니다. 이 알림은 생산자에게 스레드가 더 이상 바쁘지 않다는 것을 알려주므로, 큐 버퍼가 가득 찬 경우에도 생산자의 블로킹을 해제할 수 있습니다.\n\n**파일**: `source/concurrency/thread_pool.cpp`\n\n```cpp\n// ... LoopForWorker 내부\njob_queue_.enqueue_condition_.notify_one();\njob();\njob_queue_.jobs_in_progress_.fetch_sub(1, std::memory_order_relaxed);\njob_queue_.enqueue_condition_.notify_one();\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n- 구현을 검증하려면, 프로젝트를 빌드하고 `ThreadPool` 컴포넌트에 대한 테스트를 포함하는 유닛 테스트 스위트를 실행하십시오. 이 테스트들은 스레드 안전성, 작업 실행, 그리고 종료 절차를 검증합니다.\n\n```bash\n# 1. 빌드 디렉터리로 이동\ncd build\n\n# 2. 프로젝트와 테스트를 구성하고 빌드\ncmake .. -DCMAKE_BUILD_TYPE=Debug\ncmake --build .\n\n# 3. 테스트 실행\nctest --verbose\n```\n\n### 4.2. 예상 결과\n\n- `ThreadPool`을 대상으로 하는 테스트들을 포함한 모든 테스트가 오류나 교착 상태(deadlock) 없이 통과하면 검증은 성공입니다. `ctest` 출력은 100% 테스트 통과를 나타내야 합니다.\n\n```\n테스트 실행 중...\n테스트 프로젝트 /path/to/readable-code-cpp-core-framework/build\n Start 1: TestThreadPool.BasicLifecycle\n1/4 Test #1: TestThreadPool.BasicLifecycle ...... 통과 0.02 sec\n Start 2: TestThreadPool.ConcurrentEnqueue\n2/4 Test #2: TestThreadPool.ConcurrentEnqueue ... 통과 0.51 sec\n Start 3: TestThreadPool.ShutdownWithPendingJobs\n3/4 Test #3: TestThreadPool.ShutdownWithPendingJobs ... 통과 0.23 sec\n Start 4: TestOtherComponent...\n4/4 Test #4: TestOtherComponent ................. 통과 0.01 sec\n\n100% 테스트 통과, 4개 중 0개 테스트 실패\n```","풀이 중지될 때까지 작업을 안전하게 디큐하고 실행하는 완전한 기능의 워커 루프",[1798,1800,1802,1804,1806],{"_24":1799,"_83":39,"_84":192,"_85":61},"메인 `while(true)` 루프 구현",{"_24":1801,"_83":39,"_84":192,"_85":88},"사용 가능한 작업 또는 정지 신호를 위한 조건 변수 대기",{"_24":1803,"_83":39,"_84":192,"_85":91},"공유 버퍼에서 작업을 디큐하는 로직",{"_24":1805,"_83":39,"_84":192,"_85":94},"디큐된 작업 실행",{"_24":1807,"_83":39,"_84":192,"_85":97},"큐 상태 관리를 위한 조건 변수 알림","풀의 각 스레드에 대한 주 실행 루프를 구성하는 `LoopForWorker` 메서드를 구현",{"_22":1810,"_24":1811,"_75":1812,"_77":1813,"_79":1814,"_51":1823,"_42":99},"task-1751725969867","NodeResult 및 ControlFlow 구조체 정의","# 작업: NodeResult 및 ControlFlow 구조체 정의\n\n> **에픽**: 파이프라인 노드 결과 및 제어 흐름\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: `ControlFlow` 열거형과 `NodeResult` 구조체를 정의하여 파이프라인 노드의 출력을 표준화합니다.\n- **근거**: 데이터 처리 파이프라인 내에서 견고한 통신과 제어를 가능하게 하려면 각 `pipeline::Node`에 대한 표준화된 반환 규약이 필요합니다. 이 규약은 `Pipeline` 오케스트레이터가 노드의 출력 데이터와 그것이 실행 흐름에 미치는 영향을 모호함 없이 해석할 수 있도록 보장합니다. `ControlFlow` 열거형은 명시적인 신호(`kContinue`, `kSkip`, `kKill`)를 제공하며, `NodeResult` 구조체는 이 신호를 타입 소거된 데이터와 함께 묶어 파이프라인 단계 간의 기본적인 데이터 전송 객체를 형성합니다.\n\n### 1.2. 결과물\n- **예상 결과물**: `ControlFlow`와 `NodeResult`의 정의를 포함하는 헤더 전용 파일.\n- **사양**:\n - `enum class ControlFlow : std::uint8_t { kContinue, kSkip, kKill };`\n - `struct NodeResult { std::any data; ControlFlow control{ControlFlow::kContinue}; };`\n- **결과 파일 구조**\n```bash\n# ./\n# └── include/\n# └── core/\n# └── concurrency/\n# └── pipeline/\n# └── result.hpp <-- 신규\n```\n\n- **프로세스 흐름도**\n이 다이어그램은 `Pipeline` 컴포넌트가 `pipeline::Node`에 의해 반환된 `NodeResult`를 어떻게 활용하는지 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n A[\"Pipeline이 Node 실행\"] --> B{\"Node가 NodeResult 반환\"};\n B --> C{NodeResult.control 검사};\n C -- \"kContinue\" --> D[\"다음 Node 스케줄링\"];\n C -- \"kSkip\" --> E[\"현재 Pipeline 사이클 종료\"];\n C -- \"kKill\" --> F[\"전체 Pipeline 종료\"];\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] `kContinue`, `kSkip`, `kKill` 값을 가지는 `ControlFlow` 열거형 정의.\n- [ ] `NodeResult` 구조체 정의.\n- [ ] 데이터 멤버에 `std::any` 포함.\n- [ ] 구조체에 `kContinue`로 기본 설정된 `ControlFlow` 멤버 포함.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - **`pipeline::Node`**: 이 컴포넌트는 `NodeResult` 인스턴스의 *생산자*입니다. 단일 처리 단계로서, `Execute` 메서드는 `NodeResult`를 반환하도록 설계되어 출력 데이터와 제어 신호를 패키징합니다. 이 작업은 모든 `Node` 구현에 대한 표준화된 출력 규약을 정의합니다.\n - **`Pipeline`**: 이 컴포넌트는 `NodeResult` 인스턴스의 *소비자*입니다. `Node`가 실행된 후, `Pipeline` 오케스트레이터는 반환된 `NodeResult`의 `control` 멤버를 검사하여 다음 노드를 실행할지, 현재 사이클을 종료할지, 또는 전체 파이프라인을 중단할지 결정합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `include/core/concurrency/pipeline/result.hpp`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부적인 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공할 것입니다.\n\n---\n\n### 단계 1: `kContinue`, `kSkip`, `kKill` 값을 가지는 `ControlFlow` 열거형 정의\n\n#### 1. `ControlFlow` 열거형 정의\n\n이 액션은 `pipeline::Node`가 실행 후 반환할 수 있는 제어 명령을 나타내는 강타입(strongly-typed) 열거형을 설정합니다. `enum class`를 사용하면 암시적 변환과 이름 충돌을 방지할 수 있습니다. 메모리 효율성을 위해 기본 타입은 `std::uint8_t`로 지정됩니다. 세 가지 값은 `Pipeline`의 동작에 대한 포괄적인 제어를 제공합니다: 정상 작동을 위한 `kContinue`, 현재 데이터 처리 사이클을 중단하기 위한 `kSkip`, 그리고 전체 파이프라인을 중지해야 하는 치명적인 오류를 알리는 `kKill`. 이 정의는 새로운 헤더 파일 내의 `core::concurrency::pipeline` 네임스페이스에 위치할 것입니다.\n\n**파일**: `include/core/concurrency/pipeline/result.hpp`\n\n```cpp\n/**\n * @file result.hpp\n * @author movingChurch (yes@holyground.world)\n * @brief Defines the NodeResult struct and ControlFlow enum.\n * @version 1.0.0\n * @date 2025-07-04\n * @copyright movingChurch (c) 2025, All Rights Reserved.\n */\n#ifndef CORE__CONCURRENCY__PIPELINE__RESULT_HPP_\n#define CORE__CONCURRENCY__PIPELINE__RESULT_HPP_\n\n#include \n#include // Required for std::uint8_t\n\nnamespace core::concurrency::pipeline {\n\n/**\n * @brief Defines the control flow commands that a Node can return after\n * execution.\n */\nenum class ControlFlow : std::uint8_t {\n kContinue, // Continue to the next node in the pipeline.\n kSkip, // Terminate the current execution cycle, skipping all subsequent\n // nodes.\n kKill, // Terminate the entire pipeline, stopping all future cycles.\n};\n\n// ... struct definition to follow\n\n} // namespace core::concurrency::pipeline\n\n#endif // CORE__CONCURRENCY__PIPELINE__RESULT_HPP_\n\n```\n\n---\n\n### 단계 2: `NodeResult` 구조체 정의\n\n#### 1. `NodeResult` 구조체 정의\n\n이 액션은 모든 `pipeline::Node`에서 반환되는 범용 데이터 전송 객체 역할을 하는 `NodeResult` 구조체를 정의합니다. 이 구조체는 노드의 출력과 제어 명령을 함께 묶습니다. 이 단계는 세 가지 완료 조건을 동시에 충족합니다.\n\n**파일**: `include/core/concurrency/pipeline/result.hpp`\n\n```cpp\n// ... enum definition from previous step ...\n\n/**\n * @brief Represents the result of a Node's execution, containing both the\n * output data and a control flow command.\n */\nstruct NodeResult {\n std::any data;\n ControlFlow control{ControlFlow::kContinue};\n};\n\n} // namespace core::concurrency::pipeline\n// ...\n```\n\n---\n\n### 단계 3: 데이터 멤버에 `std::any` 포함\n\n#### 1. `NodeResult`에 `data` 멤버 추가\n\n이 액션은 `NodeResult` 구조체에 `std::any`를 타입으로 사용하는 `data` 멤버를 추가합니다. `std::any`의 사용은 타입 소거(type erasure)를 위한 중요한 설계 결정입니다. 이를 통해 `Pipeline` 수준에서 복잡한 템플릿 메타프로그래밍 없이도, 서로 다른 데이터 타입을 생성하고 소비하는 이종(heterogeneous) 노드들로 `Pipeline`을 구성할 수 있습니다. `NodeResult`의 소비자는 `std::any`를 예상되는 타입으로 다시 캐스팅할 책임이 있습니다. 이 액션은 이전 단계에서 `NodeResult` 구조체를 정의할 때 함께 구현됩니다.\n\n**파일**: `include/core/concurrency/pipeline/result.hpp`\n\n```cpp\n// ...\nstruct NodeResult {\n std::any data; // 이 라인이 요구사항을 충족합니다.\n ControlFlow control{ControlFlow::kContinue};\n};\n// ...\n```\n\n---\n\n### 단계 4: 구조체에 `kContinue`로 기본 설정된 `ControlFlow` 멤버 포함\n\n#### 1. `control` 멤버 추가 및 기본값 설정\n\n이 액션은 `ControlFlow` 타입의 `control` 멤버를 `NodeResult` 구조체에 추가합니다. 중요한 것은 이 멤버가 `ControlFlow::kContinue`로 값 초기화된다는 점입니다. 이 기본값 설정은 노드 구현을 크게 단순화합니다. 노드는 표준 \"계속\" 동작에서 벗어나야 할 경우에만 `control` 멤버를 명시적으로 설정하면 됩니다. 성공적인 처리라는 일반적인 경우에는 노드가 단순히 데이터만 반환하면 파이프라인이 자동으로 계속 진행됩니다. 이 액션 또한 단계 2에서 `NodeResult` 구조체를 정의할 때 함께 구현됩니다.\n\n**파일**: `include/core/concurrency/pipeline/result.hpp`\n\n```cpp\n// ...\nstruct NodeResult {\n std::any data;\n ControlFlow control{ControlFlow::kContinue}; // 이 라인이 요구사항을 충족합니다.\n};\n// ...\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n이 작업은 헤더 파일만 생성하므로, 검증은 해당 파일이 독립적이며 C++ 컴파일러로 성공적으로 컴파일될 수 있는지 확인하는 것으로 구성됩니다.\n\n1. `verify_result.cpp`라는 이름의 임시 테스트 파일을 생성합니다.\n2. 새 헤더를 포함하는 코드를 추가합니다.\n3. 테스트 파일을 컴파일합니다.\n\n```bash\n# 1. 검증 파일 생성\ncat < verify_result.cpp\n#include \"include/core/concurrency/pipeline/result.hpp\"\n\nint main() {\n core::concurrency::pipeline::NodeResult result;\n result.control = core::concurrency::pipeline::ControlFlow::kKill;\n return 0;\n}\nEOF\n\n# 2. C++17 호환 컴파일러를 사용하여 파일 컴파일\ng++ -std=c++17 -I. -c verify_result.cpp -o verify_result.o\n\n# 3. 정리\nrm verify_result.cpp verify_result.o\n```\n\n### 4.2. 예상 결과\n\n`g++` 명령은 성공적으로 실행되어 콘솔에 어떠한 오류나 경고도 출력하지 않고 목적 파일(`verify_result.o`)을 생성해야 합니다. 이후 `rm` 명령은 임시 파일들을 정리해야 합니다. 성공적인 검증은 아무런 출력도 생성하지 않습니다.","`ControlFlow`와 `NodeResult`의 정의를 포함하는 헤더 전용 파일",[1815,1817,1819,1821],{"_24":1816,"_83":39,"_84":212,"_85":61},"kContinue`, `kSkip`, `kKill` 값을 가진 `ControlFlow` 열거형 정의",{"_24":1818,"_83":39,"_84":212,"_85":88},"NodeResult` 구조체 정의",{"_24":1820,"_83":39,"_84":212,"_85":91},"데이터 멤버를 위한 `std::any` 포함",{"_24":1822,"_83":39,"_84":212,"_85":94},"구조체 내 `ControlFlow` 멤버, 기본값은 `kContinue","파이프라인 노드의 출력을 표준화하기 위해 `ControlFlow` 열거형과 `NodeResult` 구조체를 정의",{"_22":1825,"_24":1826,"_75":1827,"_77":1828,"_79":1829,"_51":1840,"_42":99},"task-1751726023449","ExecutionEntry 클래스 인터페이스 정의","# 작업: ExecutionEntry 클래스 인터페이스 정의\n\n> **에픽**: 스케줄러 실행 엔트리\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: 단일 예약 작업을 위한 데이터를 캡슐화하는 `ExecutionEntry` 클래스 인터페이스를 정의합니다.\n- **근거**: `Scheduler` 컴포넌트는 작업 컬렉션을 관리하고 가장 빠른 실행 시간을 가진 작업을 효율적으로 검색하는 메커니즘이 필요합니다. 이 작업은 작업의 고유 식별자(`TaskId`)와 다음 실행 시간(`time_point`)을 쌍으로 묶는 `ExecutionEntry` 데이터 구조를 정의합니다. 이 클래스는 `std::priority_queue`에서 사용하도록 특별히 설계되어, `Scheduler`가 O(log n)의 삽입 시간과 O(1)의 다음 작업 검색 시간으로 보류 중인 작업의 정렬된 컬렉션을 유지할 수 있게 합니다.\n\n### 1.2. 결과물\n- **예상 결과물**: 생성자, 게터, 비교 연산자를 포함하는 `ExecutionEntry` 클래스 정의가 담긴 헤더 파일.\n- **명세**:\n - `타입 별칭`: `using TaskId = uint64_t;`\n - `클래스`: `core::concurrency::ExecutionEntry`\n - `생성자`: `ExecutionEntry(std::chrono::steady_clock::time_point time, TaskId task_id)`\n - `게터`: `GetExecutionTime() const`, `GetTaskId() const`\n - `연산자`: `operator>(const ExecutionEntry& other) const -> bool`\n- **결과 파일 구조**\n```bash\n# ./\n# └── include/\n# └── core/\n# └── concurrency/\n# └── execution_entry.hpp <-- 신규\n```\n\n- **프로세스 흐름도**\n이 다이어그램은 `ExecutionEntry` 데이터 구조가 `Scheduler` 컴포넌트에서 어떻게 활용될지를 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph Scheduler 로직\n A[AddTask 외부 호출] --> B{ExecutionEntry 객체 생성};\n B --> C[\"ExecutionEntry를 std::priority_queue에 푸시\"];\n D[스케줄러 메인 루프] --> E{\"queue.top() 확인\"};\n E --> F{\"entry.GetExecutionTime() <= 현재 시간인가?\"};\n F -- 예 --> G[큐에서 엔트리를 꺼내고 작업 실행];\n F -- 아니오 --> D;\n end\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 상세 구현은 3절에 있습니다.\n\n- [ ] `TaskId` 타입 별칭 정의.\n- [ ] `ExecutionEntry` 클래스 선언.\n- [ ] 시간과 작업 ID를 인자로 받는 생성자 선언.\n- [ ] `GetExecutionTime` 및 `GetTaskId` 게터 선언.\n- [ ] 우선순위 큐 정렬을 위한 `operator>` 선언.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - `Scheduler`: `ExecutionEntry` 클래스의 주된 사용자입니다. 시간을 기준으로 작업 실행의 올바른 순서를 결정하기 위해 우선순위 큐 내에서 `ExecutionEntry` 객체를 인스턴스화하고, 저장하고, 관리합니다.\n - `ThreadPool`: `ExecutionEntry`가 `ThreadPool`과 직접 상호작용하지는 않지만, `ExecutionEntry`가 포함하는 `TaskId`는 `Scheduler`가 결국 비동기 실행을 위해 `ThreadPool`에 전달할 작업을 참조하는 역할을 합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `include/core/concurrency/execution_entry.hpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 여러 개의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `TaskId` 타입 별칭 정의\n\n#### 1. `TaskId` 타입 정의\n이 작업은 작업 식별자를 위해 프로젝트에 특화된 명확한 타입 별칭을 설정합니다. `uint64_t`를 사용하면 방대한 식별자 공간을 제공하여, 많은 반복 작업이 있는 장기 실행 애플리케이션에서 발생할 수 있는 잠재적 충돌을 방지합니다. `TaskId`를 정의하면 일반적인 정수 타입에 동시성 도메인 내에서 특정 의미를 부여하여 코드 가독성과 유지보수성을 향상시킵니다. 이것은 새 헤더 파일의 `core::concurrency` 네임스페이스 내에 위치합니다.\n\n**파일**: `include/core/concurrency/execution_entry.hpp`\n\n```cpp\n#ifndef CORE__CONCURRENCY__EXECUTION_ENTRY_HPP_\n#define CORE__CONCURRENCY__EXECUTION_ENTRY_HPP_\n\n#include \n#include \n\nnamespace core::concurrency {\n\n/**\n * @brief 예약된 작업을 위한 고유 식별자입니다.\n */\nusing TaskId = uint64_t;\n\n...\n\n} // namespace core::concurrency\n\n#endif // CORE__CONCURRENCY__EXECUTION_ENTRY_HPP_\n```\n\n---\n\n### 단계 2: `ExecutionEntry` 클래스 선언\n\n#### 1. 클래스 구조 및 private 멤버 정의\n이 작업은 `ExecutionEntry` 클래스 자체와 private 데이터 멤버를 정의합니다. 이 클래스는 단일 예약 이벤트에 필요한 상태를 캡슐화합니다. `execution_time_`은 `std::chrono::steady_clock::time_point`를 사용하는데, 이는 단조적(monotonic)이고 시스템 시계 조정에 영향을 받지 않으므로 스케줄링에 필수적입니다. `task_id_`는 실행할 작업의 식별자를 저장합니다. 이 멤버들을 private으로 유지하면 캡슐화가 강제되어 클래스의 상태가 오직 공개 인터페이스를 통해서만 조작될 수 있도록 보장합니다.\n\n**파일**: `include/core/concurrency/execution_entry.hpp`\n\n```cpp\n...\n\nclass ExecutionEntry {\n public:\n ...\n\n private:\n std::chrono::steady_clock::time_point\n execution_time_; ///< 작업 실행을 위한 정확한 시점입니다.\n TaskId task_id_; ///< 예약된 작업의 고유 식별자입니다.\n};\n\n...\n```\n\n---\n\n### 단계 3: 시간과 작업 ID를 인자로 받는 생성자 선언\n\n#### 1. public 생성자 선언\n이 작업은 `ExecutionEntry` 클래스의 public 생성자를 선언합니다. 이는 새 인스턴스를 생성하는 유일한 방법으로, 모든 `ExecutionEntry` 객체가 실행 시간과 작업 ID를 모두 가진 유효한 상태로 초기화되도록 보장합니다. 이 설계는 `Scheduler`의 맥락에서 의미가 없는, 부분적으로 형성되거나 기본 생성된 객체의 생성을 방지합니다.\n\n**파일**: `include/core/concurrency/execution_entry.hpp`\n\n```cpp\n...\n\nclass ExecutionEntry {\n public:\n /**\n * @brief 새로운 ExecutionEntry 객체를 생성합니다.\n * @param time 작업이 실행되어야 할 특정 시점입니다.\n * @param task_id 작업의 고유 식별자입니다.\n */\n ExecutionEntry(std::chrono::steady_clock::time_point time, TaskId task_id);\n\n ...\n};\n\n...\n```\n\n---\n\n### 단계 4: `GetExecutionTime` 및 `GetTaskId` 게터 선언\n\n#### 1. public 게터 메서드 선언\n이 작업은 클래스의 private 데이터에 대한 읽기 전용 접근을 제공하기 위해 두 개의 public 게터 메서드를 추가합니다. 두 메서드 모두 객체의 상태를 수정하지 않음을 나타내기 위해 `const`로 표시되어, 상수 인스턴스에서도 호출될 수 있습니다. `[[nodiscard]]` 속성은 이 함수들의 반환 값이 무시될 경우 컴파일러 경고를 발생시키는 데 사용되며, 이는 값을 가져왔지만 사용하지 않는 버그를 방지하는 데 도움이 됩니다.\n\n**파일**: `include/core/concurrency/execution_entry.hpp`\n\n```cpp\n...\n\n /**\n * @brief 예약된 작업의 실행 시간을 가져옵니다.\n * @return 실행 시간을 나타내는 `std::chrono::steady_clock::time_point`입니다.\n */\n [[nodiscard]] auto GetExecutionTime() const\n -> std::chrono::steady_clock::time_point;\n\n /**\n * @brief 작업의 고유 식별자를 가져옵니다.\n * @return 작업의 `TaskId`입니다.\n */\n [[nodiscard]] auto GetTaskId() const -> TaskId;\n\n...\n```\n\n---\n\n### 단계 5: 우선순위 큐 정렬을 위한 `operator>` 선언\n\n#### 1. '보다 큼' 비교 연산자 선언\n이 작업은 `std::priority_queue` 내에서 클래스를 사용하는 데 매우 중요한 `operator>`를 선언합니다. 기본적으로 `std::priority_queue`는 max-heap이므로 `top()`은 \"가장 큰\" 요소를 반환합니다. 큐가 *가장 이른* 시간의 엔트리를 반환하도록 만들기 위해 비교 논리를 반대로 합니다: `ExecutionEntry`는 `execution_time_`이 다른 것보다 시간상으로 *더 나중*일 경우 \"더 크다\"고 정의됩니다. 이 연산자 오버로딩을 통해 `Scheduler`는 `ExecutionEntry`를 표준 우선순위 큐에서 매끄럽게 사용하여 시간 순서대로 작업을 관리할 수 있습니다.\n\n**파일**: `include/core/concurrency/execution_entry.hpp`\n\n```cpp\n...\n\n /**\n * @brief 우선순위 큐 정렬을 위해 이 ExecutionEntry를 다른 객체와 비교합니다.\n * @details 비교는 실행 시간을 기준으로 합니다. 한 엔트리의 실행 시간이\n * 다른 엔트리보다 나중이면 \"더 크다\"고 간주합니다. 이것은\n * *가장 이른* 시간의 항목을 먼저 검색해야 하는 `std::priority_queue`에\n * 필요한 표준 동작입니다.\n * @param other 비교할 다른 ExecutionEntry 객체입니다.\n * @return 이 엔트리의 실행 시간이 다른 엔트리보다 나중이면 `true`,\n * 그렇지 않으면 `false`를 반환합니다.\n */\n [[nodiscard]] auto operator>(const ExecutionEntry& other) const -> bool;\n\n private:\n...\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n- 이 작업은 헤더 파일만 생성하므로, 검증은 올바르게 컴파일되는지 확인하는 것으로 구성됩니다. 이는 헤더를 포함하고 클래스를 인스턴스화하는 간단한 유닛 테스트를 만들어 확인할 수 있습니다.\n\n1. **새로운 테스트 파일** `tests/unit/execution_entry_test.cpp`를 생성합니다.\n2. 테스트 파일에 **다음 내용을 추가하여** 새 헤더를 포함하고 API가 정상인지 확인하기 위해 기본 인스턴스화 및 비교를 수행합니다.\n\n```cpp\n// tests/unit/execution_entry_test.cpp\n#include \n#include \n#include \n\nTEST(ExecutionEntryTest, CanBeCreatedAndAccessed) {\n const auto now = std::chrono::steady_clock::now();\n const core::concurrency::TaskId id = 123;\n const core::concurrency::ExecutionEntry entry(now, id);\n\n EXPECT_EQ(entry.GetExecutionTime(), now);\n EXPECT_EQ(entry.GetTaskId(), id);\n}\n\nTEST(ExecutionEntryTest, ComparisonOperatorWorksForPriorityQueue) {\n const auto now = std::chrono::steady_clock::now();\n const auto later = now + std::chrono::milliseconds(100);\n\n const core::concurrency::ExecutionEntry entry_now(now, 1);\n const core::concurrency::ExecutionEntry entry_later(later, 2);\n\n // operator>는 시간이 더 나중일 경우 true여야 합니다.\n // 이는 max-heap인 std::priority_queue에 올바른 동작입니다.\n EXPECT_TRUE(entry_later > entry_now);\n EXPECT_FALSE(entry_now > entry_later);\n}\n```\n\n3. 프로젝트의 **유닛 테스트를 컴파일하고 실행합니다**.\n\n```bash\n# 프로젝트의 빌드 및 테스트 명령 실행\n# (예: CMake 및 CTest 사용)\ncmake --build ./build\nctest --test-dir ./build\n```\n\n### 4.2. 예상 결과\n\n- 컴파일은 오류 없이 성공해야 합니다.\n- `ExecutionEntryTest`에 대한 유닛 테스트가 실행되고 통과해야 하며, 이는 클래스를 인스턴스화할 수 있고 비교 로직이 올바르다는 것을 나타냅니다.\n\n```\n[==========] Running 2 tests from 1 test suite.\n[----------] Global test environment set-up.\n[----------] 2 tests from ExecutionEntryTest\n[ RUN ] ExecutionEntryTest.CanBeCreatedAndAccessed\n[ OK ] ExecutionEntryTest.CanBeCreatedAndAccessed (0 ms)\n[ RUN ] ExecutionEntryTest.ComparisonOperatorWorksForPriorityQueue\n[ OK ] ExecutionEntryTest.ComparisonOperatorWorksForPriorityQueue (0 ms)\n[----------] 2 tests from ExecutionEntryTest (0 ms total)\n\n[----------] Global test environment tear-down\n[==========] 2 tests from 1 test suite ran. (0 ms total)\n[ PASSED ] 2 tests.\n```","ExecutionEntry` 클래스 정의, 생성자, getter, 비교 연산자를 포함하는 헤더 파일",[1830,1832,1834,1836,1838],{"_24":1831,"_83":39,"_84":230,"_85":61},"`TaskId` 타입 별칭 정의",{"_24":1833,"_83":39,"_84":230,"_85":88},"`ExecutionEntry` 클래스 선언",{"_24":1835,"_83":39,"_84":230,"_85":91},"타임 포인트와 태스크 ID를 받는 생성자 선언",{"_24":1837,"_83":39,"_84":230,"_85":94},"`GetExecutionTime` 및 `GetTaskId` getter 선언",{"_24":1839,"_83":39,"_84":230,"_85":97},"우선순위 큐 순서를 위한 `operator>` 선언","단일 스케줄된 작업의 데이터를 캡슐화하는 `ExecutionEntry` 클래스 인터페이스를 정의",{"_22":1842,"_24":1843,"_75":1844,"_77":1845,"_79":1846,"_51":1855,"_42":99},"task-1751726089822","ExecutionEntry 클래스 로직 구현","# 태스크: ExecutionEntry 클래스 로직 구현\n\n> **에픽**: 스케줄러 실행 엔트리\n\n## 1. 태스크 정의\n\n### 1.1. 목표\n- **목표**: `ExecutionEntry` 클래스 메서드 구현\n- **근거**: 이 태스크는 `Scheduler`에 필요한 기본 데이터 구조를 구현합니다. `ExecutionEntry` 클래스는 태스크의 고유 식별자와 다음 예약 실행 시간을 캡슐화합니다. 이를 통해 `Scheduler`는 태스크를 우선순위 큐에 배치하여, 모든 예약된 태스크를 순회하지 않고도 다음에 실행할 태스크를 효율적으로 검색할 수 있습니다. 이는 고성능 `Periodic Task Scheduler` 컴포넌트를 구축하기 위한 핵심 전제 조건입니다.\n\n### 1.2. 결과물\n- **예상 결과**: `ExecutionEntry` 생성자 및 메서드의 전체 구현을 포함하는 소스 파일.\n- **명세**:\n - 구현 대상 클래스: `core::concurrency::ExecutionEntry`\n - 메서드 시그니처:\n - `ExecutionEntry(std::chrono::steady_clock::time_point time, TaskId task_id)`\n - `auto GetExecutionTime() const -> std::chrono::steady_clock::time_point`\n - `auto GetTaskId() const -> TaskId`\n - `auto operator>(const ExecutionEntry& other) const -> bool`\n- **결과 파일 구조**\n```bash\n# ./\n# ├── include/\n# │ └── ...\n# └── source/\n# └── concurrency/\n# └── execution_entry.cpp <-- 수정됨\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 `Scheduler`가 우선순위 큐와 함께 `ExecutionEntry` 클래스를 사용하여 태스크를 관리하는 방법을 보여줍니다. `operator>` 구현은 우선순위 큐의 정렬 동작에 필수적입니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph 스케줄러\n A[\"태스크 추가\"] --> B{\"ExecutionEntry(next_time, task_id) 생성\"};\n B --> C[\"엔트리를
std::priority_queue<ExecutionEntry>에 푸시\"];\n \n subgraph \"실행 루프\"\n direction TB\n D[\"다음 태스크 가져오기\"] --> E{\"pq.top()\"};\n E --> F{\"큐에서 꺼내기\"};\n F --> G[\"EnqueueJob(entry.GetTaskId())\"];\n end\n \n C --> D\n end\n \n subgraph \"std::priority_queue (최소 힙)\"\n PQueue[\"[엔트리 C (10:01:05)]
[엔트리 A (10:01:02)]
[엔트리 B (10:01:00)]\"]\n end\n \n C -- \"정렬에 operator>() 사용\" --> PQueue\n E -- \"가장 높은 우선순위 (가장 이른 시간) 반환\" --> PQueue\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 태스크를 완료로 표시하기 위해 아래 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 3절에 기술되어 있습니다.\n\n- [ ] 멤버 초기화를 위한 생성자 구현.\n- [ ] `GetExecutionTime` getter 구현.\n- [ ] `GetTaskId` getter 구현.\n- [ ] 실행 시간 비교를 위한 `operator>` 구현.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **주요 관련 컴포넌트**:\n - **`Scheduler`**: `ExecutionEntry` 클래스의 주요 소비자입니다. `Scheduler`는 관리하는 각 주기적인 태스크에 대해 `ExecutionEntry` 객체를 인스턴스화합니다. `operator>` 오버로드를 사용하여 이러한 엔트리들의 우선순위 큐를 유지함으로써, 가장 이른 실행 시간을 가진 태스크가 항상 다음에 처리되도록 보장합니다. 이 태스크는 `Scheduler` 로직을 위한 데이터 중심의 구성 요소를 제공합니다.\n\n### 2.2. 영향받는 파일\n\n이 태스크를 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `source/concurrency/execution_entry.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 멤버 초기화를 위한 생성자 구현.\n\n#### 1. 생성자 구현\n\n이 액션은 `ExecutionEntry` 생성자를 구현합니다. 생성자의 역할은 예약된 실행 시간(`std::chrono::steady_clock::time_point`)과 고유 태스크 식별자(`TaskId`)를 받아 해당 private 멤버 변수에 저장하는 것입니다. 이를 통해 모든 `ExecutionEntry` 객체가 필요한 모든 데이터를 가진 유효한 상태로 생성되도록 보장합니다. 구현은 효율적인 초기화를 위해 멤버 이니셜라이저 리스트를 사용합니다.\n\n**파일**: `source/concurrency/execution_entry.cpp`\n\n```cpp\n#include \"core/concurrency/execution_entry.hpp\"\n// ...\n\nnamespace core::concurrency {\n\nExecutionEntry::ExecutionEntry(std::chrono::steady_clock::time_point time,\n TaskId task_id)\n : execution_time_(time), task_id_(task_id) {}\n\n// ...\n\n} // namespace core::concurrency\n```\n\n---\n\n### 단계 2: `GetExecutionTime` getter 구현.\n\n#### 1. `GetExecutionTime` 메서드 구현\n\n이 액션은 실행 시간을 검색하기 위한 public, const 한정 getter 메서드를 구현합니다. 이 메서드는 private 멤버인 `execution_time_`에 대한 읽기 전용 접근을 제공합니다. 이는 `Scheduler`가 엔트리의 상태를 수정하지 않고 예약된 시간을 검사할 수 있게 하여 캡슐화 원칙을 지키는 데 필수적입니다.\n\n**파일**: `source/concurrency/execution_entry.cpp`\n\n```cpp\n// ...\n\nauto ExecutionEntry::GetExecutionTime() const\n -> std::chrono::steady_clock::time_point {\n return execution_time_;\n}\n\n// ...\n```\n\n---\n\n### 단계 3: `GetTaskId` getter 구현.\n\n#### 1. `GetTaskId` 메서드 구현\n\n이 액션은 태스크 식별자를 검색하기 위한 public, const 한정 getter 메서드를 구현합니다. 이 메서드는 private 멤버인 `task_id_`에 대한 읽기 전용 접근을 제공합니다. `Scheduler`는 우선순위 큐에서 엔트리를 검색한 후 이 메서드를 사용하여 `ThreadPool`이 실행해야 할 특정 태스크를 식별합니다.\n\n**파일**: `source/concurrency/execution_entry.cpp`\n\n```cpp\n// ...\n\nauto ExecutionEntry::GetTaskId() const -> TaskId { return task_id_; }\n\n// ...\n```\n\n---\n\n### 단계 4: 실행 시간 비교를 위한 `operator>` 구현.\n\n#### 1. `operator>` 오버로드 구현\n\n이 액션은 '보다 큼' 비교 연산자(`>`)를 구현합니다. 이 오버로드는 이 클래스의 의도된 사용 사례에서 가장 중요한 로직입니다. `std::priority_queue`는 기본적으로 최대 힙(max-heap)으로, \"가장 큰\" 원소를 맨 위에 놓습니다. 이것이 최소 힙(min-heap)처럼 동작하게 하여(*가장 이른* 시간을 우선 처리하도록), `std::greater`를 제공할 수 있으며, 이는 내부적으로 `operator>`를 호출합니다. `a > b`가 `a.execution_time_ > b.execution_time_`일 때 참이 되도록 정의함으로써, `std::greater`를 사용하는 `std::priority_queue`가 최소 힙으로 올바르게 작동하게 할 수 있습니다. 결과적으로 가장 작은 `time_point`를 가진 엔트리가 빠른 검색을 위해 맨 위에 위치하게 됩니다.\n\n**파일**: `source/concurrency/execution_entry.cpp`\n\n```cpp\n// ...\n\nauto ExecutionEntry::operator>(const ExecutionEntry& other) const -> bool {\n return execution_time_ > other.execution_time_;\n}\n\n} // namespace core::concurrency\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n`ExecutionEntry`는 라이브러리 컴포넌트이므로 직접 실행할 수 없습니다. 검증은 프레임워크를 컴파일하고 동시성 프리미티브에 대한 단위 테스트를 실행하여 수행됩니다. 이 단위 테스트에는 `ExecutionEntry` 클래스 로직에 대한 테스트가 반드시 포함되어야 합니다(에픽 13, 태스크 13.3에 정의됨).\n\n```bash\n# 1. 빌드 디렉터리로 이동\ncd build/\n\n# 2. 테스트를 포함한 전체 프로젝트 컴파일\ncmake ..\nmake\n\n# 3. 동시성 모듈에 대한 단위 테스트 실행.\n# 정확한 명령어는 테스트 러너(예: CTest)에 따라 다를 수 있습니다.\n./tests/unit/unit_core_concurrency\n```\n\n### 4.2. 예상 결과\n\n컴파일은 오류 없이 성공해야 합니다. 테스트 러너는 `ExecutionEntry` 클래스에 대한 모든 테스트가 통과했다고 보고해야 하며, 이를 통해 생성자, getter, 비교 연산자가 명세대로 작동함을 확인합니다.\n\n```\n[==========] Running tests from 1 test suite.\n[----------] Global test environment set-up.\n[----------] N tests from ExecutionEntryTest\n[ RUN ] ExecutionEntryTest.ConstructorAndGetters\n[ OK ] ExecutionEntryTest.ConstructorAndGetters (0 ms)\n[ RUN ] ExecutionEntryTest.ComparisonOperator\n[ OK ] ExecutionEntryTest.ComparisonOperator (0 ms)\n[----------] N tests from ExecutionEntryTest (0 ms total)\n\n[----------] Global test environment tear-down\n[==========] N tests from 1 test suite ran. (0 ms total)\n[ PASSED ] N tests.\n```","`ExecutionEntry` 생성자 및 메서드의 전체 구현을 포함하는 소스 파일",[1847,1849,1851,1853],{"_24":1848,"_83":39,"_84":248,"_85":61},"멤버를 초기화하는 생성자 구현",{"_24":1850,"_83":39,"_84":248,"_85":88},"`GetExecutionTime` getter 구현",{"_24":1852,"_83":39,"_84":248,"_85":91},"`GetTaskId` getter 구현",{"_24":1854,"_83":39,"_84":248,"_85":94},"실행 시간을 비교하는 `operator>` 구현","`ExecutionEntry` 클래스 메서드를 구현",{"_22":1857,"_24":1858,"_75":1859,"_77":1860,"_79":1861,"_51":1872,"_42":99},"task-1751726139981","파일 작업 클래스 인터페이스 정의","# 작업: 파일 연산 클래스 인터페이스 정의\n\n> **에픽**: 파일 I/O 연산\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: 고수준 파일 I/O를 위한 `core::filesystem::File` 클래스 인터페이스 정의.\n- **작업 근거**: 이 작업은 파일 상호작용을 위한 표준화된 고수준 추상화를 수립합니다. `core::filesystem::File` 클래스를 생성함으로써, 표준 파일 스트림 연산의 복잡성을 캡슐화하는 깔끔하고 재사용 가능한 컴포넌트를 제공합니다. 이는 기초 유틸리티를 제공한다는 프로젝트의 핵심 목표와 일치하며, 프로젝트 의존성 다이어그램에서 볼 수 있듯이 `config::Reader` 및 `Logger`와 같은 다른 컴포넌트의 직접적인 의존성입니다.\n\n### 1.2. 결과물\n- **예상 결과**: 생성자와 읽기, 쓰기, 존재 확인 메서드를 포함하는 `File` 클래스의 헤더 파일.\n- **사양**:\n - `클래스`: `core::filesystem::File`\n - `생성자`: `explicit File(core::filesystem::Path path)`\n - `메서드`: `[[nodiscard]] auto Exists() const -> bool`\n - `메서드`: `[[nodiscard]] auto Write(const std::string& content) -> bool`\n - `메서드`: `[[nodiscard]] auto Read() const -> std::string`\n- **결과 파일 구조**\n```bash\n./\n└── include/\n └── core/\n └── filesystem/\n ├── file.hpp <-- 신규\n └── path.hpp\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 `File` 클래스와 그 의존성인 `Path` 클래스 간의 구조적 관계를 보여줍니다. `File` 클래스는 파일 시스템에서의 위치를 나타내기 위해 `Path` 객체를 캡슐화합니다.\n\n```mermaid\n%%{ init: { \"class\": { \"htmlLabels\": true } } }%%\nclassDiagram\n class Path {\n +string ToString()\n }\n class File {\n -Path path_\n +File(Path)\n +bool Exists()\n +bool Write(string)\n +string Read()\n }\n File \"1\" --o \"1\" Path : 사용\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 개괄적인 체크리스트이며, 각 항목에 대한 상세 구현은 3장에 기술되어 있습니다.\n\n- [ ] `File` 클래스 정의.\n- [ ] `core::filesystem::Path` 객체를 인자로 받는 생성자.\n- [ ] `Exists` 메서드 선언.\n- [ ] `Write` 메서드 선언.\n- [ ] `Read` 메서드 선언.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 구성 요소**:\n - `core::filesystem::Path`: 이 기존의 기초 클래스는 의존성입니다. `File` 클래스는 파일 시스템상의 위치를 식별하기 위해 `Path` 객체로 생성됩니다.\n - `core::filesystem::File`: 새로 정의되는 컴포넌트입니다. 이 컴포넌트의 책임은 내부 `std::fstream` 로직을 추상화하여 파일 I/O를 위한 고수준 API를 제공하는 것입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `include/core/filesystem/file.hpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 각 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을', '왜'), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `File` 클래스 정의.\n\n#### 1. 클래스 구조 및 Include 정의\n\n이 작업은 `file.hpp` 헤더의 기본 구조를 설정합니다. 필수적인 헤더 가드(`#ifndef...`)를 포함하고, 주요 의존성인 `core/filesystem/path.hpp`를 include하며, `core::filesystem` 네임스페이스 내에 `File` 클래스를 정의합니다. 이를 통해 프레임워크 구조 내에서 코드를 논리적으로 구성합니다.\n\n**파일**: `include/core/filesystem/file.hpp`\n\n```cpp\n/**\n * @file file.hpp\n * @author movingChurch (yes@holyground.world)\n * @brief 파일 시스템 작업을 위한 클래스를 정의합니다.\n * @version 1.0.0\n * @date 2025-07-01\n * @copyright movingChurch (c) 2025, All Rights Reserved.\n */\n#ifndef CORE__FILESYSTEM__FILE_HPP_\n#define CORE__FILESYSTEM__FILE_HPP_\n\n#include \"core/filesystem/path.hpp\"\n#include \n\nnamespace core::filesystem {\n\n/**\n * @class File\n * @brief 파일 시스템의 파일을 나타내고 관련 연산을 제공합니다.\n */\nclass File {\n public:\n // ... 메서드 선언이 여기에 추가될 것입니다\n private:\n // ... private 멤버가 여기에 추가될 것입니다\n};\n\n} // namespace core::filesystem\n\n#endif // CORE__FILESYSTEM__FILE_HPP_\n```\n\n---\n\n### 단계 2: `core::filesystem::Path` 객체를 인자로 받는 생성자.\n\n#### 1. 생성자 및 private Path 멤버 선언\n\n이 작업은 public 생성자와 이 생성자가 초기화하는 private 멤버 변수를 추가합니다. 생성자는 `core::filesystem::Path`를 값으로 받아 `File` 객체를 특정 위치와 연결합니다. 의도하지 않은 암시적 타입 변환을 방지하기 위해 `explicit`으로 선언됩니다. `path_` 멤버는 다른 클래스 메서드에서 사용할 수 있도록 이 위치를 저장합니다.\n\n**파일**: `include/core/filesystem/file.hpp`\n\n```cpp\nclass File {\n public:\n /**\n * @brief Path 객체로부터 File 객체를 생성합니다.\n * @param path 파일 경로.\n */\n explicit File(Path path);\n\n // ... 다른 메서드들\n private:\n Path path_;\n};\n```\n\n---\n\n### 단계 3: `Exists` 메서드 선언.\n\n#### 1. `Exists` 메서드 선언\n\n이 작업은 파일이 물리적으로 존재하는지 확인하기 위한 public 인터페이스를 정의합니다. 이 메서드는 `File` 객체의 상태를 수정하지 않으므로 `const`로 선언합니다. 또한, 불리언 반환값이 무시될 경우(일반적으로 논리적 오류임) 컴파일러 경고를 발생시키기 위해 `[[nodiscard]]`로 지정합니다.\n\n**파일**: `include/core/filesystem/file.hpp`\n\n```cpp\nclass File {\n public:\n // ... 생성자\n /**\n * @brief 파일 시스템에 파일이 존재하는지 확인합니다.\n * @return 파일이 존재하면 true, 그렇지 않으면 false를 반환합니다.\n */\n [[nodiscard]] auto Exists() const -> bool;\n\n // ... 다른 메서드들\n private:\n // ...\n};\n```\n\n---\n\n### 단계 4: `Write` 메서드 선언.\n\n#### 1. `Write` 메서드 선언\n\n이 작업은 파일에 데이터를 쓰기 위한 public 인터페이스를 정의합니다. 이 메서드는 쓸 내용을 효율적으로 전달하기 위해 `const std::string&`을 인자로 받습니다. 작업의 성공 여부를 알리기 위해 `bool`을 반환합니다. `[[nodiscard]]` 속성은 호출자가 잠재적인 쓰기 실패를 처리하도록 보장하는 데 매우 중요합니다.\n\n**파일**: `include/core/filesystem/file.hpp`\n\n```cpp\nclass File {\n public:\n // ...\n /**\n * @brief 파일에 내용을 씁니다.\n * @details 파일이 이미 존재할 경우 덮어씁니다.\n * @param content 파일에 쓸 문자열 내용.\n * @return 성공 시 true, 실패 시 false를 반환합니다.\n */\n [[nodiscard]] auto Write(const std::string& content) -> bool;\n\n // ... 다른 메서드들\n private:\n // ...\n};\n```\n\n---\n\n### 단계 5: `Read` 메서드 선언.\n\n#### 1. `Read` 메서드 선언\n\n이 작업은 파일의 전체 내용을 읽기 위한 public 인터페이스를 정의합니다. 이 메서드는 읽기 전용 작업이므로 `const`입니다. `std::string`을 반환하며, 성공 시 파일의 내용을, 실패 시 빈 문자열을 담게 됩니다. `[[nodiscard]]`는 호출자가 가져온 데이터를 실수로 버리는 것을 방지합니다.\n\n**파일**: `include/core/filesystem/file.hpp`\n\n```cpp\nclass File {\n public:\n // ...\n /**\n * @brief 파일의 전체 내용을 읽어들입니다.\n * @return 파일 내용을 담은 문자열을 반환합니다. 실패 시 빈 문자열을 반환합니다.\n */\n [[nodiscard]] auto Read() const -> std::string;\n\n private:\n // ...\n};\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 이 작업은 헤더 파일 생성만 포함하므로 직접 실행은 불가능합니다. 검증은 성공적인 컴파일을 통해 이루어집니다.\n- 새 헤더 파일 `include/core/filesystem/file.hpp`는 빌드 시스템(예: `CMakeLists.txt`)에 포함되어야 합니다.\n- 후속 작업인 `파일 연산 로직 구현`과 관련 단위 테스트가 최종적인 기능 검증을 제공할 것입니다. 이 작업에서는 프로젝트의 성공적인 컴파일이 주요 검증 단계입니다.\n\n```bash\n# 1. 새 파일이 빌드 시스템에 의해 추적되는지 확인합니다.\n# 2. 프로젝트 빌드를 구성합니다.\ncmake -B build .\n\n# 3. 전체 프로젝트를 컴파일합니다.\ncmake --build build\n```\n\n### 4.2. 예상 결과\n\n- `cmake --build build` 명령은 종료 코드 `0`으로 성공적으로 완료되어야 합니다.\n- `include/core/filesystem/file.hpp`와 관련된 컴파일러 오류나 경고가 없어야 합니다.\n\n```\n[100%] Built target your_library_target\n```","생성자와 읽기, 쓰기, 존재 확인 메서드를 가진 `File` 클래스의 헤더 파일",[1862,1864,1866,1868,1870],{"_24":1863,"_83":39,"_84":266,"_85":61},"`File` 클래스 정의",{"_24":1865,"_83":39,"_84":266,"_85":88},"`core::filesystem::Path` 객체를 받는 생성자",{"_24":1867,"_83":39,"_84":266,"_85":91},"`Exists` 메서드 선언",{"_24":1869,"_83":39,"_84":266,"_85":94},"`Write` 메서드 선언",{"_24":1871,"_83":39,"_84":266,"_85":97},"`Read` 메서드 선언","상위 수준 파일 I/O를 위한 `core::filesystem::File` 클래스 인터페이스를 정의",{"_22":1874,"_24":1875,"_75":1876,"_77":1877,"_79":1878,"_51":1887,"_42":99},"task-1751726185387","파일 작업 로직 구현","# 작업: 파일 연산 로직 구현\n\n> **에픽**: 파일 I/O 연산\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: 표준 라이브러리 스트림을 사용하여 I/O를 수행하도록 `core::filesystem::File` 메서드를 구현합니다.\n- **근거**: 이 작업은 파일 I/O 연산을 위한 고수준의 플랫폼 독립적인 유틸리티를 구축합니다. C++ 파일 스트림(`std::ifstream`, `std::ofstream`)과 관련된 상용구 코드를 추상화하고, 파일 시스템과 상호작용해야 하는 다른 프레임워크 컴포넌트(예: `config::Reader`, `Logger`)에 깔끔하고 일관된 인터페이스를 제공합니다. 이는 견고하고 재사용 가능한 핵심 유틸리티를 제공하려는 프로젝트의 목표와 일치합니다.\n\n### 1.2. 결과물\n- **예상 결과물**: 파일 시스템과 상호작용하는 `File` 클래스 메서드가 구현된 소스 파일.\n- **명세**:\n - `구현할 클래스`: `core::filesystem::File`\n - `메서드 시그니처`: `File::File(Path path)`\n - `메서드 시그니처`: `auto File::Write(const std::string& content) -> bool`\n - `메서드 시그니처`: `auto File::Read() const -> std::string`\n - `메서드 시그니처`: `auto File::Exists() const -> bool`\n- **결과 파일 구조**\n```bash\n# ./\n# ├── include/\n# │ └── ...\n# └── source/\n# ├── ...\n# └── filesystem/\n# └── file.cpp <-- 수정됨\n```\n\n- **프로세스 흐름도**\n 클라이언트 컴포넌트가 `File` 클래스를 사용하여 읽기 연산을 수행하는 방법을 보여주는 다이어그램입니다. `File` 클래스는 표준 라이브러리 호출을 캡슐화합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n Client[\"클라이언트 컴포넌트
(예: config::Reader)\"] --> F_Read[\"File::Read() 호출\"];\n F_Read --> IFS[\"저장된 경로로
std::ifstream 인스턴스화\"];\n IFS --> FS[\"파일 시스템에서 읽기\"];\n FS --> SS[\"데이터를
std::stringstream으로 스트리밍\"];\n SS --> R_Str[\"콘텐츠를 std::string으로 반환\"];\n R_Str --> Client;\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 개괄적인 체크리스트이며, 각 항목에 대한 상세 구현은 3절에 있습니다.\n\n- [ ] 생성자 구현.\n- [ ] `std::ofstream`을 이용한 `Write` 구현.\n- [ ] `std::ifstream` 및 `std::stringstream`을 이용한 `Read` 구현.\n- [ ] `std::filesystem::exists`를 이용한 `Exists` 구현.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - **`core::filesystem::File`**: 현재 구현 중인 컴포넌트. 파일 연산을 위한 고수준 추상화 역할을 합니다.\n - **`core::filesystem::Path`**: `File` 클래스의 의존성. I/O 연산을 위해 파일을 찾는 데 사용되는, 플랫폼에 독립적인 파일 시스템 경로 표현을 제공합니다.\n - **`std::filesystem`**: 파일 존재 여부를 확인하는 데 사용되는 C++ 표준 라이브러리 컴포넌트입니다.\n - **`std::fstream`**: 실제 파일 읽기 및 쓰기 스트림 연산에 사용되는 C++ 표준 라이브러리 컴포넌트입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `source/filesystem/file.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부적인 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을', '왜'), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 1단계: 생성자 구현.\n\n#### 1. 클래스 생성자 구현\n\n이 작업은 `File` 클래스의 생성자를 구현합니다. 생성자는 `core::filesystem::Path` 객체를 값으로 받아 `std::move`를 사용해 경로 데이터의 소유권을 private 멤버 `path_`로 효율적으로 이전합니다. 이 접근 방식은 불필요한 복사를 피하고, 클래스의 다른 모든 메서드가 사용할 파일 경로를 설정합니다.\n\n**파일**: `source/filesystem/file.cpp`\n\n```cpp\n...\n#include \"core/filesystem/path.hpp\"\n\nnamespace core::filesystem {\n\nFile::File(Path path) : path_(std::move(path)) {}\n\n...\n} // namespace core::filesystem\n```\n\n---\n\n### 2단계: `std::ofstream`을 이용한 `Write` 구현.\n\n#### 1. Write 메서드 구현\n\n이 작업은 파일 쓰기 기능을 구현합니다. `Write` 메서드는 `path_`에 지정된 파일을 쓰기 모드로 열기 위해 `std::ofstream`을 사용합니다. 먼저 파일 스트림이 성공적으로 열렸는지 확인합니다. 만약 실패하면 메서드는 `false`를 반환하여 오류를 알립니다. 그렇지 않으면, 제공된 `content` 문자열 전체를 파일에 쓰고 완료 시 `true`를 반환합니다.\n\n**파일**: `source/filesystem/file.cpp`\n\n```cpp\n...\n\nauto File::Write(const std::string& content) -> bool {\n std::ofstream file_stream(path_.ConvertToString());\n if (!file_stream.is_open()) {\n return false;\n }\n file_stream << content;\n return true;\n}\n\n...\n```\n\n---\n\n### 3단계: `std::ifstream` 및 `std::stringstream`을 이용한 `Read` 구현.\n\n#### 1. Read 메서드 구현\n\n이 작업은 파일 읽기 기능을 구현합니다. `Read` 메서드는 `path_`에 지정된 파일에 대해 `std::ifstream`을 엽니다. 파일을 열 수 없다면, 실패 신호로 빈 문자열을 반환합니다. 파일이 성공적으로 열리면, 메서드는 `std::stringstream`과 `FileStream.rdbuf()`를 이용해 파일의 전체 내용을 버퍼에 담습니다. 이는 파일 전체를 메모리로 한 번에 읽어오는 효율적인 방법입니다. 마지막으로 버퍼에 담긴 내용을 `std::string`으로 반환합니다.\n\n**파일**: `source/filesystem/file.cpp`\n\n```cpp\n...\n\nauto File::Read() const -> std::string {\n const std::ifstream FileStream(path_.ConvertToString());\n if (!FileStream.is_open()) {\n return \"\";\n }\n std::stringstream buffer;\n buffer << FileStream.rdbuf();\n return buffer.str();\n}\n\n...\n```\n\n---\n\n### 4단계: `std::filesystem::exists`를 이용한 `Exists` 구현.\n\n#### 1. Exists 메서드 구현\n\n이 작업은 파일이 파일 시스템에 존재하는지 확인하는 유틸리티 메서드를 구현합니다. `Exists` 메서드는 C++17 표준 라이브러리 함수인 `std::filesystem::exists`를 직접 감싸는 래퍼(wrapper)입니다. 내부 `path_`의 문자열 표현을 표준 함수에 전달하고 그 결과인 불리언(boolean) 값을 반환하여, 존재 여부 확인을 위한 깔끔하고 편리한 API를 제공합니다.\n\n**파일**: `source/filesystem/file.cpp`\n\n```cpp\n...\n\nauto File::Exists() const -> bool {\n return std::filesystem::exists(path_.ConvertToString());\n}\n\n} // namespace core::filesystem\n```\n\n---\n\n## 4. 검증 절차\n\n### 4.1. 검증 단계\n\n- `core::filesystem::File` 구현의 정확성을 검증하기 위해, 해당하는 유닛 테스트를 실행해야 합니다. 이 테스트들은 **에픽 13: 포괄적인 시스템 검증**(특히 작업 13.1)의 일부로 정의되어 있으며, 클래스의 모든 public 메서드를 다룹니다.\n\n```bash\n# 1. 빌드 디렉터리로 이동\ncd build/\n\n# 2. 프로젝트와 테스트를 컴파일\ncmake ..\nmake\n\n# 3. 파일시스템 모듈의 유닛 테스트를 실행\n# (참고: 실제 테스트 실행 파일 이름은 CMake 설정에 따라 다를 수 있음)\n./tests/unit/unit_tests_filesystem\n```\n\n### 4.2. 예상 결과\n\n- 테스트 러너는 `File` 컴포넌트에 대한 모든 테스트가 통과했다고 보고해야 합니다. 출력은 표준 GTest 성공 메시지와 유사해야 합니다.\n\n```\n[==========] Running all tests from 1 test suite.\n[----------] Global test environment set-up.\n[----------] N tests from FileTest\n[ RUN ] FileTest.WriteAndReadFile\n[ OK ] FileTest.WriteAndReadFile (0 ms)\n[ RUN ] FileTest.ReadNonExistentFile\n[ OK ] FileTest.ReadNonExistentFile (0 ms)\n[ RUN ] FileTest.CheckFileExistence\n[ OK ] FileTest.CheckFileExistence (0 ms)\n[----------] N tests from FileTest (0 ms total)\n\n[----------] Global test environment tear-down\n[==========] N tests from 1 test suite ran. (0 ms total)\n[ PASSED ] N tests.\n```","파일시스템과 상호 작용하는 `File` 클래스 메서드가 구현된 소스 파일",[1879,1881,1883,1885],{"_24":1880,"_83":39,"_84":284,"_85":61},"생성자 구현",{"_24":1882,"_83":39,"_84":284,"_85":88},"`std::ofstream`을 사용한 `Write` 구현",{"_24":1884,"_83":39,"_84":284,"_85":91},"`std::ifstream` 및 `std::stringstream`을 사용한 `Read` 구현",{"_24":1886,"_83":39,"_84":284,"_85":94},"`std::filesystem::exists`를 사용한 `Exists` 구현","표준 라이브러리 스트림을 사용하여 I/O를 수행하는 `core::filesystem::File` 메서드를 구현",{"_22":1889,"_24":1890,"_75":1891,"_77":1892,"_79":1893,"_51":1908,"_42":99},"task-1751726260839","YAML 리더 클래스 인터페이스 정의","# 과제: YAML 리더 클래스 인터페이스 정의\n\n> **에픽**: YAML 설정 리더\n\n## 1. 과제 정의\n\n### 1.1. 목표\n- **목표**: pImpl 이디엄을 사용하여 YAML 파싱 라이브러리를 추상화한 `core::config::Reader` 공개 인터페이스를 정의합니다.\n- **근거**: 서드파티 YAML 파싱 라이브러리로부터 완전히 분리된 안정적인 설정 읽기용 공개 API를 생성하기 위함입니다. 이러한 구현을 가리키는 포인터(Pointer to Implementation, pImpl) 이디엄을 사용하면 `Reader`의 클라이언트가 파서의 헤더를 포함할 필요가 없어지고, 컴파일 의존성을 줄이며, 향후 클라이언트 코드를 손상시키지 않고 내부 파싱 라이브러리를 변경할 수 있습니다.\n\n### 1.2. 결과물\n- **예상 결과물**: `LoadFromFile`, `Read`, `GetNode` 및 오류 처리를 포함하는 `Reader` 클래스의 공개 API가 담긴 헤더 파일.\n- **사양**:\n - `class core::config::Reader`\n - 성공 및 실패 모드 값을 포함하는 `enum class Reader::Error`.\n - `static auto LoadFromFile(const core::filesystem::Path& path) -> Reader` 팩토리 메서드.\n - 삭제된 복사 생성자 및 복사 대입 연산자.\n - 구현된 이동 생성자 및 이동 대입 연산자.\n - 값 추출을 위한 `template auto Read(const std::string& key) const -> std::optional`.\n - 계층적 접근을 위한 `auto GetNode(const std::string& key) const -> Reader`.\n - 전방 선언된 비공개 `Implementation` 클래스.\n- **결과 파일 구조**\n```bash\n# ./\n# └── include/\n# └── core/\n# └── config/\n# └── reader.hpp <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 애플리케이션에서 `Reader` 클래스를 사용하는 의도된 패턴을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n App[\"애플리케이션\"]\n FilePath[\"core::filesystem::Path\"]\n ReaderClass[\"core::config::Reader\"]\n Result[\"std::optional<T> 또는
하위 리더(Sub-Reader)\"]\n\n App -->|1\\. Path 생성| FilePath\n FilePath -->|2\\. 'LoadFromFile' 호출| ReaderClass\n App -->|3\\. 'Read<T>' 또는 'GetNode' 호출| ReaderClass\n ReaderClass -->|4\\. 값 또는 노드 반환| Result\n Result -->|5\\. 데이터 사용| App\n\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 과제를 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이것은 개략적인 체크리스트이며, 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] `Reader` 클래스 정의.\n- [ ] `Error` 열거형 정의.\n- [ ] 정적 `LoadFromFile` 팩토리 메서드 선언.\n- [ ] 이동 시맨틱 선언 및 복사 금지.\n- [ ] 템플릿 `Read` 메서드 선언.\n- [ ] `GetNode` 메서드 선언.\n- [ ] `Implementation` 클래스 전방 선언.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - **`config::Reader`**: 정의될 주요 컴포넌트입니다. YAML 파일에서 설정 값을 불러와 접근을 제공하는 책임을 가집니다. 이 과제는 이 컴포넌트의 공개 계약을 정의합니다.\n - **`core::filesystem::Path`**: `Reader`의 의존성입니다. `LoadFromFile` 메서드는 `Path` 객체를 받아 설정 파일 위치를 지정하며, 이를 통해 프레임워크 전체에서 일관되고 플랫폼 독립적인 파일 경로 처리 방식을 보장합니다.\n\n### 2.2. 영향받는 파일\n\n이 과제를 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `include/core/config/reader.hpp`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부적인 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을', '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `Reader` 클래스 정의.\n\n#### 1. 네임스페이스 및 클래스 구조 정의\n\n이 액션은 `Reader` 클래스의 기본 구조를 설정합니다. 다중 포함 오류를 방지하기 위한 표준 헤더 가드를 포함하고, 프레임워크 내 논리적 구성을 유지하기 위해 클래스를 `core::config` 네임스페이스 안에 배치합니다. 또한 필요한 표준 라이브러리 헤더와 의존성인 `core/filesystem/path.hpp` 헤더를 포함합니다.\n\n**파일**: `include/core/config/reader.hpp`\n\n```cpp\n#ifndef CORE__CONFIG__READER_HPP_\n#define CORE__CONFIG__READER_HPP_\n\n#include \n#include \n#include \n\n#include \"core/filesystem/path.hpp\"\n\nnamespace core::config {\n\n/**\n * @class Reader\n * @brief YAML 파일에서 설정 값을 읽기 위한 클래스.\n */\nclass Reader {\n // ... 클래스 멤버들이 여기에 추가될 것입니다\n};\n\n} // namespace core::config\n\n#endif // CORE__CONFIG__READER_HPP_\n```\n\n---\n\n### 단계 2: `Error` 열거형 정의.\n\n#### 1. 공개 `Error` 열거형 정의\n\n이 액션은 범위가 지정되고 강력한 타입을 갖는 `enum class`를 `Reader`의 공개 인터페이스에 추가합니다. 이는 `Reader`가 연산의 특정 결과(예: 파일을 찾을 수 없음, 잘못된 형식)를 호출 코드로 명확하고 타입-안전한 방식으로 전달하는 메커니즘을 제공하며, 정수 오류 코드의 모호성을 피합니다.\n\n**파일**: `include/core/config/reader.hpp`\n\n```cpp\nclass Reader {\n public:\n /**\n * @brief 설정을 읽을 때 발생할 수 있는 오류를 정의합니다.\n */\n enum class Error : std::uint8_t {\n kSuccess, ///< 연산이 성공했습니다.\n kFileNotFound, ///< 지정된 파일을 찾을 수 없습니다.\n kInvalidYamlFormat,///< 파일 내용이 유효한 YAML 형식이 아닙니다.\n kKeyNotFound ///< 요청한 키가 존재하지 않습니다.\n };\n // ...\n};\n```\n\n---\n\n### 단계 3: 정적 `LoadFromFile` 팩토리 메서드 선언.\n\n#### 1. 정적 팩토리 메서드 선언\n\n이 액션은 `LoadFromFile` 정적 메서드를 선언합니다. 이 메서드는 디스크의 파일로부터 `Reader` 인스턴스를 생성하는 유일한 공개 진입점 역할을 합니다. 정적 팩토리 패턴을 사용하여 파일 로딩 및 파싱의 복잡한 로직을 캡슐화하고, 사용자에게 간단하고 명확한 초기화 인터페이스를 제공합니다.\n\n**파일**: `include/core/config/reader.hpp`\n\n```cpp\nclass Reader {\n public:\n // ...\n /**\n * @brief YAML 파일에서 설정을 불러옵니다.\n * @param path YAML 파일의 경로.\n * @return 불러온 설정을 나타내는 Reader 객체.\n */\n static auto LoadFromFile(const core::filesystem::Path& path) -> Reader;\n\n // ...\n};\n```\n\n---\n\n### 단계 4: 이동 시맨틱 선언 및 복사 금지.\n\n#### 1. 리소스 관리 메서드 선언 (Rule of Five)\n\n이 액션은 `Reader`의 리소스 소유권 시맨틱을 정의합니다. 복사 생성자와 복사 대입 연산자를 삭제함으로써, 내부 YAML 데이터의 의도치 않은 비싼 복사를 방지합니다. 이동 생성자와 이동 대입 연산자를 제공함으로써, 구현 포인터(`pImpl`)의 소유권을 효율적으로 이전할 수 있게 하며, 이는 고유한 리소스를 관리하는 클래스에 필수적입니다. 소멸자 또한 `pImpl` 객체의 생명주기를 관리하기 위해 선언됩니다.\n\n**파일**: `include/core/config/reader.hpp`\n\n```cpp\nclass Reader {\n public:\n // ...\n // Rule of 5: 이동은 기본으로, 복사는 삭제\n Reader(const Reader&) = delete;\n auto operator=(const Reader&) -> Reader& = delete;\n\n /**\n * @brief 이동 생성자.\n */\n Reader(Reader&&) noexcept;\n\n /**\n * @brief 이동 대입 연산자.\n *\n * @return 이 객체에 대한 참조.\n */\n auto operator=(Reader&&) noexcept -> Reader&;\n\n /**\n * @brief 소멸자.\n */\n ~Reader();\n // ...\n};\n```\n\n---\n\n### 단계 5: 템플릿 `Read` 메서드 선언.\n\n#### 1. 값 접근 및 상태 확인 메서드 선언\n\n이 액션은 `Reader`의 상태를 조회하고 데이터를 추출하기 위한 공개 메서드들을 선언합니다. `explicit operator bool()`와 `GetError()` 메서드는 사용자가 `Reader`가 유효한 상태인지 (즉, 성공적으로 로드되었는지) 확인하고 특정 오류 코드를 검색할 수 있게 합니다. 템플릿 `Read` 메서드는 키를 통해 설정 값을 타입-안전하고 편리하게 검색하는 인터페이스를 제공하며, 키를 찾지 못하거나 타입이 일치하지 않는 경우를 우아하게 처리하기 위해 `std::optional`를 반환합니다.\n\n**파일**: `include/core/config/reader.hpp`\n\n```cpp\nclass Reader {\n public:\n // ...\n /**\n * @brief 리더가 유효한 상태인지 확인합니다.\n * @return 설정이 성공적으로 로드되었으면 true, 그렇지 않으면 false.\n */\n explicit operator bool() const;\n\n /**\n * @brief 로딩 중에 발생한 오류를 가져옵니다.\n * @return 오류 코드.\n */\n [[nodiscard]] auto GetError() const -> Error;\n\n /**\n * @brief 설정에서 특정 타입의 값을 읽습니다.\n * @tparam T 읽을 값의 타입.\n * @param key 읽을 값의 키.\n * @return 값을 찾았고 타입이 일치하면 해당 값을 포함하는 optional,\n * 그렇지 않으면 nullopt.\n */\n template \n [[nodiscard]] auto Read(const std::string& key) const -> std::optional;\n // ...\n};\n```\n\n---\n\n### 단계 6: `GetNode` 메서드 선언.\n\n#### 1. 계층적 노드 접근 메서드 선언\n\n이 액션은 `GetNode` 메서드를 선언합니다. 이 함수는 구조화된 YAML 파일 작업을 위해 매우 중요하며, 사용자가 설정의 특정 하위 섹션(또는 \"노드\")으로 범위가 지정된 새로운 `Reader` 인스턴스를 얻을 수 있게 합니다. 이를 통해 중첩된 설정 매개변수에 대한 깔끔한 계층적 접근이 가능해집니다.\n\n**파일**: `include/core/config/reader.hpp`\n\n```cpp\nclass Reader {\n public:\n // ...\n /**\n * @brief 설정의 하위 노드에 대한 새로운 Reader를 가져옵니다.\n * @param key 하위 노드의 키.\n * @return 하위 노드에 대한 새로운 Reader. 키를 찾을 수 없는 경우,\n * 반환된 리더는 유효하지 않습니다.\n */\n [[nodiscard]] auto GetNode(const std::string& key) const -> Reader;\n\n private:\n // ...\n};\n```\n\n---\n\n### 단계 7: `Implementation` 클래스 전방 선언.\n\n#### 1. pImpl 이디엄을 위한 비공개 섹션 정의\n\n이 액션은 헤더 파일에서 pImpl 설정을 완료합니다. `class Implementation;`은 전체 정의를 제공하지 않고도 `Implementation`을 타입으로 사용할 수 있게 하는 전방 선언입니다. `std::unique_ptr implementation_;` 멤버는 실제 구현에 대한 포인터를 보유하며, 이 구현은 `.cpp` 파일에서만 독점적으로 정의될 것입니다. 비공개 생성자 `explicit Reader(std::unique_ptr implementation);`는 내부 로직(`LoadFromFile` 팩토리 등)이 `Reader` 인스턴스를 생성하는 지정된 방법입니다.\n\n**파일**: `include/core/config/reader.hpp`\n\n```cpp\nclass Reader {\n public:\n // ... (public members) ...\n\n private:\n class Implementation;\n explicit Reader(std::unique_ptr implementation);\n\n std::unique_ptr implementation_;\n};\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 헤더 파일이 잘 구성되어 있고 독립적인지 확인하기 위해 임시 `main.cpp` 파일을 만들고 컴파일을 시도합니다. 이는 필요한 모든 헤더가 포함되었고 문법이 올바른지 확인하는 과정입니다.\n\n1. 다음 내용을 포함하는 `verification.cpp`라는 파일을 생성합니다:\n ```cpp\n #include \"include/core/config/reader.hpp\"\n\n int main() {\n // 목표는 새 헤더를 포함하는 이 파일이 오류 없이\n // 컴파일되는지 확인하는 것입니다. 링크하거나 실행할 필요는 없습니다.\n // 아직 구현이 없어서 클래스를 인스턴스화할 수는 없지만,\n // 헤더를 포함하는 것은 성공해야 합니다.\n return 0;\n }\n ```\n\n2. 컴파일러를 실행하여 문법 및 헤더 오류를 확인합니다. C++ 툴체인에 맞는 명령을 사용하세요.\n\n ```bash\n # g++ 사용 예시\n g++ -std=c++17 -I./ -c verification.cpp -o verification.o\n ```\n\n### 4.2. 예상 결과\n\n- 컴파일 명령은 종료 코드 `0`으로 성공적으로 완료되어야 합니다.\n- 컴파일러 오류나 경고가 발생해서는 안 됩니다.\n- 현재 디렉토리에 `verification.o` 오브젝트 파일이 생성되어, `include/core/config/reader.hpp` 헤더가 문법적으로 유효함을 확인합니다.","LoadFromFile`, `Read`, `GetNode`, 오류 처리를 포함한 public API를 가진 `Reader` 클래스의 헤더 파일",[1894,1896,1898,1900,1902,1904,1906],{"_24":1895,"_83":39,"_84":302,"_85":61},"`Reader` 클래스 정의",{"_24":1897,"_83":39,"_84":302,"_85":88},"`Error` 열거형 정의",{"_24":1899,"_83":39,"_84":302,"_85":91},"정적 `LoadFromFile` 팩토리 메서드 선언",{"_24":1901,"_83":39,"_84":302,"_85":94},"이동 의미론 선언 및 복사 금지",{"_24":1903,"_83":39,"_84":302,"_85":97},"템플릿 `Read` 메서드 선언",{"_24":1905,"_83":39,"_84":302,"_85":176},"`GetNode` 메서드 선언",{"_24":1907,"_83":39,"_84":302,"_85":192},"`Implementation` 클래스의 전방 선언","pImpl 이디엄을 사용하여 YAML 파싱 라이브러리를 추상화하는 `core::config::Reader` public 인터페이스를 정의",{"_22":1910,"_24":1911,"_75":1912,"_77":1913,"_79":1914,"_51":1925,"_42":99},"task-1751726340490","YAML 리더 비공개 구현","# 작업: YAML Reader 비공개 구현부 구현\n\n> **에픽**: YAML 설정 리더\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: 파싱 및 데이터 접근을 위해 `fkyaml` 라이브러리와 직접 상호작용하는 `Reader::Implementation` 클래스를 구현합니다.\n- **근거**: 이 작업은 모든 서드파티 YAML 라이브러리와의 상호작용을 비공개 구현 클래스(`pImpl` 이디엄) 내에 캡슐화합니다. 이 아키텍처 선택은 공개 API(`core::config::Reader`)를 특정 YAML 라이브러리로부터 분리(decouple)하여, 헤더 파일에 의존성 세부 정보가 노출되는 것을 방지합니다. 이를 통해 컴파일 의존성을 줄이고, 향후 클라이언트 코드에 미치는 영향을 최소화하면서 기본 라이브러리를 교체할 수 있습니다.\n\n### 1.2. 결과물\n- **예상 결과물**: 파싱된 YAML 노드를 보유하고 오류 상태를 관리하는 비공개 `Implementation` 클래스가 소스 파일 내에 구현됩니다.\n- **명세**:\n - `source/config/reader.cpp` 내에 `class Reader::Implementation` 정의\n - 파싱된 데이터를 저장하기 위한 비공개 멤버 `fkyaml::node root_node_`\n - 객체의 상태를 저장하기 위한 비공개 멤버 `Reader::Error error_`\n - 파싱 상태를 확인하기 위한 공개 메서드 `IsValid() const -> bool`\n - 중첩된 노드를 검색하기 위한 공개 메서드 `FindNode(const std::string& key) const -> const fkyaml::node*`\n - 로드 성공 시를 위한 공개 생성자 `Implementation(fkyaml::node&& root_node)`\n - 로드 실패 시를 위한 공개 생성자 `Implementation(Error error)`\n- **결과 파일 구조**\n```bash\n# ./\n# └── source/\n# └── config/\n# └── reader.cpp <-- 수정됨\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 공개 `Reader` 클래스가 어떻게 비공개 `Implementation` 클래스에 작업을 위임하는지 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"공개 인터페이스 (core::config::Reader)\"\n A[\"LoadFromFile(path)\"]\n B[\"Read(key)\"]\n end\n \n subgraph \"비공개 구현 (Reader::Implementation)\"\n C[\"constructor(fkyaml::node)\"]\n D[\"constructor(Error)\"]\n E[\"FindNode(key)\"]\n end\n \n subgraph \"외부 의존성\"\n F[\"fkyaml::node::deserialize()\"]\n G[\"fkyaml::node\"]\n end\n\n A -- \"성공 시\" --> F\n F -- \"노드 반환\" --> C\n A -- \"실패 시\" --> D\n \n B --> E\n E --> G\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 상세 구현은 섹션 3에 있습니다.\n\n- [ ] `Reader::Implementation` 클래스 정의\n- [ ] `fkyaml::node`를 위한 멤버 변수 추가\n- [ ] 파싱 상태를 확인하기 위한 `IsValid` 메서드 추가\n- [ ] 키를 통해 YAML 구조를 순회하기 위한 `FindNode` 메서드 추가\n- [ ] 성공 및 오류 상태를 위한 생성자 추가\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 구성 요소**:\n - `config::Reader`: 설정 값에 대한 접근을 제공하는 공개 컴포넌트입니다. 이 작업은 이의 비공개 대응물인 `Reader::Implementation`을 구현하며, 이는 YAML 데이터 구조의 파싱 및 탐색과 같은 저수준 로직을 처리합니다. `Reader` 클래스는 `Implementation` 클래스의 인스턴스를 생성하고 관리합니다.\n - `fkyaml` 라이브러리: 모든 YAML 파싱에 사용되는 외부 서드파티 라이브러리입니다. `Reader::Implementation` 클래스는 이 라이브러리, 특히 `fkyaml::node` 객체에 대한 래퍼(wrapper) 역할을 합니다.\n - `core::filesystem::Path`: 이 유틸리티 컴포넌트는 공개 `Reader::LoadFromFile` 메서드에서 설정 파일의 위치를 지정하는 데 사용됩니다. 구현 자체는 이와 직접 상호작용하지 않고 `Reader`가 제공하는 데이터 스트림을 기반으로 작동합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `source/config/reader.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 여러 개의 세부적인 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을', '왜'), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `Reader::Implementation` 클래스 정의\n\n#### 1. 클래스 기본 구조 정의\n\n이 액션은 비공개 구현을 위한 구조를 설정합니다. `Reader::Implementation` 클래스는 `reader.cpp` 파일 내의 `core::config` 네임스페이스 안에 정의되어, 동일한 파일의 `Reader` 클래스 구현에서만 접근할 수 있도록 합니다.\n\n**파일**: `source/config/reader.cpp`\n\n```cpp\n// ... includes ...\n\nnamespace core::config {\n\n/**\n * @class Reader::Implementation\n * @brief Reader 클래스의 비공개 구현입니다.\n * @details 이 클래스는 YAML 노드와 오류 상태를 보유하여 헤더 파일로부터\n * `fkyaml` 의존성을 숨깁니다.\n */\nclass Reader::Implementation {\n public:\n // 공개 메서드들은 다음 단계들에서 추가될 것입니다.\n\n private:\n // 비공개 멤버들은 다음 단계들에서 추가될 것입니다.\n};\n\n// ... 기존 Reader 메서드 구현 ...\n\n} // namespace core::config\n```\n\n---\n\n### 단계 2: `fkyaml::node`를 위한 멤버 변수 추가\n\n#### 1. 비공개 멤버 변수 추가\n\n이 액션은 `Implementation` 클래스에 핵심 데이터 멤버를 추가합니다. `root_node_`는 파싱된 전체 YAML 문서를 `fkyaml::node`로 저장합니다. `error_`는 `Reader::Error` 열거형 값을 가지며 객체의 상태(예: 파싱 성공 여부)를 나타냅니다.\n\n**파일**: `source/config/reader.cpp`\n\n```cpp\nclass Reader::Implementation {\n public:\n ...\n\n private:\n fkyaml::node root_node_;\n Reader::Error error_;\n};\n```\n\n---\n\n### 단계 3: 파싱 상태를 확인하기 위한 `IsValid` 메서드 추가\n\n#### 1. `IsValid` 메서드 구현\n\n이 액션은 공개 `IsValid` 메서드를 추가합니다. 이는 `Reader` 클래스가 `Implementation` 객체가 성공적으로 생성되었고 유효한 데이터를 가지고 있는지 간단한 불리언(boolean) 값으로 확인할 수 있게 해줍니다. 이 메서드는 `error_` 멤버를 성공 상태와 직접 비교합니다.\n\n**파일**: `source/config/reader.cpp`\n\n```cpp\nclass Reader::Implementation {\n public:\n ...\n /**\n * @brief 내부 YAML 노드가 유효한지 확인합니다.\n * @return 상태가 kSuccess이면 true, 그렇지 않으면 false를 반환합니다.\n */\n [[nodiscard]] auto IsValid() const -> bool {\n return error_ == Error::kSuccess;\n }\n ...\n private:\n ...\n};\n```\n\n---\n\n### 단계 4: 키를 통해 YAML 구조를 순회하기 위한 `FindNode` 메서드 추가\n\n#### 1. `FindNode` 메서드 구현\n\n이 액션은 데이터 검색을 위한 핵심 로직인 `FindNode` 메서드를 추가합니다. 이 메서드는 점(dot)으로 구분된 문자열 키(예: `\"server.port\"`)를 받아 `fkyaml::node` 계층 구조를 순회하여 해당 하위 노드를 찾습니다. 노드를 찾으면 해당 노드에 대한 포인터를 반환하고, 키가 유효하지 않거나 경로가 존재하지 않으면 `nullptr`를 반환합니다. 이를 통해 공개 `Reader` API에서 트리 순회 로직을 캡슐화합니다.\n\n**파일**: `source/config/reader.cpp`\n\n```cpp\nclass Reader::Implementation {\n public:\n ...\n /**\n * @brief 점으로 구분된 키로 노드를 찾습니다.\n * @param key 검색할 키 (예: \"database.host\").\n * @return 찾은 노드에 대한 포인터, 찾지 못하면 nullptr를 반환합니다.\n */\n [[nodiscard]] auto FindNode(const std::string& key) const\n -> const fkyaml::node* {\n if (!IsValid()) {\n return nullptr;\n }\n\n const fkyaml::node* current_node = &root_node_;\n std::stringstream key_stream(key);\n std::string part;\n\n while (std::getline(key_stream, part, '.')) {\n if (!current_node->is_mapping()) {\n return nullptr;\n }\n if (!current_node->contains(part)) {\n return nullptr;\n }\n current_node = &(*current_node)[part];\n }\n return current_node;\n }\n ...\n private:\n ...\n};\n```\n\n---\n\n### 단계 5: 성공 및 오류 상태를 위한 생성자 추가\n\n#### 1. 성공 및 오류 생성자 구현\n\n이 액션은 `Reader`의 팩토리 메서드에서 `Implementation` 객체 생성을 용이하게 하기 위해 두 개의 생성자를 추가합니다. 첫 번째 생성자는 `fkyaml::node`를 rvalue 레퍼런스로 받아 `root_node_`를 채우고 오류 상태를 `kSuccess`로 설정합니다. 두 번째 생성자는 `Reader::Error` 코드를 받으며, 파일 로드나 파싱이 실패했을 때 사용되어 객체를 유효하지 않은 상태로 생성합니다.\n\n**파일**: `source/config/reader.cpp`\n\n```cpp\nclass Reader::Implementation {\n public:\n /**\n * @brief 성공적인 로드를 위한 구현을 생성합니다.\n * @param root_node 루트 YAML 노드.\n */\n // NOLINTNEXTLINE(misc-include-cleaner)\n explicit Implementation(fkyaml::node&& root_node)\n : root_node_{std::move(root_node)}, error_{Error::kSuccess} {}\n\n /**\n * @brief 실패한 로드를 위한 구현을 생성합니다.\n * @param error 발생한 오류.\n */\n explicit Implementation(Error error) : error_{error} {}\n\n // ... 다른 공개 메서드들 (IsValid, FindNode) ...\n\n private:\n fkyaml::node root_node_;\n Reader::Error error_;\n};\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n비공개 `Reader::Implementation` 클래스의 정확성은 공개 `core::config::Reader` 클래스에 대한 단위 테스트를 통해 검증됩니다. 이 테스트들은 \"포괄적인 시스템 검증\" 에픽에 정의되어 있습니다. 이 작업을 검증하려면, 프로젝트를 빌드하고 설정 모듈에 대한 단위 테스트를 실행하십시오.\n\n```bash\n# 1. 빌드 디렉토리로 이동\ncd build/\n\n# 2. 프로젝트가 빌드되었는지 확인\ncmake --build .\n\n# 3. 단위 테스트 실행. CTest가 모든 테스트를 찾아 실행합니다.\n# 정확성을 위해 config reader 관련 테스트로 필터링합니다.\nctest -R config_reader_unit_tests\n```\n\n### 4.2. 예상 결과\n\n테스트 실행기는 `config_reader`와 관련된 모든 테스트가 성공적으로 통과했다고 보고해야 합니다. 출력은 다음과 유사해야 하며, 실패 보고가 없어야 합니다.\n\n```\nTest project /path/to/readable-code-cpp-core-framework/build\n Start 1: config_reader_unit_tests\n1/1 Test #1: config_reader_unit_tests ........ Passed 0.01s\n\n100% tests passed, 0 tests failed out of 1\n\nTotal Test time (real) = 0.02s\n```","YAML 노드를 보유하고 오류 상태를 관리하는, 소스 파일 내의 비공개 `Implementation` 클래스",[1915,1917,1919,1921,1923],{"_24":1916,"_83":39,"_84":320,"_85":61},"`Reader::Implementation` 클래스 정의",{"_24":1918,"_83":39,"_84":320,"_85":88},"`fkyaml::node`를 위한 멤버 변수",{"_24":1920,"_83":39,"_84":320,"_85":91},"파싱 상태를 확인하는 `IsValid` 메서드",{"_24":1922,"_83":39,"_84":320,"_85":94},"키로 YAML 구조를 순회하는 `FindNode` 메서드",{"_24":1924,"_83":39,"_84":320,"_85":97},"성공 및 오류 상태를 위한 생성자","파싱 및 데이터 접근을 위해 `fkyaml` 라이브러리와 직접 상호 작용을 처리하는 `Reader::Implementation` 클래스를 구현",{"_22":1927,"_24":1928,"_75":1929,"_77":1930,"_79":1931,"_51":1942,"_42":99},"task-1751726395838","YAML 리더 Public 메서드 로직 구현","# 과제: YAML 리더 공개 메서드 로직 구현\n\n> **에픽**: YAML 설정 리더\n\n## 1. 과제 정의\n\n### 1.1. 목표\n- **목표**: 비공개 `Implementation` 클래스에 로직을 위임하는 `Reader` 공개 메서드를 구현합니다.\n- **근거**: 이 과제는 공개 API와 비공개 구현을 연결하여 `core::config::Reader` 컴포넌트의 구현을 완료합니다. pImpl(pointer to implementation) 관용구를 활용하여 서드파티 라이브러리인 `fkYAML`을 캡슐화하고, 헤더 파일이 공개 API에 노출되는 것을 방지합니다. 이 아키텍처 선택은 컴파일 의존성을 줄이고, 빌드 시간을 개선하며, 프레임워크를 특정 YAML 파싱 라이브러리로부터 분리(디커플링)합니다. 공개 메서드는 설정 데이터를 로드하고 쿼리하기 위한 안전하고 사용자 친화적인 인터페이스를 제공합니다.\n\n### 1.2. 결과물\n- **예상 결과**: YAML 파일에서 데이터를 로드하고, 파싱하며, 데이터에 대한 접근을 제공할 수 있는 `Reader` 클래스의 완전한 구현.\n- **사양**:\n - `static auto Reader::LoadFromFile(const core::filesystem::Path& path) -> Reader;`\n - `auto Reader::Read(const std::string& key) const -> std::optional;`\n - `auto Reader::GetNode(const std::string& key) const -> Reader;`\n - `Reader::Reader(Reader&&) noexcept;`\n - `auto Reader::operator=(Reader&&) noexcept -> Reader&;`\n - `bool`, `std::int64_t`, `double`, `std::string` 타입에 대한 `Read`의 명시적 템플릿 인스턴스화.\n- **결과 파일 구조**\n```bash\n# ./\n# └── source/\n# └── config/\n# └── reader.cpp <-- 수정됨\n```\n\n- **프로세스 흐름 다이어그램**\n (이 다이어그램은 애플리케이션 컴포넌트가 `Reader` 클래스를 사용하여 설정 값을 가져오는 일반적인 사용 흐름을 보여줍니다.)\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n App[\"애플리케이션 컴포넌트\"] --> LFF[\"Reader::LoadFromFile(path) 호출\"];\n LFF --> Reader[\"Reader 인스턴스 생성됨\"];\n subgraph \"Reader 내부 로직\"\n Reader -- \"성공/오류 상태를 포함한
Reader 반환\" --> App;\n end\n App --> RT[\"reader.Read<std::string>(\\database.host\\) 호출\"];\n RT --> Find[\"내부적으로
Implementation::FindNode(\\database.host\\) 호출\"];\n Find --> Convert[\"내부적으로
fkyaml::node::get_value() 호출\"];\n Convert --> ReturnOpt[\"std::optional<string> 반환\"];\n ReturnOpt --> App;\n\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 과제를 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] 파일을 읽고 파싱 예외를 처리하는 `LoadFromFile` 구현\n- [ ] 노드를 찾아 타입 변환을 시도하는 `Read` 구현\n- [ ] 하위 트리에 대한 새 `Reader`를 생성하는 `GetNode` 구현\n- [ ] 이동 시맨틱 구현\n- [ ] 지원되는 타입에 대한 명시적 템플릿 인스턴스화\n\n## 2. 기술적 컨텍스트\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - `config::Reader`: 구현 대상의 주 컴포넌트입니다. YAML 파일로부터 설정 값을 로드하고 접근을 제공하는 책임을 가집니다. 이 과제에서는 공개 인터페이스 로직을 구현합니다.\n - `config::Reader::Implementation`: 이 과제의 로직이 위임할 비공개 구현 클래스입니다. `fkYAML` 라이브러리를 직접 감싸고 모든 파싱 및 노드 순회 로직을 캡슐화합니다.\n - `core::filesystem::Path`: `Reader::LoadFromFile`에서 플랫폼 독립적인 방식으로 설정 파일의 위치를 지정하는 데 사용되는 기본 유틸리티 클래스입니다.\n - `fkYAML` (YAML 파서 라이브러리): 모든 YAML 역직렬화 및 데이터 추출에 사용되는 서드파티 라이브러리입니다. 이 라이브러리의 사용은 의도적으로 `reader.cpp` 파일과 `Implementation` 클래스 내로 제한됩니다.\n\n### 2.2. 영향받는 파일\n\n이 과제를 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `source/config/reader.cpp`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계(Step)`는 **완료 조건**의 각 항목에 해당합니다. 각 `단계`는 일련의 세부 `작업(Action)`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을', '왜'), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 파일을 읽고 파싱 예외를 처리하도록 `LoadFromFile` 구현\n\n#### 1. 정적 `LoadFromFile` 메서드 구현\n\n이 작업은 `Reader` 클래스의 기본 팩토리 메서드를 구현합니다. 이 정적 메서드는 `core::filesystem::Path`를 인자로 받아 파일을 열고, 그 내용을 YAML 문서로 역직렬화합니다. 구현은 오류에 강건해야 합니다. 파일을 열 수 없는 경우 `Error::kFileNotFound` 상태로 초기화된 `Reader` 인스턴스를 반환합니다. 파일은 열렸지만 YAML 형식이 잘못된 경우 `fkyaml::exception`을 포착하고 `Error::kInvalidYamlFormat` 상태로 초기화된 `Reader`를 반환합니다. 성공 시, 파싱된 YAML 문서의 루트 노드를 포함하는 `Reader`를 생성합니다.\n\n**파일**: `source/config/reader.cpp`\n\n```cpp\nauto Reader::LoadFromFile(const core::filesystem::Path& path) -> Reader {\n std::ifstream file_stream(path.ConvertToString());\n if (!file_stream.good()) {\n return Reader(std::make_unique(Error::kFileNotFound));\n }\n\n try {\n fkyaml::node root_node = fkyaml::node::deserialize(file_stream);\n return Reader(std::make_unique(std::move(root_node)));\n } catch (const fkyaml::exception&) {\n return Reader(std::make_unique(Error::kInvalidYamlFormat));\n }\n}\n```\n\n---\n\n### 단계 2: 노드를 찾아 타입 변환을 시도하도록 `Read` 구현\n\n#### 1. 템플릿 `Read` 메서드 구현\n\n이 작업은 핵심 데이터 검색 메서드를 구현합니다. 키(예: \"server.port\")를 받아 `std::optional`를 반환하는 템플릿 함수입니다. 이 설계는 타입 안정성을 제공하고 값이 존재하지 않을 수 있는 경우를 명시적으로 처리합니다. 로직은 먼저 `Reader`의 상태를 확인한 다음, `implementation_->FindNode`에 노드 검색을 위임합니다. 노드를 찾으면 `fkyaml`을 사용하여 타입 변환을 시도합니다. 변환 중 발생하는 모든 예외는 포착되고 `std::nullopt`가 반환되어 사용자에게 안전하고 간단한 API를 제공합니다.\n\n**파일**: `source/config/reader.cpp`\n\n```cpp\ntemplate \nauto Reader::Read(const std::string& key) const -> std::optional {\n if (!implementation_ || !implementation_->IsValid()) {\n return std::nullopt;\n }\n\n const fkyaml::node* found_node = implementation_->FindNode(key);\n if (found_node == nullptr) {\n return std::nullopt;\n }\n\n try {\n return found_node->template get_value();\n } catch (const fkyaml::exception&) {\n return std::nullopt;\n }\n}\n```\n\n---\n\n### 단계 3: 하위 트리에 대한 새 `Reader`를 생성하도록 `GetNode` 구현\n\n#### 1. `GetNode` 메서드 구현\n\n이 작업은 계층적 설정 접근을 위한 메커니즘을 제공합니다. `GetNode` 메서드를 사용하면 설정의 특정 하위 섹션으로 범위가 지정된 `Reader` 인스턴스를 요청할 수 있습니다. `implementation_->FindNode`를 사용하여 하위 트리를 찾습니다. 하위 트리를 찾으면 `fkyaml::node`의 깊은 복사본을 만들어 새 `Reader::Implementation`을 생성하는 데 사용합니다. 이를 통해 새 `Reader`는 독립적으로 동작하게 됩니다. 키를 찾지 못했거나 현재 `Reader`가 유효하지 않은 경우, `Error::kKeyNotFound` 상태로 미리 설정된 새 `Reader`를 반환합니다.\n\n**파일**: `source/config/reader.cpp`\n\n```cpp\nauto Reader::GetNode(const std::string& key) const -> Reader {\n if (!implementation_ || !implementation_->IsValid()) {\n return Reader(std::make_unique(Error::kKeyNotFound));\n }\n\n const fkyaml::node* found_node = implementation_->FindNode(key);\n if (found_node == nullptr) {\n return Reader(std::make_unique(Error::kKeyNotFound));\n }\n\n // 값에 의한 새로운 노드를 생성하여 새 Reader 인스턴스에 전달합니다.\n return Reader(std::make_unique(fkyaml::node(*found_node)));\n}\n```\n\n---\n\n### 단계 4: 이동 시맨틱 구현\n\n#### 1. 기본(Defaulted) 이동 연산 정의\n\n이 작업은 `Reader` 클래스가 이동 시맨틱을 올바르게 처리하도록 보장합니다. `Reader` 클래스는 'Rule of Five/Zero'를 따릅니다. `std::unique_ptr`를 통해 리소스 소유권을 관리하므로 소멸자와 이동 연산이 정의되어야 합니다. 이동 생성자와 이동 대입 연산자를 명시적으로 기본값으로 설정함으로써, `std::unique_ptr`의 소유권을 정확하고 효율적으로 이전하는 컴파일러 생성 버전을 활용합니다. 이것이 가장 간단하고 안전한 접근 방식입니다.\n\n**파일**: `source/config/reader.cpp`\n\n```cpp\n...\nReader::Reader(std::unique_ptr implementation)\n : implementation_{std::move(implementation)} {}\n\nReader::~Reader() = default;\n\nReader::Reader(Reader&&) noexcept = default;\nauto Reader::operator=(Reader&&) noexcept -> Reader& = default;\n\nauto Reader::LoadFromFile(const core::filesystem::Path& path) -> Reader {\n...\n```\n\n---\n\n### 단계 5: 지원되는 타입에 대한 명시적 템플릿 인스턴스화\n\n#### 1. `Read` 템플릿 인스턴스화\n\n이 작업은 템플릿 메서드 `Read`의 정의가 헤더가 아닌 소스 파일(`.cpp`)에 있기 때문에 필요합니다. 프로그램의 다른 부분에서 특정 타입에 대한 `Reader::Read`에 링크할 수 있으려면, 컴파일러에게 해당 타입에 대한 코드를 생성하도록 지시해야 합니다. 이는 명시적 템플릿 인스턴스화를 통해 수행됩니다. 프레임워크가 지원하도록 설계된 기본 타입에 대해 `Read`를 인스턴스화하여 프로젝트 전체에서 사용할 수 있도록 보장합니다.\n\n**파일**: `source/config/reader.cpp`\n\n```cpp\n...\n try {\n return found_node->template get_value();\n } catch (const fkyaml::exception&) {\n return std::nullopt;\n }\n}\n\ntemplate auto Reader::Read(const std::string& key) const\n -> std::optional;\ntemplate auto Reader::Read(const std::string& key) const\n -> std::optional;\ntemplate auto Reader::Read(const std::string& key) const\n -> std::optional;\ntemplate auto Reader::Read(const std::string& key) const\n -> std::optional;\n\n} // namespace core::config\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 구현은 프레임워크를 컴파일하고 `config::Reader` 컴포넌트에 대한 관련 유닛 테스트를 실행하여 검증됩니다. 표준 CMake 워크플로우를 가정합니다.\n\n```bash\n# 1. CMake를 사용하여 프로젝트 구성\ncmake -B build -S .\n\n# 2. 테스트를 포함하여 프로젝트 빌드\ncmake --build build\n\n# 3. 빌드 디렉토리로 이동\ncd build\n\n# 4. Reader 컴포넌트에 특화된 유닛 테스트 실행\n# \"-R\" 플래그는 이름으로 테스트를 필터링합니다.\nctest --output-on-failure -R Reader\n```\n\n### 4.2. 예상 결과\n\n- `ctest` 명령어는 성공적으로 실행되어야 하며, `Reader` 컴포넌트와 관련된 모든 테스트가 통과했음을 보고해야 합니다. 출력은 다음과 유사해야 합니다.\n\n```\nTest project /path/to/readable-code-cpp-core-framework/build\n Start 1: ReaderTests.LoadAndReadValidFile\n1/1 Test #1: ReaderTests.LoadAndReadValidFile ... Passed 0.01 sec\n\n100% tests passed, 0 tests failed out of 1\n\nTotal Test time (real) = 0.02 sec\n```","YAML 파일에서 데이터를 로드, 파싱, 접근할 수 있는 `Reader` 클래스의 완전한 구현",[1932,1934,1936,1938,1940],{"_24":1933,"_83":39,"_84":338,"_85":61},"파일을 읽고 파싱 예외를 처리하는 `LoadFromFile` 구현",{"_24":1935,"_83":39,"_84":338,"_85":88},"노드를 찾고 타입 변환을 시도하는 `Read` 구현",{"_24":1937,"_83":39,"_84":338,"_85":91},"하위 트리를 위한 새 `Reader`를 생성하는 `GetNode` 구현",{"_24":1939,"_83":39,"_84":338,"_85":94},"이동 의미론 구현",{"_24":1941,"_83":39,"_84":338,"_85":97},"지원되는 타입에 대한 명시적 템플릿 인스턴스화","로직을 비공개 `Implementation` 클래스에 위임하는 `Reader` public 메서드를 구현",{"_22":1944,"_24":1945,"_75":1946,"_77":1947,"_79":1948,"_51":1961,"_42":99},"task-1751726437625","로거 클래스 인터페이스 정의","# 작업: 로거 클래스 인터페이스 정의\n\n> **에픽**: 다중 싱크 로깅 프레임워크\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: pImpl 이디엄을 사용하여 기본 로깅 라이브러리를 추상화하고, `core::Logger` 클래스의 공개 인터페이스를 정의합니다.\n- **근거**: 특정 백엔드 구현(`spdlog` 등)과 분리된 안정적인 공개 로깅 API를 구축하기 위함입니다. Pimpl(Pointer to Implementation) 이디엄을 사용하면 헤더 파일에 구현 세부 정보가 노출되는 것을 방지할 수 있습니다. 이는 종속 모듈의 컴파일 시간을 단축시키고, 클라이언트 코드에 영향을 주지 않으면서 기본 로깅 라이브러리를 변경할 수 있게 해줍니다.\n\n### 1.2. 결과물\n- **예상 결과**: `Level` 열거형, 생성자, 로깅 메서드, 싱크 설정 메서드를 포함하는 `Logger` 클래스의 헤더 파일.\n- **명세**:\n - `클래스`: `core::Logger`\n - `열거형`: `enum class Level : std::uint8_t` (값: `kTrace`, `kDebug`, `kInfo`, `kWarn`, `kError`, `kFatal`)\n - `생성자`: `explicit Logger(const std::string& logger_name, Level level = Level::kInfo)`\n - `공개 메서드`: `Trace(const std::string&)`, `Debug(const std::string&)`, `Info(const std::string&)`, `Warn(const std::string&)`, `Error(const std::string&)`, `Fatal(const std::string&)`, `AddFileSink(const core::filesystem::Path&)`\n - `이디엄`: 전방 선언된 `Implementation` 클래스와 `std::unique_ptr` 멤버를 통해 pImpl 이디엄을 활용합니다.\n- **결과 파일 구조**\n```bash\n# ./\n# ├── include/\n# │ └── core/\n# │ └── logger.hpp <-- 신규\n# ...\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 `pipeline::Node`와 같은 프레임워크 내 다른 컴포넌트에서 `Logger` 인터페이스가 어떻게 사용되는지를 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n Component[\"컴포넌트 (예: pipeline::Node)\"] -- \"인스턴스 생성\" --> Logger[\"core::Logger logger_instance\"]\n Component -- \"이벤트 로깅\" --> CallTrace[\"logger_instance.Trace(\\데이터 처리 중...\\)\"]\n CallTrace --> LoggerInterface[\"로거 인터페이스\"]\n LoggerInterface -- \"호출 위임\" --> Pimpl[\"비공개 구현\"]\n Pimpl --> LogSink[\"싱크에 기록 (예: 콘솔, 파일)\"]\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 아래 항목들을 완료해야 합니다. 이는 개략적인 체크리스트이며, 각 항목에 대한 자세한 구현은 3장에 기술되어 있습니다.\n\n- [ ] `Logger` 클래스 정의\n- [ ] `Level` 열거형 정의\n- [ ] 이름과 레벨을 인자로 받는 생성자\n- [ ] 각 로그 레벨(`Trace`, `Debug` 등)에 대한 공개 메서드\n- [ ] 공개 `AddFileSink` 메서드\n- [ ] `Implementation` 클래스에 대한 전방 선언\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - **`core::Logger` (본 작업)**: 이벤트 로깅을 위한 시스템 전반의 다중 레벨 인터페이스를 제공하는 핵심 유틸리티입니다. 이 작업에서는 공개 계약(public contract)을 정의합니다.\n - **`core::filesystem::Path`**: `AddFileSink` 메서드에서 플랫폼 독립적인 방식으로 로그 파일 위치를 지정하는 데 사용되는 의존성입니다.\n - **클라이언트 컴포넌트 (`Pipeline`, `Scheduler` 등)**: 상위 수준의 데이터 흐름에 설명된 대로, 자신의 상태와 운영 이벤트를 보고하기 위해 `Logger` 인터페이스를 사용할 상위 컴포넌트입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `include/core/logger.hpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `Step`은 **완료 조건**의 항목에 해당합니다. 각 `Step`은 세부적인 `Action`으로 나뉩니다. 각 `Action`에 대해 제목, 명확한 설명('무엇을', '왜'), 그리고 정확한 코드를 제공해야 합니다.\n\n---\n\n### Step 1: `Logger` 클래스 정의\n\n#### 1. 보일러플레이트 및 Include 구문 작성\n\n이 작업은 표준 인클루드 가드, 필요한 C++ 표준 라이브러리 헤더, 그리고 `core::filesystem::Path`에 대한 필수 의존성을 포함하는 `logger.hpp` 헤더 파일을 생성합니다. `core` 네임스페이스는 프레임워크의 컴포넌트를 캡슐화하기 위해 정의됩니다.\n\n**파일**: `include/core/logger.hpp`\n\n```cpp\n#ifndef CORE__LOGGER_HPP\n#define CORE__LOGGER_HPP\n\n#include \n#include \n\n#include \"core/filesystem/path.hpp\"\n\nnamespace core {\n\nclass Logger {\n public:\n // ... 다음 단계에서 내용 추가 예정 ...\n\n private:\n // ... 다음 단계에서 내용 추가 예정 ...\n};\n\n} // namespace core\n\n#endif // CORE__LOGGER_HPP\n```\n\n#### 2. 클래스 생명주기 의미론 정의\n\n이 작업은 로거의 소멸자를 정의하고, 복사 생성자와 복사 대입 연산자는 명시적으로 삭제하며, 이동 의미론은 기본값으로 설정합니다. 이를 통해 `Logger`는 pImpl 포인터와 같은 고유한 리소스를 관리하는 클래스에 적합한 이동 전용(move-only) 타입이 됩니다.\n\n**파일**: `include/core/logger.hpp`\n\n```cpp\nclass Logger {\n public:\n // ...\n ~Logger();\n\n Logger(const Logger&) = delete;\n auto operator=(const Logger&) -> Logger& = delete;\n Logger(Logger&&) noexcept = default;\n auto operator=(Logger&&) noexcept -> Logger& = default;\n // ...\n\n private:\n // ...\n};\n```\n\n---\n\n### Step 2: `Level` 열거형 정의\n\n#### 1. `Level` 열거형 클래스 정의\n\n이 작업은 로깅 심각도 레벨을 위한 강력한 타입의 `enum class`를 정의합니다. 기본 타입을 `std::uint8_t`로 지정하여 일관된 메모리 공간을 보장하고 정수 타입으로의 암시적 변환을 방지하여 타입 안정성을 향상시킵니다. 레벨은 가장 상세한(`kTrace`) 레벨부터 가장 심각한(`kFatal`) 레벨 순으로 정렬됩니다.\n\n**파일**: `include/core/logger.hpp`\n\n```cpp\nclass Logger {\n public:\n /**\n * @enum Level\n * @brief 로그 메시지의 심각도 레벨을 정의합니다.\n */\n enum class Level : std::uint8_t {\n kTrace = 0U, ///< 상세한 추적 정보입니다.\n kDebug = 1U, ///< 디버그 수준 메시지입니다.\n kInfo = 2U, ///< 정보성 메시지입니다.\n kWarn = 3U, ///< 잠재적 문제를 나타내는 경고입니다.\n kError = 4U, ///< 기능에 영향을 주는 오류입니다.\n kFatal = 5U ///< 애플리케이션을 종료시키는 치명적인 오류입니다.\n };\n\n // ...\n};\n```\n\n---\n\n### Step 3: 이름과 레벨을 인자로 받는 생성자\n\n#### 1. `Logger` 생성자 선언\n\n이 작업은 `Logger`의 `explicit` 생성자를 선언합니다. `explicit` 키워드는 `std::string`에서 `Logger` 인스턴스로의 의도치 않은 암시적 변환을 방지합니다. 편의를 위해 기본 `level`을 `kInfo`로 제공하여, 합리적인 기본 상세도를 설정합니다.\n\n**파일**: `include/core/logger.hpp`\n\n```cpp\nclass Logger {\n public:\n // ... (enum Level)\n\n /**\n * @brief 지정된 이름과 로깅 레벨로 로거를 생성합니다.\n * @param logger_name [in] 로그에 표시될 로거의 이름입니다.\n * @param level [in] 기록될 메시지의 최소 레벨입니다.\n */\n explicit Logger(const std::string& logger_name, Level level = Level::kInfo);\n\n ~Logger();\n // ...\n};\n```\n\n---\n\n### Step 4: 각 로그 레벨(`Trace`, `Debug` 등)에 대한 공개 메서드\n\n#### 1. 공개 로깅 메서드 선언\n\n이 작업은 각 심각도 레벨에 해당하는 공개 메서드 세트를 선언합니다. 이를 통해 클라이언트 코드는 매번 호출 시 레벨을 인자로 전달할 필요 없이, 깔끔하고 직관적인 API로 메시지를 로깅할 수 있습니다. 이 메서드들의 구현은 내부 `Log` 함수로 위임될 것입니다.\n\n**파일**: `include/core/logger.hpp`\n\n```cpp\nclass Logger {\n public:\n // ... (생성자 및 소멸자)\n \n void Trace(const std::string& message);\n void Debug(const std::string& message);\n void Info(const std::string& message);\n void Warn(const std::string& message);\n void Error(const std::string& message);\n void Fatal(const std::string& message);\n\n // ...\n};\n```\n\n---\n\n### Step 5: 공개 `AddFileSink` 메서드\n\n#### 1. `AddFileSink` 메서드 선언\n\n이 작업은 사용자가 로거에 파일 기반 출력을 동적으로 추가할 수 있도록 하는 `AddFileSink` 메서드를 선언합니다. 이 메서드는 인자로 `core::filesystem::Path`를 받아, 프로젝트의 파일 시스템 추상화를 활용하여 플랫폼 독립적인 경로 처리를 보장합니다.\n\n**파일**: `include/core/logger.hpp`\n\n```cpp\nclass Logger {\n public:\n // ... (로깅 메서드)\n\n /**\n * @brief 로거에 파일 싱크를 추가합니다.\n * @param file_path [in] 로그 파일의 경로입니다.\n */\n void AddFileSink(const core::filesystem::Path& file_path);\n\n private:\n // ...\n};\n```\n\n---\n\n### Step 6: `Implementation` 클래스에 대한 전방 선언\n\n#### 1. pImpl 멤버 정의\n\n이 작업은 pImpl 이디엄 설정을 완료합니다. 내부적으로 사용할 비공개 `Log` 메서드를 선언합니다. `Implementation` 클래스는 전방 선언되어 전체 정의를 포함할 필요가 없습니다. 이 클래스를 가리키는 `std::unique_ptr`가 비공개 멤버로 추가되어, 실제 로깅 구현에 대한 포인터를 보유하게 됩니다.\n\n**파일**: `include/core/logger.hpp`\n\n```cpp\nclass Logger {\n // ... (공개 멤버)\n\n private:\n void Log(Level level, const std::string& message);\n\n class Implementation;\n std::unique_ptr logger_implementation_;\n};\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- 이 작업의 주된 검증은 성공적인 컴파일입니다. 전용 유닛 테스트는 추후 다른 작업에서 추가될 것입니다. 검증을 위해, 새로운 `include/core/logger.hpp` 파일을 추가한 후 프로젝트가 오류 없이 빌드되는지 확인해야 합니다.\n\n```bash\n# 'build' 디렉터리에 CMake 기반 빌드 시스템이 있다고 가정\n\n# 1. build 디렉터리로 이동\ncd build/\n\n# 2. 필요한 경우 프로젝트 구성\ncmake ..\n\n# 3. 프로젝트 빌드. logger.hpp에서 발생하는 오류나\n# 경고 없이 빌드가 완료되어야 합니다.\nmake\n```\n\n### 4.2. 예상 결과\n\n- `make` 명령어는 종료 코드 `0`으로 성공적으로 완료되어야 합니다.\n- 빌드 출력은 컴파일이 `100%` 완료되었음을 보여주어야 하며, `include/core/logger.hpp`와 관련된 컴파일러 오류나 경고를 포함해서는 안 됩니다.\n\n```\n[100%] Built target your_library_or_executable\n```","Level` 열거형, 생성자, 로깅 메서드, 싱크 구성 메서드를 가진 `Logger` 클래스의 헤더 파일",[1949,1951,1953,1955,1957,1959],{"_24":1950,"_83":39,"_84":356,"_85":61},"`Logger` 클래스 정의",{"_24":1952,"_83":39,"_84":356,"_85":88},"`Level` 열거형 정의",{"_24":1954,"_83":39,"_84":356,"_85":91},"이름과 레벨을 받는 생성자",{"_24":1956,"_83":39,"_84":356,"_85":94},"각 로그 레벨(`Trace`, `Debug` 등)에 대한 public 메서드",{"_24":1958,"_83":39,"_84":356,"_85":97},"public `AddFileSink` 메서드",{"_24":1960,"_83":39,"_84":356,"_85":176},"`Implementation` 클래스에 대한 전방 선언","pImpl 이디엄을 사용하여 기본 로깅 라이브러리를 추상화하는 `core::Logger` 클래스 public 인터페이스를 정의",{"_22":1963,"_24":1964,"_75":1965,"_77":1966,"_79":1967,"_51":1980,"_42":99},"task-1751726496128","spdlog를 사용한 로거 비공개 구현","# 작업: spdlog를 사용한 Logger 비공개 구현체 구현\n\n> **Epic**: 다중 싱크 로깅 프레임워크\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: 실제 로깅 기능을 제공하기 위해 `spdlog` 라이브러리를 래핑하는 `Logger::Implementation` 클래스를 구현합니다.\n- **근거**: 이 작업은 PImpl(Pointer to Implementation) 이디엄을 활용하여 서드파티 `spdlog` 라이브러리를 캡슐화합니다. 이 아키텍처는 공개 `Logger` API를 내부 구현으로부터 분리하여, `spdlog` 관련 세부 정보를 프레임워크의 나머지 부분으로부터 숨깁니다. 이 접근 방식은 모듈성을 향상시키고, 공개 `logger.hpp`에서 `spdlog` 헤더를 제거하여 컴파일 시간을 줄이며, 향후 공개 컴포넌트에 대한 최소한의 변경으로 로깅 백엔드를 교체할 수 있도록 합니다.\n\n### 1.2. 결과물\n- **예상 결과물**: 소스 파일 내에서 `spdlog::logger` 인스턴스를 관리하는 비공개 `Implementation` 클래스.\n- **명세**:\n - **클래스**: `source/logger.cpp` 내에 `core::Logger::Implementation` 정의 및 구현.\n - **생성자**: `Implementation(const std::string& logger_name, Logger::Level level)`는 `spdlog::logger`를 생성하고 등록합니다.\n - **소멸자**: `~Implementation()`는 `spdlog::drop()`을 호출하여 등록된 로거를 정리합니다.\n - **메서드**:\n - `void AddFileSink(const core::filesystem::Path& file_path)`\n - `void Log(Logger::Level level, const std::string& message)`\n - **헬퍼 함수**: 비공개 정적 함수 `spdlog::level::level_enum ConvertToSpdlogLevel(core::Logger::Level level)`.\n - **비공개 멤버**: `std::shared_ptr logger_`.\n- **결과 파일 구조**\n```bash\n# ./\n# ├── ...\n# └── source/\n# └── logger.cpp <-- 수정됨\n```\n\n- **프로세스 흐름 다이어그램**\n 이 다이어그램은 공개 `Logger` 클래스가 어떻게 비공개 `Implementation`으로 호출을 위임하고, 이어서 `Implementation`이 `spdlog` 라이브러리와 상호작용하는지를 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"core::Logger (공개 API)\"\n direction LR\n A[\"Log(level, msg)\"]\n end\n\n subgraph \"core::Logger::Implementation (pImpl)\"\n direction LR\n B[\"logger_implementation_->Log(level, msg)\"]\n C[\"switch (level)\"]\n end\n\n subgraph \"spdlog 라이브러리\"\n direction LR\n D[\"spdlog::logger->info(msg)\"]\n E[\"spdlog::logger->warn(msg)\"]\n F[\"...\"]\n end\n\n A --> B\n B --> C\n C -- \"case kInfo\" --> D\n C -- \"case kWarn\" --> E\n C -- \"...\" --> F\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 3장에 있습니다.\n\n- [ ] `Logger::Implementation` 클래스의 정의.\n- [ ] `spdlog::logger`를 생성하고 등록하는 생성자 로직.\n- [ ] 로거를 제거하는 소멸자 로직.\n- [ ] `spdlog::sinks::basic_file_sink_mt`를 사용한 `AddFileSink` 구현.\n- [ ] `switch` 문을 사용하여 해당 `spdlog` 메서드를 호출하는 `Log` 메서드 구현.\n- [ ] `core::Logger::Level`을 `spdlog::level::level_enum`으로 변환하는 헬퍼 함수.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **주요 관련 컴포넌트**:\n - **`Logger`**: 이 작업에서 구현을 제공하는 공개 컴포넌트입니다. 애플리케이션의 나머지 부분에 안정적인 로깅 API를 제공합니다.\n - **`spdlog` 라이브러리**: 고성능 로깅 엔진을 제공하는 서드파티 종속성입니다. 이 작업은 `spdlog`를 래핑하여 코어 프레임워크의 공개 API에서 세부 사항을 추상화합니다.\n - **`core::filesystem::Path`**: 파일 시스템 경로에 대한 플랫폼 독립적인 표현을 제공하는 기반 유틸리티 클래스입니다. 파일 기반 로그의 위치를 지정하기 위해 `AddFileSink` 메서드에서 사용됩니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `source/logger.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부적인 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `Logger::Implementation` 클래스의 정의.\n\n#### 1. 클래스 구조 및 비공개 멤버 정의\n\n이 액션은 `source/logger.cpp` 내에 `Logger::Implementation` 클래스의 구조를 정의합니다. 이 클래스는 `spdlog` 인스턴스를 관리하는 데 필요한 모든 메서드와 멤버를 포함하며, pImpl 인터페이스를 위한 공개 메서드와 `spdlog::logger` 객체에 대한 공유 포인터를 담을 비공개 멤버 `logger_`를 포함합니다. 이는 비공개 구현의 경계를 정의합니다.\n\n**파일**: `source/logger.cpp`\n\n```cpp\n// ... (includes)\n\nnamespace core {\n\nclass Logger::Implementation {\n public:\n // Public methods will be defined in subsequent steps\n explicit Implementation(const std::string& logger_name, Logger::Level level);\n ~Implementation();\n\n Implementation(const Implementation&) = delete;\n auto operator=(const Implementation&) -> Implementation& = delete;\n Implementation(Implementation&&) = default;\n auto operator=(Implementation&&) -> Implementation& = default;\n\n void AddFileSink(const core::filesystem::Path& file_path);\n void Log(Logger::Level level, const std::string& message);\n\n private:\n static auto ConvertToSpdlogLevel(core::Logger::Level level)\n -> spdlog::level::level_enum;\n\n std::shared_ptr logger_;\n};\n\n// ... (Logger public method implementations)\n\n} // namespace core\n```\n\n---\n\n### 단계 2: `spdlog::logger`를 생성하고 등록하는 생성자 로직.\n\n#### 1. `Implementation` 생성자 구현\n\n생성자는 `spdlog` 로거를 초기화하는 역할을 합니다. 지정된 이름으로 `spdlog::logger` 인스턴스를 생성하고, 향후 접근 가능성을 위해 전역 `spdlog` 레지스트리에 등록하며, 로그 메시지의 기본 서식 패턴을 설정하고, 프레임워크의 `Level` 열거형을 `spdlog`의 해당 열거형으로 변환하여 초기 로깅 레벨을 설정합니다. 이를 통해 `Logger`가 인스턴스화될 때 로거가 완전히 구성되고 사용할 준비가 되도록 보장합니다.\n\n**파일**: `source/logger.cpp`\n\n```cpp\n// ...\n\nclass Logger::Implementation {\n public:\n explicit Implementation(const std::string& logger_name, Logger::Level level) {\n logger_ = std::make_shared(logger_name);\n spdlog::register_logger(logger_);\n logger_->set_pattern(\"[%Y-%m-%d %H:%M:%S.%e] [%n] [%^%l%$] %v\");\n logger_->set_level(ConvertToSpdlogLevel(level));\n }\n\n// ... (rest of the class)\n};\n\n// ...\n```\n\n---\n\n### 단계 3: 로거를 제거하는 소멸자 로직.\n\n#### 1. `Implementation` 소멸자 구현\n\n소멸자는 `spdlog` 리소스의 정리를 처리합니다. 로거의 이름과 함께 `spdlog::drop()`을 호출하여 전역 `spdlog` 레지스트리에서 로거를 제거합니다. 이는 적절한 리소스 관리를 위한 중요한 단계이며, 메모리 누수를 방지하고 `Logger` 객체가 범위를 벗어날 때 로거와 관련된 모든 리소스가 해제되도록 보장합니다.\n\n**파일**: `source/logger.cpp`\n\n```cpp\n// ...\n\nclass Logger::Implementation {\n public:\n // ... (constructor)\n\n ~Implementation() { spdlog::drop(logger_->name()); }\n\n// ... (rest of the class)\n};\n\n// ...\n```\n\n---\n\n### 단계 4: `spdlog::sinks::basic_file_sink_mt`를 사용한 `AddFileSink` 구현.\n\n#### 1. `AddFileSink` 메서드 구현\n\n이 메서드는 로그 메시지를 파일에 쓸 수 있게 하여 로거의 기능을 향상시킵니다. 출력 파일을 지정하기 위해 `core::filesystem::Path` 객체를 사용하여 `spdlog::sinks::basic_file_sink_mt`(스레드 안전 파일 싱크)의 인스턴스를 생성합니다. 새로운 싱크는 로거의 싱크 목록에 추가되어 다중 싱크 로깅(예: 콘솔과 파일 동시 로깅)을 가능하게 합니다.\n\n**파일**: `source/logger.cpp`\n\n```cpp\n// ...\n\nvoid Logger::Implementation::AddFileSink(\n const core::filesystem::Path& file_path) {\n auto file_sink = std::make_shared(\n file_path.ConvertToString(), true);\n logger_->sinks().push_back(file_sink);\n}\n\n// ...\n```\n\n---\n\n### 단계 5: `switch` 문을 사용하여 해당 `spdlog` 메서드를 호출하는 `Log` 메서드 구현.\n\n#### 1. `Log` 메서드 구현\n\n이 메서드는 모든 로깅 호출에 대한 중앙 디스패처 역할을 합니다. 프레임워크의 일반적인 `Logger::Level`과 로그 메시지를 받습니다. `switch` 문은 이 레벨을 `spdlog::logger` 인스턴스의 해당 특정 로깅 메서드(예: `kInfo`는 `logger_->info()`에 매핑)에 매핑하는 데 사용됩니다. 이 변환은 래퍼의 핵심이며, 공개 API를 기본 라이브러리의 기능과 연결합니다.\n\n**파일**: `source/logger.cpp`\n\n```cpp\n// ...\n\nvoid Logger::Implementation::Log(Logger::Level level,\n const std::string& message) {\n switch (level) {\n case Logger::Level::kTrace:\n logger_->trace(message);\n break;\n case Logger::Level::kDebug:\n logger_->debug(message);\n break;\n case Logger::Level::kInfo:\n logger_->info(message);\n break;\n case Logger::Level::kWarn:\n logger_->warn(message);\n break;\n case Logger::Level::kError:\n logger_->error(message);\n break;\n case Logger::Level::kFatal:\n logger_->critical(message);\n break;\n }\n}\n\n// ...\n```\n\n---\n\n### 단계 6: `core::Logger::Level`을 `spdlog::level::level_enum`으로 변환하는 헬퍼 함수.\n\n#### 1. `ConvertToSpdlogLevel` 헬퍼 함수 구현\n\n이 비공개 정적 헬퍼 함수는 프레임워크별 `core::Logger::Level` 열거형을 `spdlog` 라이브러리에서 요구하는 `spdlog::level::level_enum`으로 변환하는 역할을 합니다. 이 추상화는 생성자에서 로거의 필터 레벨을 설정하는 데 필요하며, 매핑 로직을 한곳에 격리하여 유지보수를 용이하게 합니다.\n\n**파일**: `source/logger.cpp`\n\n```cpp\n// ...\n\nclass Logger::Implementation {\n// ... (public members)\n\n private:\n static auto ConvertToSpdlogLevel(core::Logger::Level level)\n -> spdlog::level::level_enum {\n auto return_value = spdlog::level::off;\n switch (level) {\n case core::Logger::Level::kTrace:\n return_value = spdlog::level::trace;\n break;\n case core::Logger::Level::kDebug:\n return_value = spdlog::level::debug;\n break;\n case core::Logger::Level::kInfo:\n return_value = spdlog::level::info;\n break;\n case core::Logger::Level::kWarn:\n return_value = spdlog::level::warn;\n break;\n case core::Logger::Level::kError:\n return_value = spdlog::level::err;\n break;\n case core::Logger::Level::kFatal:\n return_value = spdlog::level::critical;\n break;\n }\n return return_value;\n }\n\n std::shared_ptr logger_;\n};\n\n// ...\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n`Logger::Implementation` 클래스의 올바른 구현을 검증하기 위해, 개발자는 `Logger` 컴포넌트에 대한 관련 단위 테스트를 컴파일하고 실행해야 합니다.\n\n```bash\n# 1. 빌드 디렉토리로 이동\ncd build\n\n# 2. CMake를 사용하여 프로젝트 구성 (아직 하지 않은 경우)\ncmake ..\n\n# 3. 로거 단위 테스트 타겟 빌드\n# 특정 타겟 이름은 CMake 구성에 따라 달라질 수 있습니다.\ncmake --build . --target logger_unit_test\n\n# 4. ctest를 통해 단위 테스트를 실행하여 요약 결과 확인\nctest --output-on-failure -R logger_unit_test\n```\n\n### 4.2. 예상 결과\n\n검증은 `ctest` 명령이 `logger_unit_test` 타겟의 모든 테스트가 통과했다고 보고하면 성공입니다. 출력은 다음과 유사해야 합니다:\n\n```\nTest project /path/to/readable-code-cpp-core-framework/build\n Start 1: logger_unit_test\n1/1 Test #1: logger_unit_test ................... Passed 0.01s\n\n100% tests passed, 0 tests failed out of 1\n\nTotal Test time (real) = 0.02s\n```","spdlog::logger` 인스턴스를 관리하는, 소스 파일 내의 비공개 `Implementation` 클래스",[1968,1970,1972,1974,1976,1978],{"_24":1969,"_83":39,"_84":374,"_85":61},"`Logger::Implementation` 클래스 정의",{"_24":1971,"_83":39,"_84":374,"_85":88},"`spdlog::logger`를 생성하고 등록하는 생성자 로직",{"_24":1973,"_83":39,"_84":374,"_85":91},"로거를 드롭하는 소멸자 로직",{"_24":1975,"_83":39,"_84":374,"_85":94},"`spdlog::sinks::basic_file_sink_mt`를 사용한 `AddFileSink` 구현",{"_24":1977,"_83":39,"_84":374,"_85":97},"해당 `spdlog` 메서드를 호출하기 위해 switch를 사용하는 `Log` 메서드 구현",{"_24":1979,"_83":39,"_84":374,"_85":176},"`core::Logger::Level`을 `spdlog::level::level_enum`으로 변환하는 헬퍼 함수","실제 로깅 기능을 제공하기 위해 `spdlog` 라이브러리를 래핑하는 `Logger::Implementation` 클래스를 구현",{"_22":1982,"_24":1983,"_75":1984,"_77":1985,"_79":1986,"_51":1993,"_42":99},"task-1751726546260","로거 Public 메서드 로직 구현","# 작업: Logger 공개 메서드 로직 구현\n\n> **에픽**: 다중 싱크 로깅 프레임워크\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: pImpl 인스턴스로 호출을 위임하는 `Logger` 공개 메서드를 구현합니다.\n- **근거**: 이 작업은 `Logger` 클래스에 Pimpl(Pointer to Implementation) 이디엄을 적용하여 완성하는 데 핵심적입니다. 공개 메서드가 비공개 `Implementation` 클래스로 호출을 위임하도록 구현함으로써, `Logger`의 공개 API를 기저의 `spdlog` 라이브러리로부터 완전히 분리(디커플링)합니다. 이를 통해 컴파일 의존성을 줄이고, 구현 세부 사항을 숨기며, 프레임워크 내 다른 모든 컴포넌트가 로깅에 사용할 수 있는 안정적이고 제어된 인터페이스를 제공합니다.\n\n### 1.2. 결과물\n- **예상 결과**: 공개 메서드들이 비공개 `spdlog` 래퍼에 연결된, 완전히 구현된 `Logger` 클래스.\n- **명세**: `core::Logger` 클래스의 다음 메서드들이 `logger_implementation_` 멤버에 로직을 위임하도록 구현됩니다.\n - `Logger::Logger(const std::string& logger_name, Level level)`\n - `Logger::~Logger()`\n - `void Logger::Log(Level level, const std::string& message)`\n - `void Logger::Trace(const std::string& message)`\n - `void Logger::Debug(const std::string& message)`\n - `void Logger::Info(const std::string& message)`\n - `void Logger::Warn(const std::string& message)`\n - `void Logger::Error(const std::string& message)`\n - `void Logger::Fatal(const std::string& message)`\n - `void Logger::AddFileSink(const core::filesystem::Path& file_path)`\n- **결과 파일 구조**\n```bash\n# ./\n# └── source/\n# └── logger.cpp <-- 수정됨\n```\n\n- **프로세스 흐름도**\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"애플리케이션 코드\"\n A[\"컴포넌트 (예: 파이프라인)\"]\n end\n\n subgraph \"Logger 공개 API (logger.hpp)\"\n B[\"Logger::Info(\\...\\)\"]\n end\n \n subgraph \"Logger 비공개 구현 (logger.cpp)\"\n C[\"pImpl->Log(kInfo, \\...\\)\"]\n D[\"spdlog::logger->info(\\...\\)\"]\n end\n \n subgraph \"출력\"\n E[\"콘솔 / 파일 싱크\"]\n end\n\n A --> B;\n B --> C;\n C --> D;\n D --> E;\n```\n\n### 1.3. 인수 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완수해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 상세 구현은 3절에 있습니다.\n\n- [ ] `Implementation` 객체를 생성하도록 `Logger` 생성자 구현\n- [ ] 내부 `Log` 메서드를 호출하는 레벨별 메서드(`Trace`, `Info` 등) 구현\n- [ ] 구현 객체에 위임하는 `AddFileSink` 구현\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **주요 관련 컴포넌트**:\n - **`Logger`**: 현재 구현 중인 컴포넌트입니다. 전체 애플리케이션을 위해 다중 레벨, 다중 싱크 로깅 인터페이스를 제공하고, 사용된 특정 로깅 라이브러리를 추상화하는 책임을 가집니다. 이 작업에서는 공개용 메서드들을 구현합니다.\n - **`Logger::Implementation`**: `spdlog` 라이브러리를 캡슐화하는 비공개 내부 클래스입니다. 공개 `Logger` 메서드들은 이 클래스의 인스턴스에 모든 작업을 위임합니다.\n - **`core::filesystem::Path`**: 파일 시스템 경로를 나타내는 유틸리티 클래스입니다. `AddFileSink` 메서드에서 로그 파일의 위치를 플랫폼 독립적인 방식으로 지정하기 위해 매개변수로 사용됩니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `source/logger.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계(Step)`는 **인수 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션(Action)`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `Implementation` 객체를 생성하도록 `Logger` 생성자 구현\n\n#### 1. Logger 생성자와 소멸자 구현\n\n이 액션은 `Logger` 클래스 생성자와 소멸자를 구현합니다. 생성자의 유일한 책임은 비공개 `Implementation` 클래스를 인스턴스화하고 `logger_implementation_` 유니크 포인터에 할당하는 것입니다. 이를 통해 Pimpl 설정이 완료되며, 모든 `spdlog` 관련 로직이 `Implementation` 클래스와 `logger.cpp` 내에 포함되도록 보장합니다. `std::unique_ptr`가 `Implementation` 객체의 정리를 처리하므로 기본 소멸자로 충분합니다.\n\n**파일**: `source/logger.cpp`\n\n```cpp\n...\n std::shared_ptr logger_;\n};\n\nLogger::Logger(const std::string& logger_name, Level level)\n : logger_implementation_(\n std::make_unique(logger_name, level)) {}\n\nLogger::~Logger() = default;\n\nvoid Logger::Log(Level level, const std::string& message) {\n...\n```\n\n---\n\n### 단계 2: 내부 `Log` 메서드를 호출하는 레벨별 메서드(`Trace`, `Info` 등) 구현\n\n#### 1. 중앙 `Log` 메서드 구현\n\n주요 `Log` 메서드를 구현합니다. 이 메서드는 공개 API와 비공개 구현 사이의 다리 역할을 합니다. 심각도 레벨과 메시지를 포함한 로깅 요청을 `logger_implementation_` 객체의 `Log` 메서드로 직접 전달하는 기능을 합니다. 이를 통해 위임 로직을 중앙 집중화합니다.\n\n**파일**: `source/logger.cpp`\n\n```cpp\n...\nLogger::~Logger() = default;\n\nvoid Logger::Log(Level level, const std::string& message) {\n logger_implementation_->Log(level, message);\n}\n\nvoid Logger::Trace(const std::string& message) { Log(Level::kTrace, message); }\n...\n```\n\n#### 2. 편의 로깅 메서드 구현\n\n레벨별 편의 메서드인 `Trace`, `Debug`, `Info`, `Warn`, `Error`, `Fatal`을 구현합니다. 이들 각각은 가장 일반적인 로깅 작업을 위한 간소화된 API를 제공합니다. 이들은 중앙 `Log` 메서드를 한 줄로 호출하며, 각각 하드코딩된 `Level` 열거형을 전달하는 방식으로 간단히 구현됩니다. 이는 코드 재사용성을 높이고 `Logger` 사용자에게 깨끗하고 표현력 있는 API를 제공합니다.\n\n**파일**: `source/logger.cpp`\n\n```cpp\n...\nvoid Logger::Log(Level level, const std::string& message) {\n logger_implementation_->Log(level, message);\n}\n\nvoid Logger::Trace(const std::string& message) { Log(Level::kTrace, message); }\n\nvoid Logger::Debug(const std::string& message) { Log(Level::kDebug, message); }\n\nvoid Logger::Info(const std::string& message) { Log(Level::kInfo, message); }\n\nvoid Logger::Warn(const std::string& message) { Log(Level::kWarn, message); }\n\nvoid Logger::Error(const std::string& message) { Log(Level::kError, message); }\n\nvoid Logger::Fatal(const std::string& message) { Log(Level::kFatal, message); }\n\nvoid Logger::AddFileSink(const core::filesystem::Path& file_path) {\n...\n```\n\n---\n\n### 단계 3: 구현 객체에 위임하는 `AddFileSink` 구현\n\n#### 1. `AddFileSink` 메서드 구현\n\n공개 `AddFileSink` 메서드를 구현합니다. 이 메서드를 통해 애플리케이션 코드는 런타임에 파일을 로깅 대상으로 추가할 수 있습니다. 구현은 `core::filesystem::Path` 객체를 전달하면서 `logger_implementation_` 객체의 `AddFileSink` 메서드로 호출을 직접 위임해야 합니다. 공개 `Logger` 클래스는 파일 싱크가 어떻게 생성되고 관리되는지 알지 못하므로, 이를 통해 Pimpl 추상화가 유지됩니다.\n\n**파일**: `source/logger.cpp`\n\n```cpp\n...\nvoid Logger::Fatal(const std::string& message) { Log(Level::kFatal, message); }\n\nvoid Logger::AddFileSink(const core::filesystem::Path& file_path) {\n logger_implementation_->AddFileSink(file_path);\n}\n\n} // namespace core\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- `Logger` 구현의 정확성은 해당 단위 테스트를 컴파일하고 실행하여 검증합니다. 로거 컴포넌트의 테스트 스위트는 생성자 동작, 모든 레벨에서의 정확한 메시지 로깅, 그리고 파일 싱크의 동적 추가를 검증합니다.\n\n```bash\n# 1. 빌드 디렉터리로 이동\ncd build/\n\n# 2. 프로젝트와 테스트 빌드\ncmake --build .\n\n# 3. 로거 컴포넌트의 단위 테스트 실행\n# 정확한 이름은 CTest 설정에 따라 다를 수 있습니다.\nctest --output-on-failure -R logger_unit_test\n```\n\n### 4.2. 예상 결과\n\n- 테스트 실행기는 `logger_unit_test` 스위트의 모든 테스트가 통과했다고 보고해야 합니다. 출력은 다음 예시와 유사하게 실패가 없음을 나타내야 합니다.\n\n```\nRunning tests...\nTest project /path/to/readable-code-cpp-core-framework/build\n Start 1: logger_unit_test\n1/1 Test #1: logger_unit_test ................... Passed 0.01s\n\n100% tests passed, 0 tests failed out of 1\n\nTotal Test time (real) = 0.02s\n```","public 메서드가 비공개 `spdlog` 래퍼에 연결된 완전히 구현된 `Logger` 클래스",[1987,1989,1991],{"_24":1988,"_83":39,"_84":392,"_85":61},"`Implementation` 객체를 생성하는 `Logger` 생성자 구현",{"_24":1990,"_83":39,"_84":392,"_85":88},"내부 `Log` 메서드를 호출하는 레벨별 메서드(`Trace`, `Info` 등) 구현",{"_24":1992,"_83":39,"_84":392,"_85":91},"구현 객체에 위임하는 `AddFileSink` 구현","pImpl 인스턴스로 호출을 위임하는 public `Logger` 메서드를 구현",{"_22":1995,"_24":1996,"_75":1997,"_77":1998,"_79":1999,"_51":2008,"_42":99},"task-1751726579183","타임스탬프 클래스 인터페이스 정의","# 작업: Timestamp 클래스 인터페이스 정의\n\n> **에픽**: 고정밀 타임스탬핑\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: 고해상도 시점을 캡처하기 위한 `core::time::Stamp` 클래스 인터페이스 정의.\n- **근거**: 이 클래스는 프레임워크에 연산 소요 시간 측정이라는 핵심 기능을 제공합니다. `Stamp`는 고해상도 시계를 캡슐화하여, `Scheduler` 및 `Pipeline`과 같은 상위 컴포넌트에서 요구하는 성능 모니터링, 프로파일링, 시간 기반 계산을 가능하게 합니다. 이는 성능 메트릭이나 정밀한 타이밍 제어가 필요한 모든 작업의 선행 조건이 됩니다.\n\n### 1.2. 결과물\n- **예상 결과물**: 기본 생성자와, `Duration`을 반환하는 뺄셈 연산자를 포함하는 `Stamp` 클래스 헤더 파일.\n- **사양**:\n - 클래스 이름: `core::time::Stamp`\n - Public 멤버:\n - 기본 생성자: `Stamp()`\n - 기본값(Defaulted)으로 지정된 복사/이동 생성자 및 할당 연산자.\n - 기본값(Defaulted)으로 지정된 소멸자.\n - 뺄셈 연산자: `[[nodiscard]] auto operator-(const Stamp& other) const -> Duration;`\n - Private 멤버:\n - 시점을 저장하기 위한 `std::chrono::time_point` 멤버.\n- **결과 파일 구조**\n```bash\n# ./\n# └── include/\n# └── core/\n# └── time/\n# ├── duration.hpp <-- Existing\n# └── stamp.hpp <-- Modified\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 `Stamp` 클래스의 주요 사용 사례를 보여줍니다: 두 이벤트 사이의 시간을 측정하여 `Duration`을 계산합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"이벤트 타이밍\"\n A[\"이벤트 A 발생\"] --> C1[\"Stamp stamp_a;\"];\n B[\"이벤트 B 발생\"] --> C2[\"Stamp stamp_b;\"];\n end\n\n subgraph \"소요 시간 계산\"\n C1 --> OP[\"duration = stamp_b - stamp_a\"];\n C2 --> OP;\n end\n \n OP --> D[\"Duration 객체
경과 시간을 나타냄\"];\n```\n\n### 1.3. 수용 기준\n\n개발자는 이 작업을 완료된 것으로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 상세 구현은 섹션 3에 있습니다.\n\n- [ ] `Stamp` 클래스 정의.\n- [ ] 기본 생성자.\n- [ ] 기본값으로 지정된 Rule-of-five 멤버.\n- [ ] 다른 `Stamp`를 받아 `Duration`을 반환하는 `operator-` 선언.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - `core::time::Stamp` (이 작업): 단일 고해상도 시점을 나타내는 데이터 구조. 시간 측정의 기초 빌딩 블록 역할을 합니다.\n - `core::time::Duration`: `Stamp`가 직접 상호작용하는 컴포넌트. 두 `Stamp` 객체의 뺄셈은 경과 시간을 나타내는 `Duration` 객체를 생성합니다. 이 의존성은 설계의 핵심입니다.\n - `Scheduler` / `Pipeline`: `Stamp` 객체를 사용하여 작업 실행 시간을 측정하고 타이밍 제약을 강제하는 상위 레벨 컴포넌트. 이는 고성능의 관찰 가능한 시스템을 제공한다는 핵심 프로젝트 목표를 달성합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `include/core/time/stamp.hpp`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `Step`은 **수용 기준**의 각 항목에 해당합니다. 각 `Step`은 일련의 세분화된 `Action`으로 나뉩니다. 각 `Action`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### Step 1: `Stamp` 클래스 정의.\n\n#### 1. 의존성 포함 및 클래스 구조 정의\n\n이 작업은 헤더 파일의 기본 구조를 설정합니다. 기본 시간-점(time-point) 구현을 위한 ``와 뺄셈 연산자의 반환 타입을 위한 `\"core/time/duration.hpp\"` 헤더를 포함합니다. `Stamp` 클래스는 `core::time` 네임스페이스 내에 정의되며, 시간 데이터를 캡슐화하기 위해 `std::chrono::time_point` 타입의 private 멤버 `time_`이 추가됩니다.\n\n**파일**: `include/core/time/stamp.hpp`\n\n```cpp\n#ifndef CORE__TIME__STAMP_HPP\n#define CORE__TIME__STAMP_HPP\n\n#include \n\n#include \"core/time/duration.hpp\"\n\nnamespace core::time {\n\nclass Stamp {\n public:\n // ... Public 인터페이스가 여기에 정의될 것입니다.\n\n private:\n std::chrono::time_point\n time_; ///< 이 스탬프에 의해 캡처된 고해상도 시점.\n};\n\n} // namespace core::time\n\n#endif // CORE__TIME__STAMP_HPP\n```\n\n---\n\n### Step 2: 기본 생성자.\n\n#### 1. 기본 생성자 선언\n\n기본 생성자는 클래스의 public 섹션에 선언됩니다. 그 목적은 객체 생성 시 `time_` 멤버를 현재 시간으로 초기화하는 것입니다. 구현은 별도의 작업에서 제공될 것이지만, 클래스를 생성 가능하게 만들기 위해 여기에서 public 인터페이스를 정의해야 합니다.\n\n**파일**: `include/core/time/stamp.hpp`\n\n```cpp\nclass Stamp {\n public:\n /**\n * @brief 기본 생성자.\n * @details 현재 시간을 나타내는 Stamp 객체를 생성합니다.\n */\n Stamp();\n\n // ... 나머지 public 인터페이스\n...\n```\n\n---\n\n### Step 3: 기본값으로 지정된 Rule-of-five 멤버.\n\n#### 1. 기본값으로 지정된 특수 멤버 함수 선언\n\n최신 C++ 모범 사례(Rule of Zero/Five)를 따르기 위해 특수 멤버 함수(복사/이동 생성자, 복사/이동 할당 연산자, 소멸자)를 명시적으로 기본값으로 지정합니다. `Stamp`는 자체 리소스를 올바르게 처리하는 표준 라이브러리 타입(`time_point`)을 감싸는 단순한 래퍼(wrapper)이므로, 컴파일러가 생성하는 기본 동작으로 충분하며 정확합니다. 이는 클래스의 의도를 명확하게 하고 의도하지 않은 부작용을 방지합니다.\n\n**파일**: `include/core/time/stamp.hpp`\n\n```cpp\nclass Stamp {\n public:\n Stamp();\n\n /**\n * @brief 기본 복사 생성자.\n */\n Stamp(const Stamp&) = default;\n\n /**\n * @brief 기본 복사 할당 연산자.\n * @return 이 Stamp 객체에 대한 참조.\n */\n auto operator=(const Stamp&) -> Stamp& = default;\n\n /**\n * @brief 기본 이동 생성자.\n */\n Stamp(Stamp&&) = default;\n\n /**\n * @brief 기본 이동 할당 연산자.\n * @return 이 Stamp 객체에 대한 참조.\n */\n auto operator=(Stamp&&) -> Stamp& = default;\n\n /**\n * @brief 기본 소멸자.\n */\n ~Stamp() = default;\n\n // ... 나머지 public 인터페이스\n...\n```\n\n---\n\n### Step 4: 다른 `Stamp`를 받아 `Duration`을 반환하는 `operator-` 선언.\n\n#### 1. 뺄셈 연산자 선언\n\n뺄셈 연산자는 `Stamp` 객체와 상호작용하는 주요 메서드입니다. 두 `Stamp` 인스턴스 간의 경과 시간을 계산하는 의미를 정의합니다. 객체를 수정하지 않으므로 `const` 멤버 함수로 선언됩니다. 뺄 다른 `const Stamp&`를 인자로 받아 `core::time::Duration` 객체를 반환하여, 시간 차이에 대한 타입-안전(type-safe) 표현을 제공합니다. `[[nodiscard]]` 속성은 뺄셈 결과가 사용되지 않을 경우 컴파일러 경고를 발생시켜 잠재적인 논리 오류를 방지하는 데 사용됩니다.\n\n**파일**: `include/core/time/stamp.hpp`\n\n```cpp\nclass Stamp {\n public:\n...\n ~Stamp() = default;\n\n /**\n * @brief 두 타임스탬프 간의 시간 차이를 계산합니다.\n * @param other [in] 뺄 타임스탬프 객체.\n * @return 시간 차이를 나타내는 Duration 객체.\n */\n [[nodiscard]] auto operator-(const Stamp& other) const -> Duration;\n\n private:\n...\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n헤더 파일이 구문적으로 올바르고 모든 의존성이 제대로 선언되었는지 확인하려면, 해당 헤더를 포함하는 간단한 C++ 파일을 컴파일해 봅니다.\n\n1. `verify_stamp.cpp`라는 임시 검증 파일을 생성합니다:\n\n ```cpp\n // verify_stamp.cpp\n #include \"core/time/stamp.hpp\"\n\n int main() {\n // 헤더 유효성을 확인하기 위해 클래스를 인스턴스화하기만 하면 됩니다.\n // 아직 구현되지 않은 메서드는 호출할 수 없습니다.\n core::time::Stamp s1;\n core::time::Stamp s2 = s1; // 복사 생성자 테스트\n s1 = s2; // 복사 할당 테스트\n return 0;\n }\n ```\n\n2. `core/time/duration.hpp` 파일이 존재하고 유효하다고 가정합니다. C++ 컴파일러를 사용하여 검증 파일을 컴파일합니다. 빌드 환경에 맞게 포함 경로(`-I`)를 조정하세요.\n\n ```bash\n # 프로젝트의 루트 디렉터리에 있는지 확인하세요\n g++ -std=c++17 -I./include -c tests/verification/verify_stamp.cpp -o /tmp/verify_stamp.o\n ```\n\n### 4.2. 예상 결과\n\n- 컴파일 명령은 종료 코드 `0`으로 성공적으로 완료되어야 합니다.\n- 컴파일러 오류나 경고가 발생해서는 안 됩니다.\n- `/tmp/` 디렉터리에 새로운 오브젝트 파일(`verify_stamp.o`)이 생성되어, 헤더 `stamp.hpp`가 올바른 형식임을 나타냅니다.\n\n```\n# 예상되는 커맨드 라인 출력 (즉, 아무것도 없음)\n$ \n\n# 종료 코드 확인\n$ echo $?\n0\n```","기본 생성자와 `Duration`을 반환하는 빼기 연산자를 가진 `Stamp` 클래스의 헤더 파일",[2000,2002,2004,2006],{"_24":2001,"_83":39,"_84":410,"_85":61},"`Stamp` 클래스 정의",{"_24":2003,"_83":39,"_84":410,"_85":88},"기본 생성자",{"_24":2005,"_83":39,"_84":410,"_85":91},"기본값으로 설정된 rule-of-five 멤버",{"_24":2007,"_83":39,"_84":410,"_85":94},"다른 `Stamp`를 받아 `Duration`을 반환하는 `operator-` 선언","고해상도 타임 포인트를 캡처하기 위한 `core::time::Stamp` 클래스 인터페이스를 정의",{"_22":2010,"_24":2011,"_75":2012,"_77":2013,"_79":2014,"_51":2021,"_42":99},"task-1751726620801","타임스탬프 클래스 로직 구현","# 작업: Timestamp 클래스 로직 구현\n\n> **에픽**: 고정밀 타임스탬핑\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: 시간을 캡처하고 기간을 계산하기 위한 `core::time::Stamp` 메서드 구현.\n- **이유**: 이 작업은 프레임워크 내에서 성능 측정을 가능하게 하는 데 필수적입니다. `Stamp` 클래스를 구현함으로써 애플리케이션 실행 중 특정 시점의 고해상도 타임스탬프를 캡처하는 메커니즘을 제공합니다. 이 스탬프들은 `Duration`을 계산하는 데 사용될 수 있으며, 개발자는 이를 통해 작업에 소요된 시간을 정밀하게 측정할 수 있습니다. 이는 고성능 시스템의 핵심 목표입니다.\n\n### 1.2. 결과물\n- **예상 결과물**: `Stamp` 클래스 구현이 포함된 소스 파일.\n- **사양**:\n - **구현될 클래스**: `core::time::Stamp`\n - **함수 시그니처 (생성자)**: `Stamp()`\n - **함수 시그니처 (연산자)**: `auto operator-(const Stamp& other) const -> core::time::Duration`\n- **결과 파일 구조**\n```bash\n./\n└── source/\n └── time/\n └── stamp.cpp <-- 수정됨\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 `Stamp`와 `Duration` 클래스를 사용하여 시간을 측정하는 의도된 사용 패턴을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"측정 프로세스\"\n direction TB\n A[\"1\\. 시작 스탬프 생성
`auto start = Stamp();`\"]\n B[\"2\\. 작업 실행\"]\n C[\"3\\. 종료 스탬프 생성
`auto end = Stamp();`\"]\n D[\"4\\. 기간 계산
`auto elapsed = end - start;`\"]\n end\n \n A --> B --> C --> D\n D --> E[\"결과: Duration 객체\"]\n```\n\n### 1.3\\. 완료 조건\n\n개발자는 이 작업을 완료 처리하기 위해 다음 항목들을 모두 완료해야 합니다. 이는 상위 수준의 체크리스트입니다. 각 항목에 대한 상세 구현은 3장에 있습니다.\n\n- [ ] `std::chrono::high_resolution_clock::now()`를 캡처하는 생성자 구현.\n- [ ] 시간 차이를 계산하는 `operator-` 구현.\n- [ ] 계산된 차이를 바탕으로 `Duration` 객체 생성.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련된 주요 컴포넌트**:\n - **`core::time::Stamp`**: 현재 구현 대상인 클래스입니다. 단일의 고정밀 시점을 캡슐화하는 역할을 합니다. 이 작업에서 핵심 로직을 구현합니다.\n - **`core::time::Duration`**: `Stamp`의 의존성입니다. 시간 간격을 나타내는 역할을 합니다. `Stamp`의 `operator-`는 반드시 `Duration`의 인스턴스를 반환하여, 내부 `std::chrono` 구현 세부 사항을 추상화해야 합니다.\n - **`std::chrono::high_resolution_clock`**: 타임스탬프를 얻기 위해 사용되는 C++ 표준 라이브러리 컴포넌트입니다. `Stamp` 클래스는 이 시계가 생성하는 시점에 대한 프레임워크 전용 래퍼 역할을 합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `source/time/stamp.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `Step`은 **완료 조건**의 항목에 해당합니다. 각 `Step`은 세분화된 `Action`으로 나뉩니다. 각 `Action`에 대해 제목, 명확한 서술적 설명('무엇을', '왜' 하는지 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `std::chrono::high_resolution_clock::now()`를 캡처하는 생성자 구현.\n\n#### 1. 기본 생성자 구현\n\n이 액션은 `core::time::Stamp` 클래스의 기본 생성자를 구현합니다. 생성자의 유일한 역할은 현재 시점을 가능한 가장 높은 정밀도로 캡처하여 private 멤버 변수인 `time_`에 저장하는 것입니다. 이는 `std::chrono::high_resolution_clock::now()`를 호출하여 수행됩니다. 이 초기화는 특정 시점을 기록하는 클래스의 목적에 있어 가장 기본이 됩니다.\n\n**파일**: `source/time/stamp.cpp`\n\n```cpp\n/**\n * @file stamp.cpp\n * @author movingChurch (yes@holyground.world)\n * @brief 고정밀 타임스탬프를 위한 Stamp 클래스를 구현합니다.\n * @version 1.2.1\n * @date 2025-06-30\n * @copyright movingChurch (c) 2025, All Rights Reserved.\n */\n#include \"core/time/stamp.hpp\"\n\n#include \n\n#include \"core/time/duration.hpp\"\n\ncore::time::Stamp::Stamp() : time_(std::chrono::high_resolution_clock::now()) {}\n\n// ...\n```\n\n---\n\n### 단계 2: 시간 차이를 계산하는 `operator-` 구현.\n\n#### 1. 뺄셈 연산자 구현\n\n이 액션은 `Stamp` 클래스의 뺄셈 연산자(`operator-`)를 구현합니다. 이 연산자를 사용하면 두 `Stamp` 인스턴스 간의 경과 시간(예: `end_time - start_time`)을 직관적으로 계산할 수 있습니다. 구현은 현재 인스턴스(`this`)의 `time_` 멤버에서 `other` 스탬프의 `time_` 멤버를 뺍니다. 이 연산은 `std::chrono::duration` 결과를 생성합니다. 이 액션은 연산자 시그니처와 핵심 로직만을 정의합니다.\n\n**파일**: `source/time/stamp.cpp`\n\n```cpp\n// ...\n\nauto core::time::Stamp::operator-(const Stamp& other) const\n -> core::time::Duration {\n return core::time::Duration(time_ - other.time_);\n}\n```\n\n---\n\n### 단계 3: 계산된 차이를 바탕으로 `Duration` 객체 생성.\n\n#### 1. `core::time::Duration` 객체 반환\n\n이 액션은 `operator-`의 구현을 완성합니다. 시점들의 차이로 계산된 원시 `std::chrono::duration`은 즉시 `core::time::Duration` 객체를 생성하고 반환하는 데 사용됩니다. 이것은 추상화를 위한 핵심 단계입니다. 이를 통해 `Stamp` 클래스 사용자가 `std::chrono` 타입이 아닌 프레임워크의 `Duration` 타입과 상호작용하도록 보장합니다. 이는 일관된 API를 유지하고 구현 세부 사항을 숨깁니다. 전체 작업은 연산자의 return 문에서 완료됩니다.\n\n**파일**: `source/time/stamp.cpp`\n\n```cpp\n// ...\n\nauto core::time::Stamp::operator-(const Stamp& other) const\n -> core::time::Duration {\n return core::time::Duration(time_ - other.time_);\n}\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n- `Stamp` 클래스의 기능을 검증하기 위해 유닛 테스트를 생성해야 합니다. 새 테스트 파일 `tests/unit/time_stamp_test.cpp`를 만듭니다. 테스트는 다음을 수행합니다:\n 1. `start` 타임스탬프를 생성합니다.\n 2. 짧은 지연을 추가합니다.\n 3. `end` 타임스탬프를 생성합니다.\n 4. `end`에서 `start`를 빼서 `Duration`을 계산합니다.\n 5. 결과로 나온 duration이 0 나노초보다 큰지 검증(assert)합니다.\n- 프로젝트의 유닛 테스트를 컴파일하고 실행합니다.\n\n```bash\n# 1. 빌드 디렉터리로 이동\ncd build/\n\n# 2. 프로젝트와 테스트 컴파일\ncmake ..\nmake\n\n# 3. 특정 테스트 실행 파일 또는 전체 테스트 스위트 실행\n# (정확한 명령어는 테스트 프레임워크 설정에 따라 다를 수 있습니다)\n./tests/unit/core_unit_tests\n```\n\n### 4.2. 예상 결과\n\n- 컴파일은 오류 없이 성공해야 합니다. 테스트 러너는 새로 추가된 `TimeStampTest`를 포함한 모든 테스트가 통과했다고 보고해야 합니다.\n\n```\n[==========] Running all tests.\n[----------] Global test environment set-up.\n[----------] 1 test from TimeStampTest\n[ RUN ] TimeStampTest.SubtractionCalculatesPositiveDuration\n[ OK ] TimeStampTest.SubtractionCalculatesPositiveDuration (1 ms)\n[----------] 1 test from TimeStampTest (1 ms total)\n\n[----------] Global test environment tear-down\n[==========] All tests passed.\n```","`Stamp` 클래스 구현이 포함된 소스 파일",[2015,2017,2019],{"_24":2016,"_83":39,"_84":428,"_85":61},"`std::chrono::high_resolution_clock::now()`를 캡처하는 생성자 구현",{"_24":2018,"_83":39,"_84":428,"_85":88},"시간 차이를 계산하는 `operator-` 구현",{"_24":2020,"_83":39,"_84":428,"_85":91},"계산된 차이로부터 `Duration` 객체 생성","시간을 캡처하고 기간을 계산하는 `core::time::Stamp` 메서드를 구현",{"_22":2023,"_24":2024,"_75":2025,"_77":2026,"_79":2027,"_51":2038,"_42":99},"task-1751726666519","파이프라인 노드 클래스 인터페이스 정의","# 작업: 파이프라인 노드 클래스 인터페이스 정의\n\n> **에픽**: 타입이 제거된(Type-Erased) 파이프라인 노드\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: `core::concurrency::pipeline::Node` 클래스 인터페이스를 정의하고, 프로듀서 및 트랜스포머 노드를 위한 팩토리를 제공합니다.\n- **근거**: 비동기 데이터 처리 파이프라인을 위한 근본적이고, 타입이 제거되었으며, 타입-세이프한 빌딩 블록을 구축하기 위함입니다. 이 `Node` 클래스는 단일 작업 단위를 캡슐화하여, `Pipeline` 오케스트레이터가 이종(heterogeneous) 처리 단계(예: `Image`를 생성하는 노드가 `Image`를 소비하는 노드에 연결)를 일반적인 방식으로 관리하고 연결할 수 있게 합니다. 이 설계는 유연하고 모듈화된 데이터 처리 시스템을 만드는 데 매우 중요합니다.\n\n### 1.2. 결과물\n- **예상 결과물**: `Node` 클래스 정의, 정적 팩토리 메서드, `Execute` 메서드, 타입 정보 getter를 포함하는 헤더 파일.\n- **명세**:\n - `class core::concurrency::pipeline::Node`가 정의됩니다.\n - `static auto Producer(...) -> Node` 팩토리 템플릿이 구현됩니다.\n - `static auto Transformer(...) -> Node` 팩토리 템플릿이 구현됩니다.\n - `[[nodiscard]] auto Execute(...) const -> NodeResult` public 메서드가 선언됩니다.\n - `[[nodiscard]] auto GetId() const -> NodeId` public 메서드가 선언됩니다.\n - `[[nodiscard]] auto GetInputType() const -> const std::type_index &` public 메서드가 선언됩니다.\n - `[[nodiscard]] auto GetOutputType() const -> const std::type_index &` public 메서드가 선언됩니다.\n- **결과 파일 구조**\n```bash\n# ./\n# └── include/\n# └── core/\n# └── concurrency/\n# └── pipeline/\n# └── node.hpp <-- 수정됨\n```\n\n- **프로세스 흐름도**\n 아래 다이어그램은 외부 컴포넌트(`Pipeline` 오케스트레이터 등)가 `Node` 클래스 인터페이스와 상호 작용하는 방식을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"파이프라인 오케스트레이터\"\n direction LR\n A[\"프로듀서 노드 생성
(예: 센서에서 읽기)\"] --> B{Node::Producer};\n C[\"트랜스포머 노드 생성
(예: 데이터 처리)\"] --> D{Node::Transformer};\n end\n\n subgraph \"노드 실행\"\n direction TB\n E[\"파이프라인이
producer.Execute() 호출\"] --> F[\"사용자의 프로듀서 작업 호출됨\"];\n F --> G[\"SensorData와 함께 NodeResult 반환\"];\n H[\"파이프라인이
transformer.Execute(SensorData) 호출\"] --> I[\"사용자의 트랜스포머 작업 호출됨\"];\n I --> J[\"ProcessedData와 함께 NodeResult 반환\"];\n end\n\n B --> E\n D --> H\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 개략적인 체크리스트이며, 각 항목에 대한 상세 구현은 3절에 있습니다.\n\n- [ ] `Node` 클래스 정의.\n- [ ] 정적 `Producer` 팩토리 메서드 템플릿.\n- [ ] 정적 `Transformer` 팩토리 메서드 템플릿.\n- [ ] public `Execute` 메서드 선언.\n- [ ] `Id`, `InputType`, `OutputType`에 대한 getter 선언.\n\n## 2. 기술적 컨텍스트\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - **`Pipeline`**: 이 컴포넌트는 `Node` 클래스의 주된 소비자(consumer)입니다. `Producer` 및 `Transformer` 정적 팩토리 메서드를 사용하여 노드 시퀀스를 구성합니다. 또한 `GetInputType` 및 `GetOutputType` getter를 사용하여 인접한 노드들이 타입 호환이 되는지 검증합니다.\n - **`pipeline::NodeResult`**: 이 데이터 구조는 `Node::Execute` 메서드의 반환 타입입니다. `Node`의 내부 작업은 `NodeResult`를 생성하고 반환할 책임이 있으며, 이 구조체는 출력 데이터(`std::any`)와 파이프라인의 계속 또는 종료를 알리는 `ControlFlow` 열거형을 포함합니다.\n - **`ThreadPool`**: 직접적인 의존성은 아니지만, `Node` 객체는 `ThreadPool`에서 비동기적으로 실행되도록 설계되었습니다. `Pipeline` 오케스트레이터는 `Node::Execute` 호출을 `ThreadPool`에 enqeueue되는 작업으로 래핑(wrap)합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `include/core/concurrency/pipeline/node.hpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계(Step)`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션(Action)`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `Node` 클래스 정의.\n\n#### 1. 핵심 클래스 구조 확정\n\n이 액션은 `node.hpp`의 `Node` 클래스 정의가 public 인터페이스를 지원하는 데 필요한 private 멤버들을 포함하도록 보장합니다. 이 멤버들은 노드의 고유 ID, 타입이 제거된 호출 가능한 작업(job), 그리고 `Pipeline` 오케스트레이터에 의한 런타임 검증에 필요한 타입 정보를 저장합니다. 클래스는 파이프라인 내에서 명확한 소유권 의미를 보장하기 위해 이동 전용(move-only)이어야 합니다.\n\n**파일**: `include/core/concurrency/pipeline/node.hpp`\n\n```cpp\n// ... (includes)\n\nnamespace core::concurrency::pipeline {\n\n// ... (Node에 대한 doxygen 주석)\nclass Node {\n public:\n using NodeId = std::uint32_t;\n\n // ... (생성자, 소멸자, 및 기타 public 메서드)\n\n private:\n NodeId node_id_;\n using Job = std::function;\n Job job_;\n std::type_index input_type_;\n std::type_index output_type_;\n};\n\n} // namespace core::concurrency::pipeline\n\n// ... (footer)\n```\n\n---\n\n### 단계 2: 정적 `Producer` 팩토리 메서드 템플릿.\n\n#### 1. `Producer` 팩토리 오버로드 구현\n\n이 액션은 두 개의 정적 `Producer` 팩토리 메서드를 추가합니다. 이 메서드들은 입력 없이 데이터를 생성하는 노드를 편리하고 타입-세이프한 방식으로 생성하는 방법을 제공합니다. 사용자 편의를 위해 두 가지 오버로드가 제공됩니다: 하나는 원시 `OutputType`을 반환하는 함수용이고, 다른 하나는 완전한 `NodeResult` 구조체를 반환하여 사용자에게 파이프라인 흐름에 대한 더 많은 제어권을 주는 함수용입니다. 입력 타입은 명시적으로 `typeid(void)`로 설정됩니다.\n\n**파일**: `include/core/concurrency/pipeline/node.hpp`\n\n```cpp\n// ... (Node 클래스의 public 섹션 내부)\n\n /**\n * @brief 입력 없이 데이터를 생성하는 프로듀서 노드를 생성합니다.\n * @tparam OutputType 이 프로듀서가 생성할 데이터의 타입.\n * @param node_id 새로운 노드의 고유 식별자.\n * @param producer 인자가 없고 NodeResult 값을 반환하는 함수.\n * @return 프로듀서로 구성된 새로운 Node.\n */\n template \n static auto Producer(NodeId node_id,\n const std::function &producer)\n -> Node {\n return Node(\n node_id,\n [producer](const std::any &) -> NodeResult { return producer(); },\n typeid(void), typeid(OutputType));\n }\n\n /**\n * @brief 입력 없이 데이터를 생성하는 프로듀서 노드를 생성합니다.\n * @tparam OutputType 이 프로듀서가 생성할 데이터의 타입.\n * @param node_id 새로운 노드의 고유 식별자.\n * @param producer 인자가 없고 OutputType 값을 반환하는 함수.\n * @return 프로듀서로 구성된 새로운 Node.\n */\n template \n static auto Producer(NodeId node_id, std::function producer)\n -> Node {\n return Node(\n node_id,\n [producer](const std::any &) -> NodeResult {\n if constexpr (std::is_void_v) {\n producer();\n return NodeResult{.data = std::any{},\\\n .control = ControlFlow::kContinue};\n } else {\n return NodeResult{producer(), ControlFlow::kContinue};\n }\n },\n typeid(void), typeid(OutputType));\n }\n```\n\n---\n\n### 단계 3: 정적 `Transformer` 팩토리 메서드 템플릿.\n\n#### 1. `Transformer` 팩토리 오버로드 구현\n\n이 액션은 입력을 소비하고 출력을 생성하는 노드를 만들기 위한 두 개의 정적 `Transformer` 팩토리 메서드를 추가합니다. 이 메서드들은 사용자가 제공한 함수를 런타임에 타입-세이프한 `std::any_cast`를 수행하는 람다로 래핑합니다. `Producer` 팩토리와 마찬가지로 두 가지 오버로드가 제공됩니다: 하나는 원시 `OutputType`을 반환하는 함수용이고, 다른 하나는 `NodeResult`를 반환하여 사용자에게 유연성을 제공하는 함수용입니다.\n\n**파일**: `include/core/concurrency/pipeline/node.hpp`\n\n```cpp\n// ... (Node 클래스의 public 섹션 내부, Producer 메서드 다음)\n\n /**\n * @brief 입력을 받아 출력을 생성하는 트랜스포머 노드를 생성합니다.\n * @tparam InputType 이 트랜스포머가 입력으로 기대하는 데이터의 타입.\n * @tparam OutputType 이 트랜스포머가 출력으로 생성할 데이터의 타입.\n * @param node_id 새로운 노드의 고유 식별자.\n * @param transformer InputType을 받아 NodeResult를 반환하는 함수.\n * @return 트랜스포머로 구성된 새로운 Node.\n */\n template \n static auto Transformer(NodeId node_id,\n std::function transformer)\n -> Node {\n return Node(\n node_id,\n [transformer](const std::any &input) -> NodeResult {\n return transformer(std::any_cast(input));\n },\n typeid(InputType), typeid(OutputType));\n }\n\n /**\n * @brief 입력을 받아 출력을 생성하는 트랜스포머 노드를 생성합니다.\n * @tparam InputType 이 트랜스포머가 입력으로 기대하는 데이터의 타입.\n * @tparam OutputType 이 트랜스포머가 출력으로 생성할 데이터의 타입.\n * @param node_id 새로운 노드의 고유 식별자.\n * @param transformer InputType을 받아 OutputType을 반환하는 함수.\n * @return 트랜스포머로 구성된 새로운 Node.\n */\n template \n static auto Transformer(NodeId node_id,\n std::function transformer)\n -> Node {\n return Node(\n node_id,\n [transformer](const std::any &input) -> NodeResult {\n if constexpr (std::is_void_v) {\n transformer(std::any_cast(input));\n return NodeResult{.data = std::any{},\\\n .control = ControlFlow::kContinue};\n } else {\n return NodeResult{transformer(std::any_cast(input)),\n ControlFlow::kContinue};\n }\n },\n typeid(InputType), typeid(OutputType));\n }\n```\n\n---\n\n### 단계 4: public `Execute` 메서드 선언.\n\n#### 1. Public `Execute` 메서드 선언\n\n이 액션은 `Node`의 주 실행 인터페이스를 선언합니다. `Execute` 메서드는 `Pipeline` 오케스트레이터에 의해 호출되어 노드에 캡슐화된 작업을 실행합니다. 입력으로 `const std::any&`를 받고, 노드의 설정(작업)은 불변이므로 `const`로 표시됩니다. `[[nodiscard]]` 속성은 호출자가 `NodeResult`를 처리하도록 권장합니다.\n\n**파일**: `include/core/concurrency/pipeline/node.hpp`\n\n```cpp\n// ... (Node 클래스의 public 섹션 내부, 팩토리 메서드 다음)\n\n /**\n * @brief 주어진 입력으로 노드의 작업을 실행합니다.\n * @param input 작업에 대한 입력 데이터, std::any로 래핑됨.\n * @return 작업의 결과, NodeResult로 래핑됨.\n * @warning 호출자는 입력 std::any가 올바른 타입을 포함하고 있는지\n * 확인할 책임이 있습니다.\n */\n [[nodiscard]] auto Execute(const std::any &input = std::any{}) const\n -> NodeResult;\n```\n\n---\n\n### 단계 5: `Id`, `InputType`, `OutputType`에 대한 getter 선언.\n\n#### 1. Public 타입 정보 Getter 선언\n\n이 액션은 세 개의 `const` getter 메서드를 선언합니다. `GetId`는 노드의 고유 식별자를 반환합니다. `GetInputType`과 `GetOutputType`은 노드가 기대하는 입력 및 출력에 대한 `std::type_index`를 반환합니다. 이 getter들은 `Pipeline`이 노드를 추가할 때 타입 검사를 수행하여 한 노드의 출력이 다음 노드의 입력과 호환되는지 확인하는 데 필수적입니다.\n\n**파일**: `include/core/concurrency/pipeline/node.hpp`\n\n```cpp\n// ... (Node 클래스의 public 섹션 내부, Execute 메서드 다음)\n\n /**\n * @brief 노드의 고유 식별자를 가져옵니다.\n * @return 노드의 ID.\n */\n [[nodiscard]] auto GetId() const -> NodeId;\n /**\n * @brief 노드 입력에 대한 타입 정보를 가져옵니다.\n * @return 입력 type_index에 대한 const 참조.\n */\n [[nodiscard]] auto GetInputType() const -> const std::type_index &;\n /**\n * @brief 노드 출력에 대한 타입 정보를 가져옵니다.\n * @return 출력 type_index에 대한 const 참조.\n */\n [[nodiscard]] auto GetOutputType() const -> const std::type_index &;\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n헤더 파일이 잘 구성되었고 모든 템플릿이 올바르게 정의되었는지 확인하려면, 임시 테스트 파일을 생성하고 컴파일을 시도합니다. 이는 전체 유닛 테스트 스위트 없이 클래스 인터페이스를 검증합니다.\n\n```bash\n# 1. 임시 디렉토리에 'verification.cpp'라는 새 파일을 생성합니다.\ntouch verification.cpp\n\n# 2. 'verification.cpp'에 다음 내용을 추가합니다. 이 코드는 헤더를 포함하고\n# 팩토리 메서드를 사용하여 노드를 인스턴스화하며, 이는 템플릿 인스턴스화를\n# 트리거합니다.\n#\n# 참고: 이는 'result.hpp'가 존재하고 올바르게 구조화되었다고 가정합니다.\n# 또한 컴파일러가 프로젝트의 include 경로에 접근할 수 있다고 가정합니다.\n#\n# --- verification.cpp 내용 ---\n# #include \"core/concurrency/pipeline/node.hpp\"\n# #include \n# #include \n# \n# auto produce_data() -> std::string {\n# return \"Hello\";\n# }\n# \n# auto transform_data(std::string s) -> int {\n# return s.length();\n# }\n# \n# int main() {\n# using core::concurrency::pipeline::Node;\n# \n# auto producer_node = Node::Producer(1, &produce_data);\n# auto transformer_node = Node::Transformer(2, &transform_data);\n# \n# std::cout << \"검증 성공: 노드 인스턴스화 완료.\" << std::endl;\n# \n# return 0;\n# }\n# --- 내용 끝 ---\n\n# 3. 검증 파일을 컴파일합니다. -I./include를 프로젝트의\n# 올바른 include 디렉토리 경로로 교체하십시오.\ng++ -std=c++17 -I./include verification.cpp -o verification_test\n\n# 4. 컴파일이 성공하면 검증이 완료된 것입니다.\n# 임시 파일을 정리합니다.\nrm verification.cpp verification_test\n```\n\n### 4.2. 예상 결과\n\n3단계의 컴파일 명령어는 오류나 경고 없이 실행되어야 합니다. 컴파일에 성공하면 `verification_test` 실행 파일이 생성됩니다. 컴파일러 오류가 없다는 것은 `node.hpp` 인터페이스가 올바르게 정의되었음을 확인시켜 줍니다. `./verification_test`를 실행하면 다음이 출력됩니다:\n\n```\n검증 성공: 노드 인스턴스화 완료.\n```","`Node` 클래스 정의, 정적 팩토리 메서드, `Execute` 메서드, 타입 정보 getter를 포함하는 헤더 파일",[2028,2030,2032,2034,2036],{"_24":2029,"_83":39,"_84":446,"_85":61},"`Node` 클래스 정의",{"_24":2031,"_83":39,"_84":446,"_85":88},"정적 `Producer` 팩토리 메서드 템플릿",{"_24":2033,"_83":39,"_84":446,"_85":91},"정적 `Transformer` 팩토리 메서드 템플릿",{"_24":2035,"_83":39,"_84":446,"_85":94},"public `Execute` 메서드 선언",{"_24":2037,"_83":39,"_84":446,"_85":97},"`Id`, `InputType`, `OutputType`에 대한 getter 선언","생산자 및 변환자 노드를 위한 팩토리를 제공하는 `core::concurrency::pipeline::Node` 클래스 인터페이스를 정의",{"_22":2040,"_24":2041,"_75":2042,"_77":2043,"_79":2044,"_51":2055,"_42":99},"task-1751726668161","파이프라인 노드 로직 구현","# 작업: 파이프라인 노드 로직 구현\n\n> **에픽**: 타입 소거(Type-Erased) 파이프라인 노드\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: 래핑된 잡(job)을 호출하기 전에 타입 검사를 수행하는 핵심 실행 로직을 포함하여 `Node` 클래스 메서드를 구현합니다.\n- **근거**: 이 작업은 동작하는 `Pipeline`을 만드는 데 필수적입니다. `Node` 클래스는 데이터 처리 파이프라인의 기본 구성 요소로, 단일 원자적(atomic) 처리 단계를 캡슐화합니다. 이 클래스는 타입 소거(`std::any`, `std::function`, `std::type_index`)를 사용하여, 서로 다른 입출력 데이터 타입을 가진 이종(heterogeneous) 노드들을 타입 안전(type-safe) 방식으로 연결할 수 있게 합니다. 이를 통해 프레임워크의 핵심 목표에 필요한 유연성을 제공하면서도 런타임 정확성을 보장합니다.\n\n### 1.2. 결과물\n- **예상 결과**: 타입 소거된 잡(job)을 실행할 수 있는 `Node` 클래스 구현이 포함된 소스 파일.\n- **명세**:\n - `구현할 클래스`: `core::concurrency::pipeline::Node`\n - `핵심 메서드`: `Node::Execute(const std::any& input) const -> NodeResult`\n - `생성자`: `Node::Node(NodeId, std::function, std::type_index, std::type_index)`\n - `구현할 Getter`: `GetId`, `GetInputType`, `GetOutputType`\n- **결과 파일 구조**\n```bash\n# ./\n# └── source/\n# └── concurrency/\n# └── pipeline/\n# └── node.cpp <-- 수정됨\n```\n\n- **프로세스 흐름도**\n이 다이어그램은 이번에 구현할 핵심 로직인 `Node::Execute` 메서드의 내부 실행 흐름을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"Node::Execute(input)\"\n A[\"std::any 입력 수신\"] --> B{\"input.type()이
예상된 input_type_과 일치하는지 확인\"};\n B -- \"일치\" --> C[\"내부 job_을
입력값으로 호출\"];\n B -- \"불일치 또는
void가 아닌 타입이 예상될 경우\" --> D[\"std::invalid_argument 예외 발생\"];\n C --> E[\"NodeResult 반환\"];\n end\n subgraph \"호출 컨텍스트 (Pipeline)\"\n F[\"파이프라인 오케스트레이터\"] --> A;\n E --> F;\n end\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완수해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 상세 구현은 3절에 있습니다.\n\n- [ ] `Node` 생성자 구현.\n- [ ] `Execute` 메서드 구현.\n- [ ] `Execute` 내에서 입력 `std::any`를 검증하는 런타임 타입 검사 구현.\n- [ ] 저장된 `std::function` 잡(job) 호출 구현.\n- [ ] 모든 getter 메서드 구현.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 핵심 컴포넌트**:\n - **`pipeline::Node`**: 현재 구현 중인 컴포넌트입니다. 동시성 데이터 파이프라인 내에서 타입이 소거된 단일 처리 단계의 역할을 담당합니다. 이 작업에서는 해당 컴포넌트의 핵심 로직을 구현합니다.\n - **`Pipeline`**: 이 상위 컴포넌트는 `Node` 인스턴스를 생성하고 `Execute` 메서드를 호출합니다. `Pipeline`은 `Node`의 타입 정보 getter에 의존하여 노드 간의 연결을 검증합니다.\n - **`ThreadPool`**: `Pipeline`은 `Node::Execute` 호출이 `ThreadPool`에서 실행되도록 스케줄링합니다. `Node` 자체는 실행 컨텍스트에 구애받지 않지만, 어떤 스레드에서든 호출될 수 있도록 설계되었습니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `source/concurrency/pipeline/node.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 여러 개의 세부적인 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `Node` 생성자 구현.\n\n#### 1. Node 생성자 구현\n\n이 액션은 `Node` 클래스의 주 생성자를 구현합니다. 생성자의 목적은 고유 ID, 호출 가능한 작업(job), 그리고 입출력 타입 인덱스를 받아 노드의 불변 상태를 초기화하는 것입니다. 멤버 초기화 목록을 사용하여 효율적으로 생성하며, 복사를 피하기 위해 `job` 함수를 이동(move)시킵니다. 이 상태는 노드의 실행 및 타입 검사 로직에 필수적입니다.\n\n**파일**: `source/concurrency/pipeline/node.cpp`\n\n```cpp\n#include \"core/concurrency/pipeline/node.hpp\"\n\n// ... other includes\n\nnamespace core::concurrency::pipeline {\n\nNode::Node(NodeId node_id, std::function job,\n std::type_index input_type, std::type_index output_type)\n : node_id_(node_id),\n job_(std::move(job)),\n input_type_(input_type),\n output_type_(output_type) {}\n\n// ...\n```\n\n---\n\n### 단계 2: `Execute` 메서드 구현.\n\n#### 1. `Execute` 메서드 시그니처 정의\n\n이 액션은 `node.cpp` 소스 파일 내에 `Execute` 메서드를 정의합니다. 이 메서드는 노드에 캡슐화된 로직을 실행하기 위한 공개 인터페이스입니다. 노드를 실행하는 것이 노드의 설정(ID, 타입, 잡 자체)을 변경해서는 안 되므로 `const`로 선언됩니다. 이전 노드로부터 데이터를 받기 위해 `const std::any&`를 인자로 받고, 출력 데이터와 제어 흐름 정보를 담고 있는 `NodeResult`를 반환하도록 명시됩니다.\n\n**파일**: `source/concurrency/pipeline/node.cpp`\n\n```cpp\n// ... constructor and other methods\n\nauto Node::Execute(const std::any& input) const -> NodeResult {\n // 다음 단계들에서 로직 구현 예정\n}\n\n// ...\n```\n\n---\n\n### 단계 3: `Execute` 내에서 입력 `std::any`를 검증하는 런타임 타입 검사 구현.\n\n#### 1. 런타임 입력 타입 유효성 검사 추가\n\n이 액션은 `Execute` 메서드에 핵심적인 런타임 타입 검사 로직을 추가합니다. 이 검사는 파이프라인의 타입 안정성을 보장하는 주요 메커니즘입니다. 실제 `input` `std::any` 객체의 `type_index`를 노드가 예상하는 `input_type_`과 비교합니다. 만약 두 타입이 일치하지 않으면, 치명적인 타입 오류를 방지하기 위해 `std::invalid_argument` 예외를 발생시킵니다. 이전 노드로부터 데이터를 받지 않는 `void` 입력 타입을 가진 \"생산자(producer)\" 노드의 경우 이 검사를 건너뛰도록 특별한 조건이 추가됩니다.\n\n**파일**: `source/concurrency/pipeline/node.cpp`\n\n```cpp\n// ...\n\nauto Node::Execute(const std::any& input) const -> NodeResult {\n if (input_type_ != std::type_index(typeid(void)) &&\n std::type_index(input.type()) != input_type_) {\n throw std::invalid_argument(\"Input type mismatch\");\n }\n // ...\n}\n\n// ...\n```\n\n---\n\n### 단계 4: 저장된 `std::function` 잡(job) 호출 구현.\n\n#### 1. 캡슐화된 잡(job) 호출\n\n이 액션은 `Execute` 메서드 로직의 마지막 부분을 추가합니다. 타입 검사가 통과된 후, 저장된 `job_` 함수가 제공된 `input`으로 호출됩니다. 이는 노드의 핵심 목적인 캡슐화된 로직을 입력 데이터에 적용하는 것입니다. `job_`에 의해 생성된 `NodeResult`는 `Execute` 메서드에 의해 반환되어, 그 결과를 파이프라인 오케스트레이터에게 전달합니다.\n\n**파일**: `source/concurrency/pipeline/node.cpp`\n\n```cpp\n// ...\n\nauto Node::Execute(const std::any& input) const -> NodeResult {\n if (input_type_ != std::type_index(typeid(void)) &&\n std::type_index(input.type()) != input_type_) {\n throw std::invalid_argument(\"Input type mismatch\");\n }\n return job_(input);\n}\n\n// ...\n```\n\n---\n\n### 단계 5: 모든 getter 메서드 구현.\n\n#### 1. 접근자 메서드 구현\n\n이 액션은 `GetId`, `GetInputType`, `GetOutputType` getter 메서드의 구현을 제공합니다. 이 간단한 접근자 메서드들은 외부 컴포넌트, 특히 `Pipeline` 오케스트레이터가 노드의 설정을 조회하는 데 필요합니다. 이를 통해 `Pipeline`은 실행이 시작되기 전에 한 노드의 출력 타입이 다음 노드의 입력 타입과 일치하는지 검증할 수 있습니다. 이들은 해당 private 멤버 변수를 반환하는 `const` 메서드입니다.\n\n**파일**: `source/concurrency/pipeline/node.cpp`\n\n```cpp\n// ...\n\nauto Node::GetId() const -> NodeId { return node_id_; }\n\nauto Node::GetInputType() const -> const std::type_index& {\n return input_type_;\n}\n\nauto Node::GetOutputType() const -> const std::type_index& {\n return output_type_;\n}\n\n} // namespace core::concurrency::pipeline\n```\n\n---\n\n## 4. 검증 절차\n\n### 4.1. 검증 단계\n\n- 이 클래스의 구현은 해당 유닛 테스트를 통해 공식적으로 검증됩니다. 이 특정 작업의 주된 검증은 변경 사항 적용 후 프레임워크가 성공적으로 컴파일되는지 확인하는 것입니다.\n\n```bash\n# 1. 빌드 디렉토리로 이동\ncd build/\n\n# 2. 빌드 명령어 실행\n# 이 명령어는 수정된 node.cpp 파일을 컴파일하고 프레임워크 라이브러리에 링크합니다.\nmake\n```\n\n- 이 컴포넌트에 대한 공식적인 유닛 테스트는 **작업 13.4: 파이프라인 및 스케줄러 프레임워크 유닛 테스트**에서 수행될 예정입니다.\n\n### 4.2. 예상 결과\n\n- `make` 명령어가 컴파일이나 링크 오류 없이 완료되어야 합니다. 표준 출력은 빌드 프로세스가 성공했음을 나타내야 합니다.\n\n```\n[...빌드 진행률...]\n[100%] Built target core\n```","타입이 지워진 작업을 실행할 수 있는 `Node` 클래스 구현이 포함된 소스 파일",[2045,2047,2049,2051,2053],{"_24":2046,"_83":39,"_84":466,"_85":61},"`Node` 생성자 구현",{"_24":2048,"_83":39,"_84":466,"_85":88},"`Execute` 메서드 구현",{"_24":2050,"_83":39,"_84":466,"_85":91},"입력 `std::any`를 검증하기 위한 `Execute`의 런타임 타입 검사",{"_24":2052,"_83":39,"_84":466,"_85":94},"저장된 `std::function` 작업 호출",{"_24":2054,"_83":39,"_84":466,"_85":97},"모든 getter 메서드 구현","래핑된 작업을 호출하기 전에 타입 검사를 수행하는 핵심 실행 로직을 포함하여 `Node` 클래스 메서드를 구현",{"_22":2057,"_24":2058,"_75":2059,"_77":2060,"_79":2061,"_51":2072,"_42":99},"task-1751726755664","주기적 스케줄러 클래스 인터페이스 정의","# 작업: 주기적 스케줄러 클래스 인터페이스 정의\n\n> **에픽**: 주기적 작업 스케줄러\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: 주기적인 작업을 관리, 스케줄링, 실행하기 위한 `core::concurrency::Scheduler` 클래스 인터페이스를 정의합니다.\n- **근거**: 이 작업은 시간 기반 작업 실행을 담당하는 고수준 컴포넌트인 `Scheduler`의 공개 API를 구축합니다. 잘 정의된 인터페이스는 `Scheduler`를 클라이언트로부터 분리(decoupling)하고 예측 가능한 상호작용을 보장하는 데 매우 중요합니다. 이 인터페이스는 주기적 실행 관리의 복잡성을 추상화하며, 비동기 작업은 기반이 되는 `ThreadPool`에, 시간 순서 정렬은 `ExecutionEntry`에 의존합니다. 이 컴포넌트는 반복적인 데이터 처리 사이클이 필요한 SLAM과 같은 애플리케이션을 구축하는 데 핵심적인 역할을 합니다.\n\n### 1.2. 결과물\n- **예상 결과물**: `Scheduler` 클래스 정의, 공개 API, 그리고 내부 데이터 구조를 포함하는 헤더 파일.\n- **명세**:\n - `class Scheduler`: `core::concurrency` 네임스페이스 내의 메인 클래스 정의.\n - `enum class ExecutionMode`: `kMainThread`와 `kThreadPool` 실행 옵션을 정의합니다.\n - `struct ScheduledTask`: `TaskId`, `std::function` 그리고 `std::chrono::milliseconds`를 포함하는 비공개 구조체.\n - `Public Methods`:\n - `explicit Scheduler(std::shared_ptr thread_pool);`\n - `~Scheduler();`\n - `auto AddTask(std::function task, std::chrono::milliseconds period) -> std::optional;`\n - `void CancelTask(TaskId task_id);`\n - `void Start(ExecutionMode mode);`\n - `void Stop();`\n- **결과 파일 구조**\n```bash\n./\n└── include/\n └── core/\n └── concurrency/\n ├── execution_entry.hpp\n ├── scheduler.hpp <-- 신규\n └── thread_pool.hpp\n```\n\n- **프로세스 흐름도**\n 아래 다이어그램은 `Scheduler` 인터페이스와의 일반적인 상호작용을 보여줍니다. 애플리케이션은 스케줄러가 유휴 상태일 때 작업을 추가한 다음, 스케줄러를 시작합니다. `Scheduler`는 내부적으로 루프를 관리하며, 정확한 시간에 `ThreadPool`로 작업을 푸시합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"설정 단계 (스케줄러 유휴 상태)\"\n App[\"애플리케이션\"] -- \"1\\. AddTask(task, 100ms)\" --> S(Scheduler);\n App -- \"2\\. AddTask(another_task, 500ms)\" --> S;\n end\n\n subgraph \"실행 단계 (스케줄러 실행 중)\"\n App -- \"3\\. Start(kThreadPool)\" --> S;\n S --> Loop[\"스케줄러 루프\"];\n Loop -- \"4\\. 다음 작업 시간까지 대기\" --> Loop;\n Loop -- \"5\\. EnqueueJob(task)\" --> TP[\"ThreadPool\"];\n TP -- \"6\\. 작업 실행\" --> TP;\n end\n\n S -- \"std::shared_ptr 소유\" --> TP\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 아래 항목들을 완수해야 합니다. 이것은 개략적인 체크리스트이며, 각 항목에 대한 상세 구현은 3장에 있습니다.\n\n- [ ] `Scheduler` 클래스 정의.\n- [ ] 공개 메서드 `AddTask`, `CancelTask`, `Start`, `Stop`.\n- [ ] `ExecutionMode` 열거형.\n- [ ] 내부 `ScheduledTask` 구조체.\n- [ ] 스레드 풀, 작업 맵, 실행 큐를 위한 멤버 변수.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - **`Scheduler`**: 정의 대상인 주 컴포넌트입니다. 등록된 작업의 생명주기와 주기적 실행을 관리하는 책임을 가집니다. 이 작업에서는 해당 컴포넌트의 공개 계약(public contract)을 정의합니다.\n - **`ThreadPool`**: 핵심적인 의존성입니다. `Scheduler`는 `ThreadPool`에 대한 공유 포인터를 보유하며, 이를 모든 작업의 실행 컨텍스트로 사용하여 실제 동시성 작업의 부담을 덜어줍니다.\n - **`ExecutionEntry`**: 데이터 구조 의존성입니다. `Scheduler`는 예약된 시간을 기준으로 다음에 실행할 작업을 효율적으로 결정하기 위해 내부 우선순위 큐에서 `ExecutionEntry` 객체를 사용합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `include/core/concurrency/scheduler.hpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 각 항목에 해당합니다. 각 `단계`는 세분화된 `행동`으로 나뉩니다. 각 `행동`에 대해 제목, '무엇을'과 '왜'를 포함하는 명확한 서술적 설명, 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `Scheduler` 클래스 정의.\n\n#### 1. 클래스 셸과 핵심 생명주기 메서드 정의\n\n이 행동은 `Scheduler` 클래스의 기본 구조를 설정합니다. 생성자는 `std::shared_ptr`을 요구하여 의존성을 명시적으로 만들고, `Scheduler`가 실행 엔진 없이는 존재할 수 없도록 강제합니다. 소멸자는 적절한 정리를 보장하기 위해 선언되었으며, 복사/이동 대입 및 생성자는 `Scheduler` 인스턴스가 고유한 상태 저장 실행 컨텍스트를 나타내므로 중복을 방지하기 위해 삭제되었습니다. ``, `` 등과 같은 의존성을 위한 표준 헤더가 포함됩니다.\n\n**파일**: `include/core/concurrency/scheduler.hpp`\n\n```cpp\n/**\n * @file scheduler.hpp\n * @author movingChurch (yes@holyground.world)\n * @brief 주기적 작업 스케줄러를 정의합니다.\n * ...\n */\n#ifndef CORE__CONCURRENCY__SCHEDULER_HPP_\n#define CORE__CONCURRENCY__SCHEDULER_HPP_\n\n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n\n#include \"core/concurrency/execution_entry.hpp\"\n#include \"core/concurrency/thread_pool.hpp\"\n\nnamespace core::concurrency {\n\nclass Scheduler {\n public:\n using TaskId = core::concurrency::TaskId;\n\n explicit Scheduler(std::shared_ptr thread_pool);\n ~Scheduler();\n\n Scheduler(const Scheduler&) = delete;\n auto operator=(const Scheduler&) -> Scheduler& = delete;\n Scheduler(Scheduler&&) = delete;\n auto operator=(Scheduler&&) -> Scheduler& = delete;\n\n // ... 공개 메서드와 비공개 멤버가 추가될 예정\n};\n\n} // namespace core::concurrency\n\n#endif // CORE__CONCURRENCY__SCHEDULER_HPP_\n```\n\n---\n\n### 단계 2: 공개 메서드 `AddTask`, `CancelTask`, `Start`, `Stop`.\n\n#### 1. 작업 및 생명주기 관리 API 정의\n\n이 행동은 `Scheduler`와 상호작용하기 위한 주된 공개 인터페이스를 정의합니다. `AddTask`와 `CancelTask`는 클라이언트가 실행이 시작되기 전에 예약된 작업 집합을 관리할 수 있게 합니다. `Start`와 `Stop`은 스케줄러의 주 실행 루프를 제어합니다. 이러한 메서드들은 컴포넌트의 제어 표면 역할을 하여, 설정 단계(작업 추가/제거)와 활성 단계(작업 실행)를 명확하게 분리합니다.\n\n**파일**: `include/core/concurrency/scheduler.hpp`\n\n```cpp\nclass Scheduler {\n public:\n // ... 생성자, 소멸자, 삭제된 멤버들\n \n auto AddTask(std::function task, std::chrono::milliseconds period)\n -> std::optional;\n\n void CancelTask(TaskId task_id);\n\n // ... ExecutionMode 열거형이 여기에 추가될 예정\n \n void Start(ExecutionMode mode);\n\n void Stop();\n\n private:\n // ... 비공개 멤버들\n};\n```\n\n---\n\n### 단계 3: `ExecutionMode` 열거형.\n\n#### 1. `ExecutionMode` 열거형 정의\n\n이 행동은 `ExecutionMode` 열거형을 추가하여 스케줄러 자체의 처리 루프가 실행되는 방식에 유연성을 제공합니다. `kMainThread`는 `Start` 호출을 블로킹(blocking) 방식으로 만들어 간단한 애플리케이션이나 테스트에 유용합니다. `kThreadPool`은 루프 자체를 작업으로 제출하여 호출 스레드를 즉시 해제할 수 있게 합니다. 이러한 설계 결정은 `Scheduler`가 다양한 스레딩 모델에 적응할 수 있도록 만듭니다.\n\n**파일**: `include/core/concurrency/scheduler.hpp`\n\n```cpp\nclass Scheduler {\n public:\n // ... AddTask, CancelTask 등\n\n /**\n * @brief 스케줄러의 주 루프를 위한 실행 컨텍스트를 정의합니다.\n */\n enum class ExecutionMode : std::uint8_t {\n kMainThread, ///< 호출한 스레드에서 루프를 실행하며, 해당 스레드를 블로킹합니다.\n kThreadPool, ///< 루프를 스레드 풀에 작업으로 제출합니다.\n };\n\n void Start(ExecutionMode mode);\n \n // ... Stop 등\n};\n```\n\n---\n\n### 단계 4: 내부 `ScheduledTask` 구조체.\n\n#### 1. 비공개 `ScheduledTask` 데이터 구조 정의\n\n이 행동은 `ScheduledTask` 구조체를 비공개 멤버로 정의합니다. 이 구조체는 단일 작업에 필요한 모든 정보, 즉 고유 ID, 호출 가능한 함수 객체, 실행 주기를 캡슐화합니다. 이를 비공개 구현 세부 사항으로 유지함으로써 내부 저장 메커니즘을 클라이언트로부터 숨기고, `Scheduler` 클래스 내에서 작업 데이터를 깔끔하고 체계적으로 관리할 수 있는 방법을 제공합니다.\n\n**파일**: `include/core/concurrency/scheduler.hpp`\n\n```cpp\nclass Scheduler {\n // ... 공개 인터페이스\n\n private:\n /**\n * @brief 스케줄러가 관리하는 작업의 내부 표현입니다.\n */\n struct ScheduledTask {\n TaskId task_id; ///< 작업의 고유 식별자.\n std::function task; ///< 호출 가능한 작업 객체.\n std::chrono::milliseconds period; ///< 작업의 실행 간격.\n };\n\n void Loop(); ///< 스케줄러의 주 처리 루프.\n\n // ... 멤버 변수들이 여기에 추가될 예정\n};\n```\n\n---\n\n### 단계 5: 스레드 풀, 작업 맵, 실행 큐를 위한 멤버 변수.\n\n#### 1. 모든 비공개 멤버 변수 선언\n\n이 행동은 `Scheduler`의 작동에 필요한 모든 멤버 변수를 선언합니다.\n- `thread_pool_`: `ThreadPool`에 대한 공유 포인터를 저장합니다.\n- `stop_flag_`, `is_running_`: 원자적(atomic) 불리언은 주 루프에 대한 스레드 안전한 제어 및 상태 확인을 제공합니다.\n- `next_task_id_`: 원자적 카운터는 새로운 작업마다 고유한 ID가 부여되도록 보장합니다.\n- `tasks_`: `std::map`은 `CancelTask` 작업에 필수적인 ID별 `ScheduledTask`를 효율적으로 저장하고 검색하는 방법을 제공합니다.\n- `execution_queue_`: 다음 실행 시간으로 정렬된 `ExecutionEntry` 객체들의 `std::priority_queue`입니다. 이것은 `Scheduler`가 모든 작업을 순회하지 않고도 다음에 실행할 작업을 효율적으로 결정할 수 있게 해주는 핵심 데이터 구조입니다.\n\n**파일**: `include/core/concurrency/scheduler.hpp`\n\n```cpp\nclass Scheduler {\n // ... 공개 인터페이스\n\n private:\n // ... ScheduledTask 구조체와 Loop() 선언\n\n std::shared_ptr\n thread_pool_; ///< 작업을 실행하기 위한 스레드 풀.\n std::atomic stop_flag_{false}; ///< 루프에 중지를 알리는 플래그.\n std::atomic next_task_id_{\n 0}; ///< 고유한 작업 ID를 생성하기 위한 카운터.\n\n std::map tasks_; ///< 등록된 모든 작업을 저장합니다.\n std::priority_queue,\n std::greater<>>\n execution_queue_; ///< 다음 실행 시간을 관리하기 위한 우선순위 큐.\n\n std::atomic is_running_{\n false}; ///< 스케줄러 루프가 활성 상태인지 나타냅니다.\n};\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n이 작업은 헤더 파일 생성만을 포함하므로, 검증은 파일의 문법이 올바른지와 다른 C++ 소스 파일에 성공적으로 포함될 수 있는지를 확인하는 것으로 구성됩니다.\n\n1. `tests/unit/scheduler_interface_compile_test.cpp`라는 이름의 **임시 테스트 파일을 생성**합니다. 이 파일은 기본적인 컴파일 확인 역할을 합니다.\n\n ```cpp\n // tests/unit/scheduler_interface_compile_test.cpp\n #include \"core/concurrency/scheduler.hpp\"\n\n // 이 테스트는 헤더가 잘 구성되었는지 확인하기 위해 컴파일만 되면 됩니다.\n // 전체 단위 테스트는 후속 작업에서 구현될 것입니다.\n int main() {\n return 0;\n }\n ```\n\n2. **테스트 파일 컴파일을 시도합니다.** 프로젝트의 빌드 시스템(예: CMake)이나 직접적인 컴파일러 명령어를 사용합니다. 이 명령어는 표준 인클루드 경로 설정을 가정합니다.\n\n ```bash\n # 빌드 도구가 구성되었는지 확인합니다 (예: cmake 실행)\n # 그런 다음, 이 새 테스트 파일을 포함하는 타겟을 빌드하려고 시도합니다.\n # 예를 들어, CMake 사용 시:\n cmake --build ./build\n\n # 또는, 직접 g++ 명령어 사용 시 (필요에 따라 인클루드 경로 조정):\n g++ -std=c++17 -I./include tests/unit/scheduler_interface_compile_test.cpp -o /dev/null\n ```\n\n### 4.2. 예상 결과\n\n- 컴파일 명령어는 종료 코드 `0`으로 성공적으로 완료되어야 합니다.\n- `scheduler.hpp`와 관련된 컴파일러 오류나 경고가 발생하지 않아야 합니다. 이를 통해 클래스와 모든 멤버 정의의 문법이 유효하며, 필요한 모든 의존성이 올바르게 포함되었음을 확인합니다.","`Scheduler` 클래스 정의, public API, 내부 데이터 구조를 포함하는 헤더 파일",[2062,2064,2066,2068,2070],{"_24":2063,"_83":39,"_84":1477,"_85":61},"`Scheduler` 클래스 정의",{"_24":2065,"_83":39,"_84":1477,"_85":88},"Public 메서드 `AddTask`, `CancelTask`, `Start`, `Stop`",{"_24":2067,"_83":39,"_84":1477,"_85":91},"`ExecutionMode` 열거형",{"_24":2069,"_83":39,"_84":1477,"_85":94},"내부 `ScheduledTask` 구조체",{"_24":2071,"_83":39,"_84":1477,"_85":97},"스레드 풀, 태스크 맵, 실행 큐를 위한 멤버 변수","주기적인 작업을 관리, 스케줄링, 실행하기 위한 `core::concurrency::Scheduler` 클래스 인터페이스를 정의",{"_22":2074,"_24":2075,"_75":2076,"_77":2077,"_79":2078,"_51":2089,"_42":99},"task-1751726808134","스케줄러 작업 관리 구현","# 작업: 스케줄러 태스크 관리 구현\n\n> **에픽**: 주기적 태스크 스케줄러\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: `Scheduler`의 태스크 등록 및 취소 로직 구현\n- **근거**: 이 작업은 `Scheduler`에 처리할 작업을 채워 넣기 위한 핵심 public API를 구축합니다. 스레드 안전성과 예측 가능한 동작을 보장하기 위해, 스케줄러의 실행 루프가 활성 상태일 때는 스케줄러의 태스크 컬렉션 수정을 금지해야 합니다. 이 메서드들은 `is_running_` 상태를 확인하여 이 규칙을 강제함으로써, 경쟁 상태(race condition)를 방지하고 실행 중에는 태스크 집합이 불변(immutable)하도록 보장해야 합니다.\n\n### 1.2. 결과물\n- **예상 결과물**: 스케줄러가 실행 중이 아닐 때 스케줄러의 태스크 맵을 올바르게 수정하는 `AddTask` 및 `CancelTask` 메서드 구현\n- **명세**:\n - `AddTask` 메서드 시그니처: `auto AddTask(std::function task, std::chrono::milliseconds period) -> std::optional;`\n - `CancelTask` 메서드 시그니처: `void CancelTask(TaskId task_id);`\n - 두 메서드 모두 내부 `tasks_` 맵 수정을 시도하기 전에 `is_running_` 원자적 플래그(atomic flag)를 확인해야 합니다.\n- **결과 파일 구조**\n```bash\n# ./source/concurrency/\n# └── scheduler.cpp <-- 수정됨\n```\n\n- **프로세스 흐름도**\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"스케줄러 상호작용 (미실행 상태)\"\n App[\"애플리케이션\"] -- \"1\\. `AddTask(task, period)`\" --> Scheduler\n Scheduler -- \"2\\. `is_running_`이 false\" --> AddLogic{\"추가 로직 진행\"}\n AddLogic -- \"3\\. 고유 `TaskId` 생성\" --> AddLogic\n AddLogic -- \"4\\. `tasks_` 맵에 `ScheduledTask` 저장\" --> AddLogic\n Scheduler -- \"5\\. `std::optional` 반환\" --> App\n end\n \n subgraph \" \"\n direction LR\n App2[\"애플리케이션\"] -- \"1\\. `CancelTask(id)`\" --> Scheduler2[\"스케줄러\"]\n Scheduler2 -- \"2\\. `is_running_`이 false\" --> CancelLogic{\"취소 로직 진행\"}\n CancelLogic -- \"3\\. `tasks_` 맵에서 태스크 삭제\" --> CancelLogic\n Scheduler2 -- \"4\\. `void` 반환\" --> App2\n end\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 아래 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 상세 구현은 3절에 기술되어 있습니다.\n\n- [ ] `is_running_` 확인을 포함한 `AddTask` 구현\n- [ ] 신규 태스크에 대한 고유 `TaskId` 생성\n- [ ] `tasks_` 맵에 신규 태스크 저장\n- [ ] `is_running_` 확인을 포함한 `CancelTask` 구현\n- [ ] `tasks_` 맵에서 지정된 태스크 제거\n\n## 2. 기술적 컨텍스트\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - **Scheduler**: 이 작업에서 수정될 주요 컴포넌트입니다. 아키텍처에서 정의된 대로, `Scheduler`의 책임은 반복적인 태스크를 관리하고 실행하는 것입니다. 이 작업은 사용자가 스케줄러가 수행할 작업을 정의할 수 있도록 하는 핵심 설정 인터페이스를 구현합니다.\n - **ThreadPool**: `Scheduler`는 작업을 실행하기 위해 `ThreadPool`에 의존합니다. 이 작업에서 직접 수정되지는 않지만, `AddTask`를 통해 추가되는 태스크들은 궁극적으로 공유 `ThreadPool`에서 실행되도록 예정되어 있으므로, `ThreadPool`은 중요한 하위 의존성(downstream dependency)입니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `source/concurrency/scheduler.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 여러 개의 세부적인 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `is_running_` 확인을 포함한 `AddTask` 구현\n\n#### 1. `AddTask` 메서드 구현\n\n이 액션은 스케줄러에 새로운 태스크를 추가하는 public 메서드를 구현합니다. 핵심 설계 원칙은 스케줄러가 실행 중일 때는 태스크 목록이 불변(immutable)해야 한다는 것입니다. 따라서 첫 번째 작업으로 `is_running_` 원자적 플래그를 확인합니다. 만약 `true`이면, 이 작업이 허용되지 않음을 알리기 위해 즉시 `std::nullopt`를 반환합니다. 스케줄러가 중지된 상태라면, `next_task_id_`를 원자적으로 증가시켜 고유한 태스크 식별자를 생성합니다. 그런 다음 `ScheduledTask` 구조체를 구성하고 새로운 ID를 키로 사용하여 `tasks_` 맵에 emplace합니다. 새로운 `TaskId`는 `std::optional`로 감싸져 호출자에게 반환됩니다.\n\n**파일**: `source/concurrency/scheduler.cpp`\n\n```cpp\nauto Scheduler::AddTask(std::function task,\n std::chrono::milliseconds period)\n -> std::optional {\n if (is_running_.load()) {\n return std::nullopt; // 실행 중에는 수정을 허용하지 않음\n }\n const TaskId NewId = next_task_id_++;\n tasks_.emplace(\n NewId, ScheduledTask{\n .task_id = NewId, .task = std::move(task), .period = period});\n return NewId;\n}\n```\n\n---\n\n### 단계 2: `is_running_` 확인을 포함한 `CancelTask` 구현\n\n#### 1. `CancelTask` 메서드 구현\n\n이 액션은 스케줄러에서 태스크를 제거하는 public 메서드를 구현합니다. `AddTask`와 동일한 불변성 원칙에 따라, 이 메서드는 먼저 `is_running_` 플래그를 확인합니다. 스케줄러가 활성 상태이면, 아무 작업도 수행하지 않고 즉시 반환합니다. 스케줄러가 중지된 상태이면, `erase` 메서드를 사용하여 `tasks_` 맵에서 제공된 `task_id`에 해당하는 태스크를 안전하게 제거합니다. 이 작업은 멱등성(idempotent)을 가집니다. 즉, `task_id`가 맵에 존재하지 않으면 `erase`는 아무것도 하지 않으며, 이는 의도된 동작입니다.\n\n**파일**: `source/concurrency/scheduler.cpp`\n\n```cpp\nvoid Scheduler::CancelTask(TaskId task_id) {\n if (is_running_.load()) {\n return; // 실행 중에는 수정을 허용하지 않음\n }\n tasks_.erase(task_id);\n}\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n구현은 단위 테스트를 통해 검증됩니다. `AddTask`와 `CancelTask`의 동작을 검증하기 위해 `tests/unit/scheduler_test.cpp`에 테스트 케이스가 추가되어야 합니다.\n\n1. **테스트 케이스 생성**: `scheduler_test.cpp` 파일에 새로운 테스트 케이스(예: `SchedulerTaskManagement`)를 추가합니다.\n2. **스케줄러 인스턴스화**: 모의(mock) 또는 실제 `ThreadPool`을 제공하여 `Scheduler` 인스턴스를 생성합니다.\n3. **AddTask 검증**: 중지된 스케줄러에서 `AddTask`를 호출합니다. 반환된 `std::optional`가 값을 포함하는지 단언(assert)합니다.\n4. **CancelTask 검증**: 이전 단계에서 얻은 ID를 사용하여 `CancelTask`를 호출합니다.\n5. **실행 중 상태 불변성 검증**: 스케줄러를 시작합니다. `AddTask`를 다시 호출하고 반환된 `std::optional`이 `std::nullopt`인지 단언합니다.\n6. **테스트 빌드 및 실행**: 프로젝트를 컴파일하고 빌드 디렉터리에서 단위 테스트를 실행합니다.\n\n```bash\n# 프로젝트의 빌드 디렉터리에서:\n# 1. 테스트가 활성화된 상태로 프로젝트가 빌드되었는지 확인\ncmake .. -DENABLE_TESTS=ON\ncmake --build .\n\n# 2. 단위 테스트 실행\nctest --output-on-failure\n```\n\n### 4.2. 예상 결과\n\n테스트 실행기는 새로운 `SchedulerTaskManagement` 테스트 케이스를 포함한 모든 테스트가 통과했다고 보고해야 합니다.\n\n```\n[==========] 모든 테스트 실행 중.\n[----------] 전역 테스트 환경 설정.\n[----------] SchedulerTest의 N개 테스트\n[ RUN ] SchedulerTest.SchedulerTaskManagement\n[ OK ] SchedulerTest.SchedulerTaskManagement (X ms)\n...\n[----------] SchedulerTest의 N개 테스트 (총 Y ms)\n\n[----------] 전역 테스트 환경 해제\n[==========] 모든 테스트 통과.\n[ PASSED ] N개 테스트.\n```","실행 중이 아닐 때 스케줄러의 작업 맵을 올바르게 수정하는 기능적인 `AddTask` 및 `CancelTask` 메서드",[2079,2081,2083,2085,2087],{"_24":2080,"_83":39,"_84":1493,"_85":61},"`is_running_` 확인을 포함한 `AddTask` 구현",{"_24":2082,"_83":39,"_84":1493,"_85":88},"새 작업에 대한 고유 `TaskId` 생성",{"_24":2084,"_83":39,"_84":1493,"_85":91},"`tasks_` 맵에 새 작업 저장",{"_24":2086,"_83":39,"_84":1493,"_85":94},"`is_running_` 확인을 포함한 `CancelTask` 구현",{"_24":2088,"_83":39,"_84":1493,"_85":97},"`tasks_` 맵에서 지정된 작업 제거","`Scheduler`의 작업 등록 및 취소 로직을 구현",{"_22":2091,"_24":2092,"_75":2093,"_77":2094,"_79":2095,"_51":2107,"_42":99},"task-1751726865179","스케줄러 실행 루프 및 생명주기 구현","# 작업: 스케줄러 실행 루프 및 생명주기 구현\n\n> **Epic**: 주기적 작업 스케줄러\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: `Scheduler`의 메인 실행 루프(`Loop`)와 그 생명주기 메서드(`Start`, `Stop`)를 구현합니다.\n- **근거**: 생명주기 메서드와 실행 루프는 `Scheduler`의 핵심 운영 로직을 구성합니다. `Start`와 `Stop`은 스케줄러의 상태를 제어하며, `Loop`는 반복 작업을 `ThreadPool`에 적시에 전달하는 역할을 담당합니다. 이 기능은 고성능 애플리케이션에서 주기적인 작업을 관리하려는 프레임워크의 목표에 매우 중요합니다.\n\n### 1.2. 결과물\n- **예상 결과**: 시작할 수 있고, 우선순위 큐를 기반으로 주기적으로 작업을 실행하며, 정상적으로 중지할 수 있는 완전한 스케줄러.\n- **명세**:\n - `void Start(ExecutionMode mode)`: 실행 루프를 초기화하고 시작합니다. 멱등성(idempotent)을 보장해야 합니다.\n - `void Stop()`: 실행 루프에 정상 종료 신호를 보냅니다. 스레드 안전성(thread-safe)을 보장해야 합니다.\n - `void Loop()`: 핵심 스케줄링 로직을 포함하는 비공개(private) 메인 루프입니다.\n- **결과 파일 구조**\n```bash\n# ./\n# └── source/\n# └── concurrency/\n# └── scheduler.cpp <-- 수정됨\n```\n\n- **프로세스 흐름도**\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph 스케줄러 메인 루프\n A[루프 시작] --> B{stop_flag_가 true인가?};\n B -- 예 --> Z[큐 비우고 종료];\n B -- 아니요 --> C{execution_queue_가 비었는가?};\n C -- 예 --> D[1ms 동안 대기];\n D --> A;\n C -- 아니요 --> E[다음 ExecutionEntry 확인];\n E --> F{현재 시간 >= entry.execution_time 인가?};\n F -- 아니요 --> G[entry.execution_time까지 대기];\n G --> A;\n F -- 예 --> H[큐에서 entry 꺼내기];\n H --> I{tasks_ 맵에 작업이 존재하는가?};\n I -- 아니요 --> A;\n I -- 예 --> J[ThreadPool에 작업 추가];\n J --> K[다음 주기를 위해 작업 재스케줄];\n K --> A;\n end\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 아래 항목들을 완료해야 합니다. 이는 개괄적인 체크리스트이며, 각 항목에 대한 상세 구현은 3절에 있습니다.\n\n- [ ] 실행 큐를 초기화하고 루프를 시작하는 `Start` 메서드 구현\n- [ ] 중지 플래그를 설정하는 `Stop` 메서드 구현\n- [ ] `Loop` 메서드 구현\n- [ ] 다음 작업의 실행 시간까지 대기하는 로직 구현\n- [ ] 작업을 꺼내고, 스레드 풀을 통해 실행하며, 재스케줄하는 로직 구현\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - **`Scheduler`**: 수정될 주요 컴포넌트입니다. 이 작업은 스케줄러의 핵심 생명주기 및 실행 로직을 구현하여, 주기적 작업 관리자로서 기능할 수 있게 합니다.\n - **`ThreadPool`**: `Scheduler`의 의존성입니다. `Scheduler`는 자신의 `Loop`가 블로킹되지 않고 반응성을 유지하도록 모든 작업 실행을 `ThreadPool`에 오프로드합니다.\n - **`ExecutionEntry`**: `Scheduler` 내부에서 사용하는 데이터 구조입니다. 우선순위 큐(`execution_queue_`)에 저장되어, 예정된 시간을 기준으로 실행할 다음 작업을 효율적으로 결정합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정됩니다.\n\n- `source/concurrency/scheduler.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `Step`은 **완료 조건**의 항목에 해당합니다. 각 `Step`은 세부적인 `Action`으로 나뉩니다. 각 `Action`에 대해, 제목과 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 1단계: 실행 큐를 초기화하고 루프를 시작하는 `Start` 메서드 구현\n\n#### 1. 상태 관리 및 큐 초기화 구현\n\n이 액션은 `Start` 메서드의 초기 로직을 구현합니다. 먼저 `is_running_` 원자적 플래그를 사용한 멱등성 검사를 통해 여러 실행 루프가 동시에 실행되는 것을 방지합니다. 그런 다음, `tasks_` 맵에 설정된 각 작업에 대해 `ExecutionEntry`를 생성하여 `execution_queue_`를 채웁니다. 각 작업의 초기 실행 시간은 `now() + period`로 설정하여, 모든 작업이 초기 주기가 경과한 후 한 번 실행되도록 보장합니다.\n\n**파일**: `source/concurrency/scheduler.cpp`\n```cpp\nvoid Scheduler::Start(ExecutionMode mode) {\n if (is_running_.load()) {\n return;\n }\n is_running_ = true;\n stop_flag_ = false;\n\n // 시작하기 전에, 태스크 맵에서 실행 큐를 채웁니다.\n for (const auto& [task_id, task] : tasks_) {\n execution_queue_.emplace(std::chrono::steady_clock::now() + task.period,\n task_id);\n }\n...\n```\n\n#### 2. 루프 시작 로직 구현\n\n이 액션은 `Loop()`를 실행하여 `Start` 메서드를 완성합니다. 구현은 두 가지 `ExecutionMode`를 처리해야 합니다. `kThreadPool`이 지정되면 `Loop`는 공유 `thread_pool_`에 작업으로 추가되어 백그라운드에서 실행됩니다. `kMainThread`가 지정되면 `Loop`는 직접 호출되어 호출 스레드를 블로킹합니다. 두 시나리오 모두에서 `Loop`가 반환된 직후 `is_running_` 플래그는 `false`로 재설정되어 스케줄러의 상태를 정확하게 반영합니다.\n\n**파일**: `source/concurrency/scheduler.cpp`\n```cpp\n...\n if (mode == ExecutionMode::kThreadPool) {\n thread_pool_->EnqueueJob([this]() {\n Loop();\n is_running_ = false; // 루프가 끝나면 상태를 재설정합니다\n });\n } else { // kMainThread\n Loop();\n is_running_ = false; // 루프가 끝나면 상태를 재설정합니다\n }\n}\n```\n\n---\n\n### 2단계: 중지 플래그를 설정하는 `Stop` 메서드 구현\n\n#### 1. 정상 종료 플래그 설정\n\n이 액션은 `Stop` 메서드를 구현합니다. 유일한 책임은 원자적 `stop_flag_`를 `true`로 설정하는 것입니다. 이것은 `Loop`가 실행 주기를 정상적으로 종료하도록 신호를 보내는 논블로킹(non-blocking), 스레드 안전(thread-safe) 작업입니다. `Loop` 자체는 이 상태 변경을 감지하고 종료할 책임이 있습니다.\n\n**파일**: `source/concurrency/scheduler.cpp`\n```cpp\nvoid Scheduler::Stop() {\n stop_flag_ = true;\n // 참고: 루프는 중지되지만, is_running_은\n // Start() 메서드 범위 내에서 루프가 완전히 종료된 후에만 false로 설정됩니다.\n}\n```\n\n---\n\n### 3단계: `Loop` 메서드 구현\n\n#### 1. 메인 루프 및 종료 조건 설정\n\n이 액션은 스케줄러의 심장부인 메인 `while` 루프를 설정합니다. 루프의 계속 조건은 원자적 `stop_flag_`에 따라 결정되며, 다른 스레드에서 `Stop()`이 호출되었을 때 깔끔하게 종료되도록 보장합니다.\n\n**파일**: `source/concurrency/scheduler.cpp`\n```cpp\nvoid Scheduler::Loop() {\n while (!stop_flag_.load()) {\n ...\n }\n...\n}\n```\n\n---\n\n### 4단계: 다음 작업의 실행 시간까지 대기하는 로직 구현\n\n#### 1. 효율적인 대기 상태 구현\n\n이 액션은 바쁜 대기(busy-waiting)를 방지하기 위해 루프 내에 두 가지 대기 상태를 구현합니다. 첫째, `execution_queue_`가 비어 있으면 스레드는 최소한의 시간 동안 잠들게 됩니다. 둘째, 큐의 다음 작업이 미래 시간으로 예약된 경우, 스레드는 `std::this_thread::sleep_until`을 사용하여 효율적으로 잠들고, 작업이 실행될 시간에 정확히 깨어납니다.\n\n**파일**: `source/concurrency/scheduler.cpp`\n```cpp\n...\n while (!stop_flag_.load()) {\n if (execution_queue_.empty()) {\n std::this_thread::sleep_for(\n std::chrono::milliseconds(1)); // 작업이 없으므로 잠시 대기\n continue;\n }\n\n const auto NextEntry = execution_queue_.top();\n auto now = std::chrono::steady_clock::now();\n\n if (now >= NextEntry.GetExecutionTime()) {\n ...\n } else {\n std::this_thread::sleep_until(NextEntry.GetExecutionTime());\n }\n }\n...\n```\n\n---\n\n### 5단계: 작업을 꺼내고, 스레드 풀을 통해 실행하며, 재스케줄하는 로직 구현\n\n#### 1. 작업 전달 및 재스케줄링 구현\n\n이 액션은 핵심 스케줄링 로직을 구현합니다. 작업의 실행 시간이 되면, 우선순위 큐에서 꺼내집니다. `tasks_.contains()`를 사용하여 작업이 예약된 이후에 취소되지 않았는지 확인합니다. 작업이 유효하면, 해당 작업은 비동기 실행을 위해 `thread_pool_`에 추가됩니다. 마지막으로, 동일한 작업에 대해 실행 시간이 `now + period`인 새로운 `ExecutionEntry`가 생성되어 큐에 다시 추가됨으로써, 주기적인 실행이 계속되도록 보장합니다.\n\n**파일**: `source/concurrency/scheduler.cpp`\n```cpp\n...\n if (now >= NextEntry.GetExecutionTime()) {\n execution_queue_.pop();\n\n // 작업이 취소되었다면 맵에 존재하지 않습니다.\n if (tasks_.contains(NextEntry.GetTaskId())) {\n const auto& task_to_run = tasks_.at(NextEntry.GetTaskId());\n thread_pool_->EnqueueJob(task_to_run.task);\n // 다음 주기를 위해 동일한 불변(immutable) 작업을 다시 스케줄합니다.\n execution_queue_.emplace(now + task_to_run.period,\n NextEntry.GetTaskId());\n }\n...\n```\n\n#### 2. 루프 종료 후 큐 정리 구현\n\n이 액션은 루프가 종료된 후 `Scheduler`가 깨끗한 상태를 유지하도록 보장합니다. 마지막 `while` 루프는 `execution_queue_`를 비웁니다. 이는 `Start()`가 다시 호출될 때 큐에 이전 실행의 오래된 항목이 포함되지 않도록 하기 위해 필요합니다.\n\n**파일**: `source/concurrency/scheduler.cpp`\n```cpp\n...\n }\n\n // 다음 Start() 호출을 위해 큐를 비웁니다\n while (!execution_queue_.empty()) {\n execution_queue_.pop();\n }\n}\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- `Scheduler`의 생명주기와 주기적 실행을 검증하기 위해 `tests/unit/`에 단위 테스트를 추가해야 합니다.\n\n```bash\n# 1. 새 단위 테스트 파일 생성: tests/unit/scheduler_test.cpp\n\n# 2. 작업이 주기적으로 실행되는지 검증하는 테스트 케이스를 추가합니다.\n# - ThreadPool과 Scheduler를 인스턴스화합니다.\n# - 작업의 상태로 원자적 카운터를 사용합니다.\n# - 10ms마다 카운터를 증가시키는 작업을 추가합니다.\n# - kThreadPool 모드로 스케줄러를 시작합니다.\n# - 테스트 스레드를 55ms 동안 대기시킵니다.\n# - 스케줄러를 중지합니다.\n# - 카운터가 최소 5인지 확인합니다.\n\n# 3. 프로젝트의 단위 테스트를 컴파일하고 실행합니다.\n./build.sh && ./build/run_tests\n```\n\n### 4.2. 예상 결과\n\n- 새로운 단위 테스트는 통과해야 하며, 기존의 모든 테스트도 계속 통과해야 합니다. 테스트 출력은 성공을 나타내야 합니다.\n\n```\n[==========] Running 1 test from 1 test suite.\n[----------] Global test environment set-up.\n[----------] 1 test from SchedulerTest\n[ RUN ] SchedulerTest.ExecutesTasksPeriodicallyAndStops\n[ OK ] SchedulerTest.ExecutesTasksPeriodicallyAndStops (60 ms)\n[----------] 1 test from SchedulerTest (60 ms total)\n\n[----------] Global test environment tear-down\n[==========] 1 test from 1 test suite ran. (60 ms total)\n[ PASSED ] 1 test.\n```","시작할 수 있고, 우선순위 큐에 기반하여 작업을 주기적으로 실행하며, 우아하게 중지될 수 있는 완전한 스케줄러",[2096,2099,2101,2103,2105],{"_24":2097,"_83":39,"_84":2098,"_85":61},"실행 큐를 초기화하고 루프를 시작하는 `Start` 메서드 구현",24,{"_24":2100,"_83":39,"_84":2098,"_85":88},"중지 플래그를 설정하는 `Stop` 메서드 구현",{"_24":2102,"_83":39,"_84":2098,"_85":91},"`Loop` 메서드 구현",{"_24":2104,"_83":39,"_84":2098,"_85":94},"다음 작업의 실행 시간을 기다리는 로직",{"_24":2106,"_83":39,"_84":2098,"_85":97},"작업을 꺼내 스레드 풀을 통해 실행하고 다시 스케줄링하는 로직","`Scheduler`의 주 실행 루프(`Loop`)와 생명주기 메서드(`Start`, `Stop`)를 구현",{"_22":2109,"_24":2110,"_75":2111,"_77":2112,"_79":2113,"_51":2127,"_42":99},"task-1751726911962","파이프라인 오케스트레이터 클래스 인터페이스 정의","# 작업: 파이프라인 오케스트레이터 클래스 인터페이스 정의\n\n> **에픽**: 비동기 데이터 파이프라인 오케스트레이터\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: 노드의 시퀀스를 관리하기 위한 `core::concurrency::Pipeline` 클래스 인터페이스를 정의합니다.\n- **근거**: 이 작업은 `Pipeline` 컴포넌트의 공개 API를 확립하며, 이는 복잡한 비동기 데이터 처리를 가능하게 하려는 프레임워크의 핵심 목표입니다. 명확한 인터페이스를 정의함으로써, 애플리케이션이 데이터 처리 워크플로우를 구성하고 실행하는 방법에 대한 계약을 생성합니다. 이 클래스는 `ThreadPool`을 사용하여 `pipeline::Node` 실행을 오케스트레이션하며, 순차적 비동기 연산의 주 엔진 역할을 합니다.\n\n### 1.2. 결과물\n- **예상 결과**: 노드 추가 및 실행 사이클 실행을 위한 메서드를 포함한 `Pipeline` 클래스 정의가 담긴 헤더 파일.\n- **명세**:\n - `class core::concurrency::Pipeline`\n - `enum class Pipeline::AddNodeError`\n - `메서드: explicit Pipeline(std::shared_ptr thread_pool)`\n - `메서드: auto AddNode(pipeline::Node&& node) -> std::optional`\n - `메서드: void RunCycle()`\n - `메서드: [[nodiscard]] auto IsKilled() const -> bool`\n - `비공개 메서드: void ScheduleNextNode(uint32_t node_index, std::any input)`\n- **결과 파일 구조**\n```bash\n# ./\n# └── include/\n# └── core/\n# └── concurrency/\n# └── pipeline.hpp <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 애플리케이션에서 `Pipeline` 인터페이스를 사용하여 데이터 처리 시퀀스를 구성하고 실행하는 의도된 사용법을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"애플리케이션 스코프\"\n A[\"ThreadPool 생성\"] --> B[\"ThreadPool로 Pipeline 생성\"]\n B --> C{\"노드 1 추가 (Producer)\"}\n C -- 성공 --> D{\"노드 2 추가 (Transformer)\"}\n D -- 성공 --> E[\"pipeline.RunCycle() 호출\"]\n end\n\n subgraph \"코어 프레임워크 (런타임)\"\n E --> F[Pipeline이 ThreadPool에서 노드 1 스케줄링]\n F --> G[Pipeline이 ThreadPool에서 노드 2 스케줄링]\n end\n\n C -- 실패 --> H[AddNodeError 처리]\n D -- 실패 --> H\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목을 완료해야 합니다. 이는 상위 수준의 체크리스트입니다. 각 항목에 대한 자세한 구현은 섹션 3에 있습니다.\n\n- [ ] `Pipeline` 클래스 정의.\n- [ ] `AddNodeError` enum 정의.\n- [ ] `ThreadPool`을 받는 생성자 선언.\n- [ ] `AddNode` 메서드 선언.\n- [ ] `RunCycle` 및 `IsKilled` 메서드 선언.\n- [ ] 비공개 `ScheduleNextNode` 메서드 선언.\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - **`ThreadPool`**: `Pipeline`은 모든 비동기 노드 작업을 실행하기 위해 `ThreadPool`에 의존합니다. 생성 시 제공된 `ThreadPool` 인스턴스에 대한 `shared_ptr`를 보유합니다.\n - **`pipeline::Node`**: `Pipeline`은 `pipeline::Node` 객체의 시퀀스(`std::vector`)를 관리합니다. 타입 안전 방식으로 노드를 추가하고 올바른 순서로 실행을 오케스트레이션할 책임이 있습니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `include/core/concurrency/pipeline.hpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세분화된 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `Pipeline` 클래스 정의.\n\n#### 1. `Pipeline` 클래스 뼈대 및 멤버 정의\n\n이 액션은 `Pipeline` 클래스의 주요 구조를 확립합니다. 이 클래스는 포함된 노드 및 스레드 풀과 관련된 복잡한 생명주기 문제를 방지하고 단일 소유권을 강제하기 위해 복사 및 이동이 불가능하도록 설계되었습니다. 여기에는 작업 실행에 필수적인 비공개 데이터 멤버들이 포함됩니다: 잡(job)을 실행하기 위한 `ThreadPool`에 대한 공유 포인터, `pipeline::Node`의 시퀀스를 저장하기 위한 벡터, 그리고 여러 스레드에서 파이프라인의 종료 상태를 안전하게 관리하기 위한 원자적 불리언 `is_killed_`.\n\n**파일**: `include/core/concurrency/pipeline.hpp`\n\n```cpp\n#ifndef CORE__CONCURRENCY__PIPELINE_HPP_\n#define CORE__CONCURRENCY__PIPELINE_HPP_\n\n#include \n#include \n#include \n#include \n\n#include \"core/concurrency/pipeline/node.hpp\"\n#include \"core/concurrency/thread_pool.hpp\"\n\nnamespace core::concurrency {\n\nclass Pipeline {\n public:\n // ... 공개 인터페이스는 이후 단계에서 정의될 것입니다 ...\n ~Pipeline() = default;\n\n Pipeline(const Pipeline&) = delete;\n auto operator=(const Pipeline&) -> Pipeline& = delete;\n Pipeline(Pipeline&&) = delete;\n auto operator=(Pipeline&&) -> Pipeline& = delete;\n\n private:\n // ... 비공개 메서드는 이후 단계에서 정의될 것입니다 ...\n\n std::shared_ptr\n thread_pool_; ///< 노드 실행을 위한 스레드 풀입니다.\n std::vector\n nodes_; ///< 파이프라인의 노드 시퀀스입니다.\n std::atomic is_killed_{\n false}; ///< 파이프라인이 중단되었는지를 나타내는 플래그입니다.\n};\n\n} // namespace core::concurrency\n\n#endif // CORE__CONCURRENCY__PIPELINE_HPP_\n```\n\n---\n\n### 단계 2: `AddNodeError` enum 정의.\n\n#### 1. `AddNodeError` 범위 있는 열거형(Scoped Enum) 정의\n\n이 액션은 노드 추가 시 발생할 수 있는 오류를 나타내기 위해 `Pipeline` 클래스 내에 범위 있는 열거형을 도입합니다. 범위 있는 열거형(`enum class`)을 사용하면 타입 안전하고 명시적인 오류 코드를 제공할 수 있습니다. 정의된 값인 `kTypeMismatch`와 `kFirstNodeNotProducer`는 파이프라인이 논리적으로 올바르게 구성되도록 보장하고 런타임 타입 오류를 방지하는 데 필요한 주요 유효성 검사를 다룹니다.\n\n**파일**: `include/core/concurrency/pipeline.hpp`\n\n```cpp\nclass Pipeline {\n public:\n /**\n * @brief 파이프라인에 새 노드를 추가할 때 발생할 수 있는 오류를 설명합니다.\n */\n enum class AddNodeError : std::uint8_t {\n kTypeMismatch, ///< 새 노드의 입력 타입이 이전 노드의 출력 타입과 일치하지 않습니다.\n kFirstNodeNotProducer, ///< 파이프라인에 추가된 첫 번째 노드가 프로듀서(producer)가 아닙니다 (즉, 입력이 필요합니다).\n };\n...\n};\n```\n\n---\n\n### 단계 3: `ThreadPool`을 받는 생성자 선언.\n\n#### 1. `Pipeline` 생성자 선언\n\n이 액션은 `Pipeline` 클래스의 생성자를 선언합니다. 의도하지 않은 암시적 변환을 방지하기 위해 `explicit`으로 표시됩니다. 생성자는 `std::shared_ptr`을 요구하며, 이는 `Pipeline`이 작업을 실행하기 위해 스레드 풀에 의존한다는 것을 확립합니다. 이 설계 선택은 `Pipeline`을 스레드 관리에서 분리하여 여러 `Pipeline` 또는 `Scheduler` 인스턴스가 공통 스레드 풀을 공유할 수 있도록 합니다.\n\n**파일**: `include/core/concurrency/pipeline.hpp`\n\n```cpp\nclass Pipeline {\n public:\n // ... enum 정의 ...\n\n /**\n * @brief 공유 스레드 풀을 사용하여 Pipeline을 생성합니다.\n * @param thread_pool 노드를 실행할 `ThreadPool`에 대한 `shared_ptr`입니다.\n */\n explicit Pipeline(std::shared_ptr thread_pool);\n ~Pipeline() = default;\n\n // ... 복사/이동 연산자 삭제 ...\n...\n};\n```\n\n---\n\n### 단계 4: `AddNode` 메서드 선언.\n\n#### 1. `AddNode` 공개 메서드 선언\n\n이 액션은 파이프라인 시퀀스를 구성하기 위한 공개 API 역할을 하는 `AddNode` 메서드를 선언합니다. 이 메서드는 효율적인 이동 시맨틱(move semantics)을 허용하기 위해 `pipeline::Node`를 rvalue 레퍼런스(`&&`)로 받습니다. `std::optional`를 반환하여, 노드를 추가할 수 없는 경우 성공(`std::nullopt`) 또는 특정 타입의 오류를 명확하고 현대적인 C++ 방식으로 알립니다.\n\n**파일**: `include/core/concurrency/pipeline.hpp`\n\n```cpp\nclass Pipeline {\n public:\n // ... enum 및 생성자 ...\n\n /**\n * @brief 파이프라인의 끝에 새 노드를 추가합니다.\n * @details 노드는 순차적으로 실행됩니다. 이 메서드는 새 노드의 입력 타입이 이전 노드의\n * 출력 타입과 일치하는지 확인하여 타입 안전성을 보장합니다. 첫 번째 노드는\n * 반드시 프로듀서(producer)여야 합니다.\n * @param node 추가할 노드. rvalue 레퍼런스로 전달됩니다.\n * @return 노드를 추가할 수 없는 경우 `AddNodeError`를 담은 optional을, 성공 시\n * `std::nullopt`를 반환합니다.\n */\n auto AddNode(pipeline::Node&& node) -> std::optional;\n\n // ... 다른 공개 메서드들 ...\n...\n};\n```\n\n---\n\n### 단계 5: `RunCycle` 및 `IsKilled` 메서드 선언.\n\n#### 1. `RunCycle` 및 `IsKilled` 공개 메서드 선언\n\n이 액션은 파이프라인의 실행을 제어하고 모니터링하기 위한 두 가지 핵심 메서드를 선언합니다. `RunCycle`은 모든 노드의 단일 전체 실행 시퀀스를 트리거하는 진입점입니다. `IsKilled`는 노드가 `kKill` 신호를 반환하여 파이프라인이 종료되었는지 여부를 스레드 안전하게 조회하는 방법을 제공합니다. `IsKilled`에 붙은 `[[nodiscard]]` 속성은 반환 값이 무시될 경우 컴파일러에 경고를 표시하여 `Scheduler`와 같은 호출자가 올바르게 사용하도록 유도합니다.\n\n**파일**: `include/core/concurrency/pipeline.hpp`\n\n```cpp\nclass Pipeline {\n public:\n // ... AddNode 메서드 ...\n\n /**\n * @brief 파이프라인의 단일 전체 사이클을 실행합니다.\n * @details 첫 번째 노드(프로듀서)를 스레드 풀에 스케줄링하여 파이프라인을\n * 시작합니다. 후속 노드들은 입력이 사용 가능해지면 스케줄링됩니다.\n * 파이프라인이 \"killed\" 상태인 경우, 이 메서드는 아무 조치 없이 즉시\n * 반환됩니다.\n */\n void RunCycle();\n\n /**\n * @brief 파이프라인이 `kKill` 신호에 의해 종료되었는지 확인합니다.\n * @return 파이프라인이 killed 상태이면 `true`, 그렇지 않으면 `false`를 반환합니다.\n */\n [[nodiscard]] auto IsKilled() const -> bool;\n\n private:\n // ... 비공개 멤버 및 메서드 ...\n};\n```\n\n---\n\n### 단계 6: 비공개 `ScheduleNextNode` 메서드 선언.\n\n#### 1. 비공개 `ScheduleNextNode` 메서드 선언\n\n이 액션은 비공개 헬퍼 메서드인 `ScheduleNextNode`를 선언합니다. 이 메서드는 노드의 실행 작업을 `ThreadPool`에 제출하는 핵심 내부 로직을 포함하게 됩니다. 이는 `Pipeline`이 노드 간의 데이터 흐름과 실행을 관리하는 방법의 구현 세부 사항이므로 비공개로 유지됩니다. 실행할 노드의 인덱스와 필요한 입력 데이터를 받으며, 입력 데이터는 `std::any`를 사용하여 타입이 지워집니다.\n\n**파일**: `include/core/concurrency/pipeline.hpp`\n\n```cpp\nclass Pipeline {\n public:\n // ... 공개 인터페이스 ...\n\n private:\n /**\n * @brief 시퀀스의 다음 노드를 실행하도록 스케줄링합니다.\n * @param node_index 스케줄링할 노드의 인덱스입니다.\n * @param input 노드의 입력 데이터로, `std::any`로 래핑됩니다.\n */\n void ScheduleNextNode(uint32_t node_index, std::any input);\n\n // ... 비공개 데이터 멤버 ...\n};\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n이 작업은 헤더 파일(`.hpp`) 생성만 포함하므로 직접 실행은 불가능합니다. 검증은 새 헤더가 빌드 시스템에 의해 성공적으로 컴파일될 수 있는지 확인하여 수행됩니다.\n\n1. `include/core/concurrency/pipeline.hpp` 파일이 구현 단계에서 명시된 내용으로 생성되었는지 확인합니다.\n2. 전체 프로젝트 또는 이 헤더에 의존하게 될 컴포넌트의 빌드를 트리거합니다.\n\n```bash\n# CMake 기반 프로젝트의 예시 명령어\ncmake --build ./build\n```\n\n### 4.2. 예상 결과\n\n- 빌드 명령은 `include/core/concurrency/pipeline.hpp`와 관련된 컴파일 오류 없이 성공적으로 완료되어야 합니다.\n- 이는 헤더 파일이 구문적으로 올바르고 모든 의존성(예: `thread_pool.hpp`, `pipeline/node.hpp`)이 올바르게 포함되었음을 확인합니다.\n- 전체 기능 검증은 `pipeline.cpp` 소스 파일과 해당 단위 테스트를 구현하는 후속 작업에서 수행될 것입니다.","`Pipeline` 클래스 정의와 노드 추가 및 실행 주기 실행을 위한 메서드가 포함된 헤더 파일",[2114,2117,2119,2121,2123,2125],{"_24":2115,"_83":39,"_84":2116,"_85":61},"`Pipeline` 클래스 정의",25,{"_24":2118,"_83":39,"_84":2116,"_85":88},"`AddNodeError` 열거형",{"_24":2120,"_83":39,"_84":2116,"_85":91},"`ThreadPool`을 받는 생성자 선언",{"_24":2122,"_83":39,"_84":2116,"_85":94},"`AddNode` 메서드 선언",{"_24":2124,"_83":39,"_84":2116,"_85":97},"`RunCycle` 및 `IsKilled` 메서드 선언",{"_24":2126,"_83":39,"_84":2116,"_85":176},"비공개 `ScheduleNextNode` 메서드 선언","노드의 시퀀스를 관리하기 위한 `core::concurrency::Pipeline` 클래스 인터페이스를 정의",{"_22":2129,"_24":2130,"_75":2131,"_77":2132,"_79":2133,"_51":2143,"_42":99},"task-1751726973861","파이프라인 노드 관리 및 실행 주기 구현","# 작업: 파이프라인 노드 관리 및 실행 사이클 구현\n\n> **에픽**: 비동기 데이터 파이프라인 오케스트레이터\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: `Pipeline`에 노드를 추가하고 처리 사이클을 시작하는 핵심 로직을 구현합니다.\n- **이론적 근거**: 이 작업은 데이터 파이프라인을 구성하고 운영하기 위한 기본 메커니즘을 구축합니다. `AddNode` 메서드는 순차적인 노드 간의 타입-세이프(type-safe) 연결을 강제하여 파이프라인의 구조적 무결성을 보장합니다. `RunCycle` 메서드는 비동기 실행을 위한 진입점을 제공하며, `ThreadPool`을 활용하여 데이터 처리를 시작합니다. 이는 오케스트레이터 구성 요소로서 `Pipeline`의 핵심적인 역할입니다.\n\n### 1.2. 결과물\n- **예상 결과**: 파이프라인의 상태를 관리하고 실행을 시작하는 `AddNode` 및 `RunCycle` 메서드가 정상적으로 기능해야 합니다.\n- **사양**:\n - **구현 클래스**: `core::concurrency::Pipeline`\n - **메서드 시그니처**:\n - `auto AddNode(pipeline::Node&& node) -> std::optional`\n - `void RunCycle()`\n - `auto IsKilled() const -> bool`\n- **결과 파일 구조**\n```bash\n# ./\n# └── source/\n# └── concurrency/\n# └── pipeline.cpp <-- 수정됨\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 노드를 추가하고 처리 사이클을 시작하는 로직을 보여줍니다. `AddNode`는 유효성 검사를 포함하며, `RunCycle`은 비동기 작업 스케줄링을 시작합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"AddNode 로직\"\n A[\"AddNode(node) 시작\"] --> B{\"파이프라인이 비어있나요?\"};\n B -- 예 --> C{노드 입력이 `void`인가요?};\n C -- 예 --> D[노드를 벡터에 추가];\n C -- 아니요 --> E[kFirstNodeNotProducer 오류 반환];\n B -- 아니요 --> F{노드 입력 타입이
이전 노드 출력 타입과 일치하나요?};\n F -- 예 --> D;\n F -- 아니요 --> G[kTypeMismatch 오류 반환];\n D --> H[std::nullopt 반환];\n end\n\n subgraph \"RunCycle 로직\"\n I[\"RunCycle() 시작\"] --> J{파이프라인이 종료되었나요?};\n J -- 예 --> K[즉시 반환];\n J -- 아니요 --> L{파이프라인이 비어있나요?};\n L -- 예 --> K;\n L -- 아니요 --> M[\"첫 번째 노드(인덱스 0)를
ThreadPool에 스케줄링\"];\n M --> N[종료];\n end\n```\n\n### 1.3. 인수 기준\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이것은 상위 수준의 체크리스트입니다. 각 항목에 대한 상세 구현은 섹션 3에 있습니다.\n\n- [ ] 타입 불일치 검사를 포함한 `AddNode` 구현\n- [ ] 첫 번째 노드가 프로듀서(producer)인지 확인하는 로직 구현\n- [ ] 종료 상태를 확인하고 첫 번째 노드를 스케줄링하는 `RunCycle` 구현\n- [ ] `IsKilled` getter 구현\n\n## 2. 기술적 맥락\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 구성 요소**:\n - **`Pipeline`**: 이 작업에서 구현되는 기본 구성 요소입니다. 선형적인 `Node` 시퀀스를 오케스트레이션하는 역할을 합니다. 이 작업에서는 핵심적인 노드 관리 및 실행 시작 로직을 구현합니다.\n - **`pipeline::Node`**: 타입-소거(type-erased)된 처리 단계입니다. `Pipeline::AddNode` 메서드는 `Node` 객체를 받아 `GetInputType()` 및 `GetOutputType()`을 사용하여 입/출력 타입을 검사하고 내부 컬렉션에 저장합니다.\n - **`ThreadPool`**: 기본적인 동시성 엔진입니다. `Pipeline::RunCycle` 메서드는 첫 번째 `Node`의 실행 작업을 공유 `ThreadPool`에 인큐(enqueue)하여 파이프라인 실행을 시작합니다.\n\n### 2.2. 영향을 받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `source/concurrency/pipeline.cpp`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **인수 기준**의 항목에 해당합니다. 각 `단계`는 여러 개의 세부 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 타입 불일치 검사를 포함한 `AddNode` 구현\n\n#### 1. `AddNode` 타입 불일치 유효성 검사 구현\n\n이 작업은 `AddNode` 메서드 내에서 새 노드의 입력 타입이 현재 파이프라인의 마지막 노드의 출력 타입과 일치하는지 확인하는 로직을 구현합니다. 이는 한 노드에서 다음 노드로 데이터가 올바르게 흐르도록 보장하고, 실행 중 `std::bad_any_cast` 예외를 방지하는 중요한 런타임 검사입니다. 타입이 일치하지 않으면 이 메서드는 `Pipeline::AddNodeError::kTypeMismatch`를 반환합니다. 이 로직은 파이프라인이 비어 있지 않을 때만 실행됩니다.\n\n**파일**: `source/concurrency/pipeline.cpp`\n\n```cpp\nauto Pipeline::AddNode(pipeline::Node&& node)\n -> std::optional {\n if (!nodes_.empty()) {\n if (nodes_.back().GetOutputType() != node.GetInputType()) {\n return Pipeline::AddNodeError::kTypeMismatch;\n }\n } else {\n // ... logic for first node\n }\n\n nodes_.push_back(std::move(node));\n return std::nullopt;\n}\n```\n\n---\n\n### 단계 2: 첫 번째 노드가 프로듀서(producer)인지 확인하는 로직 구현\n\n#### 1. 첫 번째 노드 프로듀서 유효성 검사 구현\n\n이 작업은 빈 파이프라인에 추가되는 첫 번째 노드가 \"프로듀서\" 노드인지 확인하는 로직을 구현합니다. 프로듀서 노드는 입력 타입이 `void`인 노드로 정의되며, 파이프라인의 초기 데이터를 생성합니다. 이 검사는 시작할 수 없는 잘못된 파이프라인의 생성을 방지합니다. 검사는 `AddNode` 메서드 내에서 수행되며, 실패할 경우 `Pipeline::AddNodeError::kFirstNodeNotProducer`가 반환됩니다.\n\n**파일**: `source/concurrency/pipeline.cpp`\n\n```cpp\nauto Pipeline::AddNode(pipeline::Node&& node)\n -> std::optional {\n if (!nodes_.empty()) {\n // ... logic for type mismatch\n } else {\n if (node.GetInputType() != typeid(void)) {\n return Pipeline::AddNodeError::kFirstNodeNotProducer;\n }\n }\n\n nodes_.push_back(std::move(node));\n return std::nullopt;\n}\n```\n\n---\n\n### 단계 3: 종료 상태를 확인하고 첫 번째 노드를 스케줄링하는 `RunCycle` 구현\n\n#### 1. `RunCycle` 실행 진입점 구현\n\n이 작업은 공개(public) `RunCycle` 메서드를 구현합니다. 이 메서드의 목적은 파이프라인의 단일 실행 패스를 시작하는 것입니다. 먼저 `is_killed_` 원자적(atomic) 플래그를 스레드-세이프하게 확인합니다. 만약 true이면 추가 처리를 막기 위해 즉시 반환합니다. 파이프라인이 종료되지 않았고 하나 이상의 노드를 포함하고 있다면, 비공개(private) 헬퍼 함수 `ScheduleNextNode`를 호출하여 인덱스 `0`과 빈 `std::any`를 전달합니다. 이를 통해 `ThreadPool`에서 첫 번째 노드의 비동기 실행이 시작됩니다.\n\n**파일**: `source/concurrency/pipeline.cpp`\n\n```cpp\nvoid Pipeline::RunCycle() {\n if (is_killed_.load()) {\n return;\n }\n if (!nodes_.empty()) {\n ScheduleNextNode(0, {});\n }\n}\n```\n\n---\n\n### 단계 4: `IsKilled` getter 구현\n\n#### 1. `IsKilled` 공개 Getter 구현\n\n이 작업은 `IsKilled` 메서드를 구현합니다. 이 메서드는 외부 컴포넌트가 파이프라인의 상태를 스레드-세이프하게 조회할 수 있도록 하는 `const` getter입니다. `is_killed_` 원자적 불리언(atomic boolean)의 값을 `load()`를 사용하여 읽어 스레드 간의 가시성을 보장하고 그 결과를 반환합니다. 이를 통해 `Scheduler`와 같은 호출자는 파이프라인이 종료되어 더 이상 실행해서는 안 되는지 판단할 수 있습니다.\n\n**파일**: `source/concurrency/pipeline.cpp`\n\n```cpp\nauto Pipeline::IsKilled() const -> bool { return is_killed_.load(); }\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n- `AddNode`와 `RunCycle`의 로직을 검증하기 위해 `tests/unit/pipeline_management.cpp`에 유닛 테스트를 생성해야 합니다. 개발자는 프레임워크를 컴파일하고 이 테스트를 실행해야 합니다.\n\n```bash\n# 1. 빌드 디렉토리로 이동합니다.\ncd build/\n\n# 2. 프로젝트와 테스트를 컴파일합니다.\ncmake ..\nmake\n\n# 3. 파이프라인 관리 로직에 대한 유닛 테스트를 실행합니다.\n./tests/unit/pipeline_management_test\n```\n\n### 4.2. 예상 결과\n\n- 테스트 실행 파일은 상태 코드 0으로 실행되고 종료되어야 합니다. 출력은 모든 테스트 케이스(예: 성공적인 노드 추가, 타입 불일치 오류, 첫 노드 프로듀서 오류)가 통과되었음을 나타내야 합니다.\n\n```\n[==========] Running 3 tests from 1 test suite.\n[----------] Global test environment set-up.\n[----------] 3 tests from PipelineManagementTest\n[ RUN ] PipelineManagementTest.AddNodeSuccess\n[ OK ] PipelineManagementTest.AddNodeSuccess (0 ms)\n[ RUN ] PipelineManagementTest.AddNodeFailsOnTypeMismatch\n[ OK ] PipelineManagementTest.AddNodeFailsOnTypeMismatch (0 ms)\n[ RUN ] PipelineManagementTest.AddNodeFailsIfFirstNodeIsNotProducer\n[ OK ] PipelineManagementTest.AddNodeFailsIfFirstNodeIsNotProducer (0 ms)\n[----------] 3 tests from PipelineManagementTest (0 ms total)\n\n[----------] Global test environment tear-down\n[==========] 3 tests from 1 test suite ran. (0 ms total)\n[ PASSED ] 3 tests.\n```","파이프라인의 상태를 관리하고 실행을 시작하는 기능적인 `AddNode` 및 `RunCycle` 메서드",[2134,2137,2139,2141],{"_24":2135,"_83":39,"_84":2136,"_85":61},"타입 불일치 검사를 포함한 `AddNode` 구현",26,{"_24":2138,"_83":39,"_84":2136,"_85":88},"첫 번째 노드가 생산자인지 확인하는 로직",{"_24":2140,"_83":39,"_84":2136,"_85":91},"killed 상태를 확인하고 첫 번째 노드를 스케줄링하는 `RunCycle` 구현",{"_24":2142,"_83":39,"_84":2136,"_85":94},"`IsKilled` getter 구현","노드를 추가하고 처리 주기를 시작하는 `Pipeline`의 핵심 로직을 구현",{"_22":2145,"_24":2146,"_75":2147,"_77":2148,"_79":2149,"_51":2163,"_42":99},"task-1751727020014","비동기 노드 스케줄링 구현","# 작업: 비동기 노드 스케줄링 구현\n\n> **에픽**: 비동기 데이터 파이프라인 오케스트레이터\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: `ScheduleNextNode` 메서드를 구현하여 파이프라인에서 노드의 비동기적, 순차적 실행을 조율합니다.\n- **근거**: 이 메서드는 `Pipeline` 컴포넌트의 핵심 실행 로직을 형성합니다. 선형 시퀀스로 구성된 `pipeline::Node` 객체들을 `ThreadPool`에서 순서대로 스케줄링하는 역할을 담당합니다. 노드 간 데이터 전달을 관리하고, 각 노드가 반환하는 `ControlFlow` 신호를 존중하여, 단순하고 순차적인 정의로부터 복잡한 비동기 워크플로를 가능하게 합니다. 이 메커니즘은 복잡한 비동기 데이터 처리 파이프라인을 구현한다는 프로젝트의 핵심 목표를 직접적으로 충족시킵니다.\n\n### 1.2. 결과물\n- **예상 결과**: 스레드 풀에 노드 실행 작업을 큐에 추가하고 노드 간에 데이터를 전달하는 재귀적 스케줄링 메서드.\n- **사양**:\n - **메서드 시그니처**: `void Pipeline::ScheduleNextNode(std::uint32_t node_index, std::any input)`\n - **동작**: 이 메서드는 단일 노드의 실행을 캡슐화하는 람다 함수를 생성해야 합니다. 이 작업은 `ThreadPool`에 제출됩니다. 노드가 완료되면 `NodeResult`를 검사합니다. 만약 `ControlFlow`가 `kContinue`이면, 메서드는 재귀적으로 자신을 호출하여 시퀀스의 다음 노드를 스케줄링합니다.\n- **결과 파일 구조**\n```bash\n# ./\n# └── source/\n# └── concurrency/\n# └── pipeline.cpp <-- 수정됨\n```\n\n- **프로세스 흐름 다이어그램**\n 이 다이어그램은 단일 `ScheduleNextNode` 호출 내의 로직과 그 재귀적 특성을 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n A[\"ScheduleNextNode(node_index, input_data)\"] --> B{node_index가 유효한가?};\n B -- 아니오 --> Z[파이프라인 사이클 종료];\n B -- 예 --> C[작업 람다 생성];\n C --> D[ThreadPool에 작업 추가];\n\n subgraph \"워커 스레드 실행\"\n direction LR\n E[작업 람다 실행] --> F[\"current_node.Execute(input_data)\"];\n F --> G[\"NodeResult (데이터, 제어 흐름) 가져오기\"];\n G --> H{제어 흐름 분기};\n H -- kContinue --> I[\"ScheduleNextNode(node_index + 1, result.data)\"];\n H -- kSkip / kKill --> J[체인 중지];\n end\n \n D -.-> E;\n I -.-> A;\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 섹션 3에 기술되어 있습니다.\n\n- [ ] `ScheduleNextNode` 메서드 구현\n- [ ] 큐에 추가될 람다 `job` 생성\n- [ ] 작업 내에서 현재 노드 실행\n- [ ] `NodeResult` 및 `ControlFlow` 처리\n- [ ] `kContinue` 시 다음 노드를 위한 `ScheduleNextNode` 재귀 호출\n- [ ] 스레드 풀에 작업 제출\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - **`Pipeline`**: 구현 대상인 오케스트레이터 컴포넌트. 이 작업은 실행 로직의 핵심인 비공개 메서드 `ScheduleNextNode`에 중점을 둡니다.\n - **`ThreadPool`**: 기본적인 동시성 엔진. `ScheduleNextNode`는 스레드 풀의 `EnqueueJob` 메서드를 사용하여 노드의 실제 실행을 워커 스레드에 위임합니다.\n - **`pipeline::Node`**: 개별 처리 단위. `ScheduleNextNode`는 현재 노드의 `Execute` 메서드를 호출하여 작업을 수행합니다.\n - **`pipeline::NodeResult` / `pipeline::ControlFlow`**: 노드 간의 통신 프로토콜 역할을 하는 데이터 구조. `ScheduleNextNode` 메서드는 `NodeResult`의 `ControlFlow` 열거형을 검사하여 파이프라인을 계속 진행할지, 건너뛸지, 또는 전체 실행을 중단할지 결정합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `source/concurrency/pipeline.cpp`\n\n## 3. 구현 사양\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 서술적 설명('무엇을', '왜'), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: `ScheduleNextNode` 메서드 구현\n\n이 단일 단계는 하나의 일관된 함수를 구현하는 과정에 모든 완료 조건이 포함되므로 모든 조건을 포괄합니다. 다음 액션들은 `ScheduleNextNode` 메서드 본문의 구성을 상세히 설명합니다.\n\n#### 1. 메서드 및 비동기 작업 람다 정의\n\n**액션:** `ScheduleNextNode` 메서드의 본문을 구현합니다. 이 구현의 핵심은 단일 파이프라인 노드를 실행하는 데 필요한 상태를 캡처하는 C++ 람다 함수입니다. `current_node`를 **값으로** 캡처하는 것이 매우 중요합니다. 참조(`auto&`)로 캡처하면 댕글링 참조가 발생할 수 있습니다. 람다는 나중에 다른 스레드에서 비동기적으로 실행되는데, 이때 `ScheduleNextNode`의 스택 프레임에 있던 원본 참조는 이미 유효하지 않게 되기 때문입니다. 값으로 캡처하면 람다가 실행할 노드의 안전하고 독립적인 복사본을 갖게 됩니다.\n\n**파일**: `source/concurrency/pipeline.cpp`\n\n```cpp\nvoid Pipeline::ScheduleNextNode(std::uint32_t node_index, std::any input) {\n if (node_index >= nodes_.size() || is_killed_.load()) {\n return;\n }\n\n // Action 1: 워커 스레드에서 use-after-free를 방지하기 위해 노드를 값으로 캡처합니다.\n auto current_node = nodes_[node_index];\n\n auto job = [this, node_index, current_node,\n prev_input = std::move(input)]() mutable {\n try {\n // Action 2: 노드의 로직을 실행합니다.\n using core::concurrency::pipeline::ControlFlow;\n auto result = current_node.Execute(prev_input);\n\n // Action 3: 제어 흐름 신호를 처리합니다.\n switch (result.control) {\n case ControlFlow::kContinue:\n // Action 4: 체인의 다음 노드를 재귀적으로 스케줄링합니다.\n ScheduleNextNode(node_index + 1, std::move(result.data));\n return;\n case ControlFlow::kSkip:\n // 체인은 의도적으로 중지되지만, 파이프라인 전체가 종료되는 것은 아닙니다.\n return;\n case ControlFlow::kKill:\n // 전체 파이프라인에 더 이상의 사이클 처리를 중지하라는 신호를 보냅니다.\n is_killed_ = true;\n return;\n }\n\n } catch (const std::bad_any_cast& e) {\n // 하나의 노드 실패로 전체 애플리케이션이 중단되는 것을 막기 위해 오류는 의도적으로 무시됩니다.\n // 실제 운영 시스템에서는 이 부분을 견고한 오류 로깅으로 대체해야 합니다.\n } catch (const std::exception& e) {\n // 같은 이유로 일반적인 예외도 무시합니다.\n }\n };\n\n // Action 5: 실행을 위해 스레드 풀에 작업을 제출합니다.\n thread_pool_->EnqueueJob(std::move(job));\n}\n```\n\n#### 2. 노드 실행 및 제어 흐름 로직 구현\n\n**액션:** 람다 내에서 값으로 복사된 `current_node`의 `Execute` 메서드를 호출합니다. 반환된 `NodeResult`는 출력 데이터와 `ControlFlow` 신호를 모두 포함합니다. `switch` 문은 이러한 신호를 처리하는 가장 깔끔한 방법입니다. `kContinue`의 경우, `ScheduleNextNode`를 재귀적으로 호출하여 다음 작업을 연결합니다. `kKill`의 경우, 원자적(atomic) `is_killed_` 플래그를 설정하여 모든 향후 파이프라인 작업을 종료합니다. `kSkip`의 경우, 람다는 단순히 반환하여 파이프라인을 종료하지 않고 현재 사이클의 실행 체인만 종료합니다. 전체 실행은 `try-catch` 블록으로 감싸져 있어 결함이 있는 노드가 전체 워커 스레드를 중단시키지 않도록 보장합니다.\n\n#### 3. 작업 큐에 추가\n\n**액션:** 작업 람다가 완전히 정의된 후, `EnqueueJob` 메서드를 통해 공유 `ThreadPool`에 전달합니다. 이 액션은 작업 단위를 `Pipeline` 오케스트레이터에서 `ThreadPool` 실행기로 넘겨주어 원하는 비동기 동작을 달성합니다. `std::move`의 사용은 람다의 소유권을 스레드 풀의 큐로 효율적으로 이전하기 위한 최적화입니다.\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 단계\n\n구현은 프로젝트를 컴파일하고 `Pipeline` 컴포넌트에 대한 유닛 테스트를 실행하여 검증해야 합니다. 이 테스트들은 노드가 순서대로 실행되고, 데이터가 올바르게 전달되며, 제어 흐름 신호가 예상대로 처리되는지를 검증합니다.\n\n```bash\n# 1. 프로젝트의 빌드 디렉터리로 이동합니다. 없다면 생성하세요.\n# 예시:\nmkdir -p build && cd build\n\n# 2. CMake로 프로젝트를 구성합니다\ncmake ..\n\n# 3. 테스트를 포함하여 프로젝트를 빌드합니다. 이 과정에서\n# pipeline.cpp의 변경 사항이 컴파일됩니다.\ncmake --build .\n\n# 4. Pipeline 테스트가 포함된 유닛 테스트 바이너리를 실행합니다.\n# 정확한 이름은 테스트 프레임워크 구성에 따라 다를 수 있습니다.\n./tests/unit/pipeline_test\n```\n\n### 4.2. 예상 결과\n\n검증이 성공하면 모든 `Pipeline` 관련 테스트가 통과합니다. 테스트 실행 결과 출력은 순차적 실행, 데이터 전파, 제어 흐름 처리(`kContinue`, `kSkip`, `kKill`)를 다루는 테스트에 대해 \"OK\" 또는 \"PASSED\"를 표시해야 합니다.\n\n```\n[==========] 1개의 테스트 스위트에서 테스트를 실행합니다.\n[----------] 전역 테스트 환경 설정.\n[----------] PipelineTest의 테스트 4개\n[ RUN ] PipelineTest.ExecutesNodesSequentiallyAndPassesData\n[ OK ] PipelineTest.ExecutesNodesSequentiallyAndPassesData (5 ms)\n[ RUN ] PipelineTest.StopsExecutionOnControlFlowSkip\n[ OK ] PipelineTest.StopsExecutionOnControlFlowSkip (2 ms)\n[ RUN ] PipelineTest.KillsPipelineOnControlFlowKill\n[ OK ] PipelineTest.KillsPipelineOnControlFlowKill (3 ms)\n[ RUN ] PipelineTest.HandlesFirstNodeNotProducerError\n[ OK ] PipelineTest.HandlesFirstNodeNotProducerError (0 ms)\n[----------] PipelineTest의 테스트 4개 (총 10ms)\n\n[----------] 전역 테스트 환경 해제\n[==========] 1개의 테스트 스위트에서 4개의 테스트 실행 완료. (총 10ms)\n[ PASSED ] 테스트 4개.\n```","스레드 풀에 노드 실행 작업을 큐에 넣고 그들 사이에 데이터를 전달하는 재귀적인 스케줄링 메서드",[2150,2153,2155,2157,2159,2161],{"_24":2151,"_83":39,"_84":2152,"_85":61},"`ScheduleNextNode` 메서드 구현",27,{"_24":2154,"_83":39,"_84":2152,"_85":88},"큐에 넣을 람다 `job` 생성",{"_24":2156,"_83":39,"_84":2152,"_85":91},"작업 내에서 현재 노드 실행",{"_24":2158,"_83":39,"_84":2152,"_85":94},"`NodeResult` 및 `ControlFlow` 처리",{"_24":2160,"_83":39,"_84":2152,"_85":97},"`kContinue` 시 다음 노드에 대한 `ScheduleNextNode` 재귀 호출",{"_24":2162,"_83":39,"_84":2152,"_85":176},"스레드 풀에 작업 제출","파이프라인에서 노드의 비동기적, 순차적 실행을 조율하는 `ScheduleNextNode` 메서드를 구현",{"_22":2165,"_24":2166,"_75":2167,"_77":2168,"_79":2169,"_51":2177,"_42":99},"task-1751727064040","파일시스템 및 설정 유틸리티 유닛 테스트","# 작업: 파일시스템 및 설정 유틸리티 유닛 테스트\n\n> **에픽**: 포괄적인 시스템 검증\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: 핵심 파일시스템(`Path`, `File`) 및 설정(`Reader`) 유틸리티를 격리된 유닛 테스트를 통해 검증합니다.\n- **근거**: 이러한 기본 유틸리티는 프레임워크 내 거의 모든 상위 컴포넌트(예: `Logger`, `Pipeline`)의 핵심 의존성입니다. 격리된 유닛 테스트를 통해 정확성, 견고성, 예측 가능한 동작을 보장하는 것은 전체 시스템 안정성에 필수적입니다. 이 테스트들은 회귀(regression)를 방지하고 아키텍처의 기본 계층이 신뢰할 수 있음을 보장합니다.\n\n### 1.2. 결과물\n- **예상 결과**: 경로 조작, 파일 I/O, YAML 파싱의 정확성을 확인하는 유닛 테스트 스위트.\n- **사양**:\n - Catch2 테스트 프레임워크를 사용하여 구현된 테스트 스위트.\n - `core::filesystem::Path`: 테스트는 생성, 문자열 변환, 결합(`operator/`), 컴포넌트 추출(`GetFilename`, `GetExtension`)을 엣지 케이스를 포함하여 검증해야 합니다.\n - `core::filesystem::File`: 테스트는 존재 확인(`Exists`), 읽기/쓰기 작업(`Read`, `Write`), 덮어쓰기 동작, 그리고 우아한 실패 처리(예: 디렉토리에 쓰기 시도)를 검증해야 합니다.\n - `core::config::Reader`: 테스트는 정적 팩토리 `LoadFromFile`의 성공 및 실패 케이스(파일 없음, 유효하지 않은 YAML), 값 읽기(`Read`), 하위 노드 추출(`GetNode`), 그리고 올바른 이동 시맨틱(move semantics)을 검증해야 합니다.\n- **결과 파일 구조**\n```bash\n# ./\n# └── tests/\n# └── unit/\n# ├── config/\n# │ └── reader.cpp <-- 신규\n# └── filesystem/\n# ├── file.cpp <-- 신규\n# └── path.cpp <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 지정된 컴포넌트들의 유닛 테스트를 실행하고 검증하는 워크플로우를 보여줍니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n Dev[\"개발자\"] -- \"빌드 및 테스트 실행\" --> CTest[\"테스트 러너 (ctest)\"];\n CTest -- \"실행\" --> PathTests[\"Path 유닛 테스트
(path.cpp)\"];\n CTest -- \"실행\" --> FileTests[\"File 유닛 테스트
(file.cpp)\"];\n CTest -- \"실행\" --> ReaderTests[\"Reader 유닛 테스트
(reader.cpp)\"];\n PathTests --> Report[\"테스트 보고서\"];\n FileTests --> Report[\"테스트 보고서\"];\n ReaderTests --> Report[\"테스트 보고서\"];\n Report -- \"성공/실패 상태\" --> Dev;\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 자세한 구현은 3절에 있습니다.\n\n- [ ] Path 클래스의 생성, 결합, 컴포넌트 추출에 대한 유닛 테스트.\n- [ ] File 클래스의 존재 확인, 읽기/쓰기, 엣지 케이스에 대한 유닛 테스트.\n- [ ] Config Reader의 파일 로딩, 오류 처리, 값 읽기, 이동 시맨틱에 대한 유닛 테스트.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - **`core::filesystem::Path`**: 파일시스템 경로 조작을 추상화하는 기본 유틸리티 클래스입니다. 이 작업은 파일 작업을 수행하는 모든 컴포넌트가 경로를 안정적으로 구성할 수 있도록 핵심 로직을 검증합니다.\n - **`core::filesystem::File`**: 파일 I/O를 수행하는 유틸리티입니다. 이 작업은 `Logger`(파일 싱크용) 및 `config::Reader`와 같은 컴포넌트에서 사용하는 읽기/쓰기 및 존재 확인 로직을 검증합니다.\n - **`core::config::Reader`**: YAML 파일에서 시스템 설정을 로드하고 파싱하는 역할을 담당하는 컴포넌트입니다. 이 작업은 파일을 올바르게 로드하고, 오류를 처리하며, 설정 값에 대한 접근을 제공하는 능력을 검증하며, 이는 시스템 초기화에 매우 중요합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `tests/unit/filesystem/path.cpp`\n- `tests/unit/filesystem/file.cpp`\n- `tests/unit/config/reader.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 여러 세부적인 `작업`으로 나뉩니다. 각 `작업`에 대해 제목, 명확한 서술적 설명('무엇'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 1단계: Path 클래스의 생성, 결합, 컴포넌트 추출에 대한 유닛 테스트.\n\n#### 1. Path 생성 및 결합 검증\n\n이 작업은 `Path` 객체가 표준 문자열로부터 올바르게 초기화될 수 있고, `operator/`를 사용하여 경로 세그먼트들이 결합될 수 있음을 확인합니다. 이는 프로그래밍 방식으로 파일 경로를 구성하는 데 필요한 가장 기본적인 기능입니다. 테스트는 두 경로 결합, 빈 경로와의 결합, 그리고 후행 슬래시를 올바르게 처리하는 경우를 다룹니다.\n\n**파일**: `tests/unit/filesystem/path.cpp`\n\n```cpp\n#include \"core/filesystem/path.hpp\"\n#include \n#include \"catch2/catch_test_macros.hpp\"\n\nTEST_CASE(\"Path should be constructible from a string\", \"[core][filesystem][path]\") {\n // Arrange\n const std::string PathString = \"/usr/local/bin\";\n\n // Act\n const core::filesystem::Path Path(PathString);\n\n // Assert\n REQUIRE(Path.ConvertToString() == PathString);\n}\n\nTEST_CASE(\"Path concatenation should correctly join paths\", \"[core][filesystem][path]\") {\n // Arrange\n const core::filesystem::Path BasePath(\"/home/user\");\n const core::filesystem::Path DataDir(\"data\");\n const core::filesystem::Path BasePathWithSlash(\"/home/user/\");\n const core::filesystem::Path EmptyPath(\"\");\n\n // Act\n const core::filesystem::Path Result1 = BasePath / DataDir;\n const core::filesystem::Path Result2 = BasePath / EmptyPath;\n const core::filesystem::Path Result3 = BasePathWithSlash / DataDir;\n\n // Assert\n REQUIRE(Result1.ConvertToString() == \"/home/user/data\");\n REQUIRE(Result2.ConvertToString() == \"/home/user/\");\n REQUIRE(Result3.ConvertToString() == \"/home/user/data\");\n}\n```\n\n#### 2. 컴포넌트 추출 메서드 검증\n\n이 작업은 `GetFilename` 및 `GetExtension` 메서드를 검증합니다. 이들은 파일을 처리할 때 흔히 요구되는 특정 컴포넌트를 검색하기 위해 경로를 파싱하는 데 필수적입니다. 테스트는 확장자가 있거나 없는 경로, 도트 파일, 슬래시로 끝나는 경로 등 다양한 시나리오를 다룹니다.\n\n**파일**: `tests/unit/filesystem/path.cpp`\n\n```cpp\n// ...\nTEST_CASE(\"GetFilename should extract the correct filename\", \"[core][filesystem][path]\") {\n // Arrange\n const core::filesystem::Path FilePath(\"/path/to/some/file.txt\");\n const core::filesystem::Path DirPath(\"/path/to/some/directory/\");\n const core::filesystem::Path RootPath(\"/\");\n const core::filesystem::Path JustFilename(\"file.txt\");\n const core::filesystem::Path EmptyPath(\"\");\n\n // Act & Assert\n REQUIRE(FilePath.GetFilename().ConvertToString() == \"file.txt\");\n REQUIRE(DirPath.GetFilename().ConvertToString().empty());\n REQUIRE(RootPath.GetFilename().ConvertToString().empty());\n REQUIRE(JustFilename.GetFilename().ConvertToString() == \"file.txt\");\n REQUIRE(EmptyPath.GetFilename().ConvertToString().empty());\n}\n\nTEST_CASE(\"GetExtension should extract the correct extension\", \"[core][filesystem][path]\") {\n // Arrange\n const core::filesystem::Path PathWithDoubleExtension(\n \"/path/to/archive.tar.gz\");\n const core::filesystem::Path PathWithoutExtension(\"file_without_extension\");\n const core::filesystem::Path Dotfile(\".dotfile\");\n const core::filesystem::Path FileWithDotInName(\"my.document.txt\");\n\n // Act & Assert\n REQUIRE(PathWithDoubleExtension.GetExtension() == \".gz\");\n REQUIRE(PathWithoutExtension.GetExtension().empty());\n REQUIRE(Dotfile.GetExtension().empty());\n REQUIRE(FileWithDotInName.GetExtension() == \".txt\");\n}\n```\n\n#### 3. 엣지 케이스 처리 검증\n\n이 작업은 비표준이지만 유효한 입력에 대한 동작을 테스트하여 `Path` 클래스의 견고성을 보장합니다. 여기에는 `.` 및 `..`와 같은 특수 디렉토리 이름, 점으로 끝나는 파일 이름, 그리고 기본 경로를 대체해야 하는 절대 경로 결합이 포함됩니다. 이는 기반이 되는 `std::filesystem`에 대한 래퍼의 정확성에 대한 신뢰를 구축합니다.\n\n**파일**: `tests/unit/filesystem/path.cpp`\n\n```cpp\n// ...\nTEST_CASE(\"Path should handle edge cases for filesystem components\",\n \"[core][filesystem][path]\") {\n SECTION(\"GetFilename should handle special directory names\") {\n // ...\n const core::filesystem::Path CurrentDir(\".\");\n const core::filesystem::Path ParentDir(\"..\");\n REQUIRE(CurrentDir.GetFilename().ConvertToString() == \".\");\n REQUIRE(ParentDir.GetFilename().ConvertToString() == \"..\");\n }\n\n SECTION(\"GetExtension should handle filenames ending with a dot\") {\n // ...\n const core::filesystem::Path FileEndingWithDot(\"file.\");\n REQUIRE(FileEndingWithDot.GetExtension() == \".\");\n }\n\n SECTION(\"Operator/ should handle absolute paths correctly\") {\n // ...\n const core::filesystem::Path Base(\"/base/dir\");\n const core::filesystem::Path AbsoluteAppend(\"/abs/path\");\n const auto Result = Base / AbsoluteAppend;\n REQUIRE(Result.ConvertToString() == \"/abs/path\");\n }\n}\n```\n\n---\n\n### 2단계: File 클래스의 존재 확인, 읽기/쓰기, 엣지 케이스에 대한 유닛 테스트.\n\n#### 1. 임시 파일 픽스처 구현\n\n이 작업은 임시 파일을 관리하기 위한 테스트 픽스처를 정의합니다. 픽스처(생성자/소멸자로 설정/해체 로직을 갖는 클래스)를 사용하면 각 테스트 케이스가 깨끗하고 격리된 환경에서 실행되도록 보장합니다. 픽스처는 테스트를 위해 고유한 이름의 파일을 생성하고 이후 삭제를 보장하여 테스트 오염과 파일시스템 혼란을 방지합니다.\n\n**파일**: `tests/unit/filesystem/file.cpp`\n\n```cpp\n#include \"core/filesystem/file.hpp\"\n#include \n#include \n#include \n#include \"catch2/catch_test_macros.hpp\"\n#include \"core/filesystem/path.hpp\"\n\n// A test fixture for managing a temporary file.\nstruct TemporaryFileFixture {\n const std::string TempFilename;\n const core::filesystem::Path Path;\n\n TemporaryFileFixture()\n : TempFilename(\"temp_test_file_\" + std::to_string(rand()) + \".txt\"),\n Path(TempFilename) {}\n\n // Create a file with specified content.\n void CreateFileWithContent(const std::string& content) const {\n std::ofstream temp_file(TempFilename);\n temp_file << content;\n temp_file.close();\n }\n\n // Destructor handles teardown.\n ~TemporaryFileFixture() { std::remove(TempFilename.c_str()); }\n};\n```\n\n#### 2. 파일 존재 및 기본 I/O 검증\n\n이 작업은 `File` 클래스의 핵심 기능을 테스트합니다. `Exists()`가 파일 상태를 올바르게 보고하는지, 그리고 `Write()`와 `Read()`가 콘텐츠를 성공적으로 저장하고 검색할 수 있는지 검증합니다. I/O 작업이 견고한지 확인하기 위해 간단한 문자열, 기존 콘텐츠 덮어쓰기, 빈 콘텐츠 및 여러 줄 콘텐츠 처리를 다룹니다.\n\n**파일**: `tests/unit/filesystem/file.cpp`\n\n```cpp\n// ...\nTEST_CASE(\"File::Exists\", \"[core][filesystem][file]\") {\n const TemporaryFileFixture Fixture;\n const core::filesystem::File File(Fixture.Path);\n\n SECTION(\"Returns false for a non-existent file\") {\n REQUIRE_FALSE(File.Exists());\n }\n\n SECTION(\"Returns true for an existing file\") {\n Fixture.CreateFileWithContent(\"test data\");\n REQUIRE(File.Exists());\n }\n}\n\nTEST_CASE(\"File Read/Write Operations\", \"[core][filesystem][file]\") {\n const TemporaryFileFixture Fixture;\n core::filesystem::File file(Fixture.Path);\n\n SECTION(\"Read from non-existent file returns empty string\") {\n REQUIRE(file.Read().empty());\n }\n\n SECTION(\"Write and Read back simple content\") {\n const std::string ExpectedContent = \"Hello, world!\";\n REQUIRE(file.Write(ExpectedContent));\n REQUIRE(file.Read() == ExpectedContent);\n }\n\n SECTION(\"Write overwrites existing content\") {\n Fixture.CreateFileWithContent(\"initial content\");\n const std::string NewContent = \"new content\";\n REQUIRE(file.Write(NewContent));\n REQUIRE(file.Read() == NewContent);\n }\n // ...\n}\n```\n\n#### 3. 유효하지 않은 작업에 대한 우아한 실패 처리 검증\n\n이 작업은 `File` 클래스가 오용될 때 예측 가능하고 안전하게 동작하는지 확인합니다. 특히, 디렉토리(일반 파일이 아님)에 해당하는 경로에서 읽거나 쓰려고 시도할 때, 충돌이나 정의되지 않은 동작을 유발하는 대신 우아하게 실패하는지(쓰기의 경우 `false` 반환, 읽기의 경우 빈 문자열 반환) 테스트합니다. 이는 클라이언트 코드의 견고한 오류 처리에 매우 중요합니다.\n\n**파일**: `tests/unit/filesystem/file.cpp`\n\n```cpp\n// ...\n#include \n// ...\nstruct TemporaryDirectoryFixture {\n // ...\n TemporaryDirectoryFixture()\n : TempDirname(\"temp_test_dir_\" + std::to_string(rand())),\n Path(TempDirname) {\n std::filesystem::create_directory(TempDirname);\n }\n ~TemporaryDirectoryFixture() { std::filesystem::remove_all(TempDirname); }\n};\n\nTEST_CASE(\"File operations should handle failures gracefully\",\n \"[core][filesystem][file]\") {\n SECTION(\"Write should fail for a path that is a directory\") {\n const TemporaryDirectoryFixture Fixture;\n core::filesystem::File file(Fixture.Path);\n REQUIRE_FALSE(file.Write(\"some content\"));\n }\n\n SECTION(\"Read should fail for a path that is a directory\") {\n const TemporaryDirectoryFixture Fixture;\n core::filesystem::File file(Fixture.Path);\n REQUIRE(file.Read().empty());\n }\n}\n```\n\n---\n\n### 3단계: Config Reader의 파일 로딩, 오류 처리, 값 읽기, 이동 시맨틱에 대한 유닛 테스트.\n\n#### 1. 파일 로딩 및 오류 처리 검증\n\n이 작업은 `Reader` 클래스의 진입점인 정적 팩토리 `LoadFromFile`을 테스트합니다. 유효한 파일을 성공적으로 로드하는 경우, 존재하지 않는 파일(`kFileNotFound`) 및 형식이 잘못된 YAML 파일(`kInvalidYamlFormat`)에 대해 특정 오류 코드로 실패하는 경우 등 모든 결과를 올바르게 처리하는지 검증하는 것이 중요합니다. 이는 `Reader`가 명확하고 실행 가능한 오류 정보를 제공하도록 보장합니다.\n\n**파일**: `tests/unit/config/reader.cpp`\n\n```cpp\n#include \"core/config/reader.hpp\"\n// ... includes and fixture ...\n\nTEST_CASE(\"Reader File Loading\", \"[reader]\") {\n SECTION(\"Should report file not found for a non-existent file\") {\n const core::filesystem::Path NonExistentPath(\"non_existent_file.yaml\");\n const auto Reader = core::config::Reader::LoadFromFile(NonExistentPath);\n REQUIRE_FALSE(Reader);\n REQUIRE(Reader.GetError() == core::config::Reader::Error::kFileNotFound);\n }\n\n SECTION(\"Should report invalid format for a malformed YAML file\") {\n const TemporaryFileFixture Fixture;\n Fixture.CreateFileWithContent(\"key: value: another_value\"); // Invalid YAML\n const auto Reader = core::config::Reader::LoadFromFile(Fixture.Path);\n REQUIRE_FALSE(Reader);\n REQUIRE(Reader.GetError() == core::config::Reader::Error::kInvalidYamlFormat);\n }\n\n SECTION(\"Should load a valid YAML file successfully\") {\n const TemporaryFileFixture Fixture;\n Fixture.CreateFileWithContent(\"key: value\");\n const auto Reader = core::config::Reader::LoadFromFile(Fixture.Path);\n REQUIRE(Reader);\n REQUIRE(Reader.GetError() == core::config::Reader::Error::kSuccess);\n }\n}\n```\n\n#### 2. 값 및 하위 노드 읽기 검증\n\n이 작업은 `Reader`의 주요 목적인 설정 데이터 검색을 검증합니다. `Read()`가 점으로 구분된 키를 사용하여 예상 타입의 값을 올바르게 검색하는지 확인합니다. 또한 `GetNode()`가 YAML 문서의 일부 섹션으로 범위가 지정된 새롭고 유효한 `Reader`를 생성할 수 있는지 확인합니다. 존재하지 않는 키, 타입 불일치, 유효하지 않은 `Reader` 인스턴스에서 읽기 시도와 같은 실패 시나리오를 테스트하여 API의 안전성을 보장하는 것이 중요합니다.\n\n**파일**: `tests/unit/config/reader.cpp`\n\n```cpp\n// ...\nTEST_CASE(\"Reader Value and Node Reading\", \"[reader]\") {\n SECTION(\"Should read a string value from a valid key\") {\n // ...\n const auto Reader = core::config::Reader::LoadFromFile(Fixture.Path);\n REQUIRE(Reader);\n const auto Host = Reader.Read(\"database.host\");\n REQUIRE(Host.has_value());\n REQUIRE(*Host == \"localhost\");\n }\n\n SECTION(\"Should get a valid sub-node reader\") {\n // ...\n const auto Reader = core::config::Reader::LoadFromFile(Fixture.Path);\n REQUIRE(Reader);\n const auto DbNodeReader = Reader.GetNode(\"database\");\n REQUIRE(DbNodeReader);\n const auto Host = DbNodeReader.Read(\"host\");\n REQUIRE(Host.has_value());\n REQUIRE(*Host == \"localhost\");\n }\n\n SECTION(\"Should get an invalid sub-node reader for a non-existent key\") {\n // ...\n const auto InvalidNodeReader = Reader.GetNode(\"non_existent_node\");\n REQUIRE_FALSE(InvalidNodeReader);\n REQUIRE(InvalidNodeReader.GetError() == core::config::Reader::Error::kKeyNotFound);\n }\n\n // ... other failure cases\n}\n```\n\n#### 3. 이동 시맨틱 검증\n\n이 작업은 `Reader` 클래스가 이동 생성 및 이동 할당을 올바르게 구현했는지 검증합니다. `Reader`는 Pimpl 이디엄을 사용하여 YAML 라이브러리 의존성을 숨기므로 힙에 할당된 구현 객체를 관리합니다. 올바른 이동 시맨틱은 이 리소스의 효율적이고 안전한 소유권 이전에 필수적이며, 메모리 누수와 비싼 복사를 방지합니다. 테스트는 이동된 `Reader`가 유효하지 않게 되고, 이동받은 `Reader`가 올바르게 작동하는지 확인합니다.\n\n**파일**: `tests/unit/config/reader.cpp`\n\n```cpp\n// ...\nTEST_CASE(\"Reader Move Semantics\", \"[reader]\") {\n SECTION(\"Should correctly move construct a reader\") {\n // Arrange\n const TemporaryFileFixture Fixture;\n Fixture.CreateFileWithContent(\"key: value\");\n auto reader1 = core::config::Reader::LoadFromFile(Fixture.Path);\n REQUIRE(reader1);\n\n // Act\n auto reader2 = std::move(reader1);\n\n // Assert\n REQUIRE(reader2);\n const auto Value = reader2.Read(\"key\");\n REQUIRE(Value.has_value());\n REQUIRE(*Value == \"value\");\n }\n\n SECTION(\"Should correctly move assign a reader\") {\n // ...\n }\n\n SECTION(\"A moved-from reader should be invalid and return errors\") {\n // Arrange\n const TemporaryFileFixture Fixture;\n Fixture.CreateFileWithContent(\"key: value\");\n auto reader1 = core::config::Reader::LoadFromFile(Fixture.Path);\n REQUIRE(reader1);\n\n // Act\n auto reader2 = std::move(reader1);\n REQUIRE(reader2);\n\n // Assert on the moved-from reader (reader1)\n REQUIRE_FALSE(reader1);\n REQUIRE(reader1.GetError() == core::config::Reader::Error::kKeyNotFound);\n }\n}\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n- 구현을 검증하려면 프로젝트를 빌드하고 `ctest`를 사용하여 테스트 스위트를 실행합니다. 이 프로세스는 표준적인 out-of-source CMake 빌드를 가정합니다.\n\n```bash\n# 1. 리포지토리의 루트로 이동합니다.\ncd /path/to/readable-code-cpp-core-framework\n\n# 2. CMake를 사용하여 프로젝트를 구성하고 빌드 디렉토리를 생성합니다.\ncmake -B build\n\n# 3. 테스트 실행 파일 컴파일을 포함하여 프로젝트를 빌드합니다.\ncmake --build build\n\n# 4. 빌드 디렉토리에서 ctest를 사용하여 테스트 스위트를 실행합니다.\ncd build\nctest --verbose\n```\n\n### 4.2. 예상 결과\n\n- `ctest` 명령어는 `Path`, `File`, `Reader`에 대해 정의된 모든 테스트를 실행해야 합니다. 출력은 모든 테스트가 실패나 충돌 없이 통과했음을 나타내야 합니다. 정확한 테스트 수는 약간 다를 수 있지만, 요약이 핵심입니다.\n\n```\nStart 1: unit-core-filesystem-path\n1/3 Test #1: unit-core-filesystem-path ........ 성공 0.01 s\nStart 2: unit-core-filesystem-file\n2/3 Test #2: unit-core-filesystem-file ........ 성공 0.01 s\nStart 3: unit-core-config-reader\n3/3 Test #3: unit-core-config-reader ............ 성공 0.01 s\n\n100% 테스트 통과, 3개 중 0개 실패\n\n총 테스트 시간 (실제) = 0.03 s\n```","경로 조작, 파일 I/O, YAML 파싱의 정확성을 확인하는 유닛 테스트 스위트",[2170,2173,2175],{"_24":2171,"_83":39,"_84":2172,"_85":61},"생성, 결합, 구성 요소 추출에 대한 Path 클래스 유닛 테스트",28,{"_24":2174,"_83":39,"_84":2172,"_85":88},"존재 확인, 읽기/쓰기, 엣지 케이스에 대한 File 클래스 유닛 테스트",{"_24":2176,"_83":39,"_84":2172,"_85":91},"파일 로딩, 오류 처리, 값 읽기, 이동 의미론에 대한 Config Reader 유닛 테스트","독립적인 유닛 테스트를 통해 코어 파일시스템(`Path`, `File`) 및 설정(`Reader`) 유틸리티를 검증",{"_22":2179,"_24":2180,"_75":2181,"_77":2182,"_79":2183,"_51":2193,"_42":99},"task-1751727106048","시간 및 로깅 유틸리티 유닛 및 통합 테스트","# 작업: 시간 및 로깅 유틸리티를 위한 단위 및 통합 테스트\n\n> **에픽**: 포괄적인 시스템 검증\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: 시간(`Duration`, `Stamp`) 및 로깅(`Logger`) 컴포넌트의 검증.\n- **근거**: `Time`과 `Logger` 유틸리티는 프레임워크 전체에서 성능 측정, 작업 스케줄링, 시스템 모니터링에 사용되는 핵심 컴포넌트입니다. `Scheduler`나 `Pipeline`과 같은 상위 레벨 컴포넌트에서 발생할 수 있는 연쇄적인 오류를 방지하고, 시스템 전반의 신뢰성과 디버깅 용이성을 확보하려면, 엄격한 테스트를 통해 이들의 정확성을 검증하는 것이 매우 중요합니다.\n\n### 1.2. 결과물\n- **예상 결과물**: 고정밀 시간 계산과 레벨 기반 로그 필터링을 검증하는 테스트 스위트.\n- **세부 사항**:\n - `core::time::Duration` 클래스의 모든 생성자와 비교 연산자를 검증하는 테스트 스위트.\n - `core::time::Stamp` 클래스의 생성 및 시간 차이 계산 역할을 검증하는 테스트 스위트.\n - 뺄셈 연산자를 통해 `core::time::Stamp`와 `core::time::Duration` 간의 상호작용을 검증하는 통합 테스트 스위트.\n - `core::Logger` 클래스의 생성, 모든 로깅 레벨, 레벨 기반 필터링 및 파일 싱크 출력을 검증하는 테스트 스위트.\n- **결과 파일 구조**\n```bash\n# ./\n# └── tests/\n# ├── integration/\n# │ └── time/\n# │ └── duration_stamp.cpp <-- 신규 또는 수정\n# └── unit/\n# ├── logger.cpp <-- 신규 또는 수정\n# └── time/\n# ├── duration.cpp <-- 신규 또는 수정\n# └── stamp.cpp <-- 신규 또는 수정\n```\n\n- **프로세스 흐름 다이어그램**\n 이 다이어그램은 테스트 실행 프로세스의 논리적 흐름을 보여줍니다. 테스트 러너(`ctest`)가 개별 테스트 실행 파일을 호출하면, 이 파일들은 Catch2 프레임워크를 사용하여 `Time` 및 `Logger` 컴포넌트의 동작을 검증(assert)합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph 테스트 실행\n Runner[\"테스트 러너 (예: ctest)\"]\n end\n \n subgraph \"단위 & 통합 테스트 스위트\"\n direction LR\n TimeTests[\"시간 유틸리티 테스트 스위트\"]\n LoggerTests[\"로거 테스트 스위트\"]\n end\n\n subgraph \"테스트 대상 컴포넌트\"\n direction LR\n Duration[\"core::time::Duration\"]\n Stamp[\"core::time::Stamp\"]\n Logger[\"core::Logger\"]\n end\n\n Runner --> TimeTests\n Runner --> LoggerTests\n\n TimeTests -- 동작 검증 --> Duration\n TimeTests -- 동작 검증 --> Stamp\n LoggerTests -- 동작 검증 --> Logger\n```\n\n### 1.3. 인수 조건\n\n개발자는 작업을 완료 처리하려면 아래 항목들을 모두 완수해야 합니다. 이는 전체적인 맥락을 파악하기 위한 체크리스트이며, 각 항목의 상세 구현 내용은 3절에서 다룹니다.\n\n- [ ] Duration 클래스의 생성 및 비교를 위한 단위 테스트.\n- [ ] Stamp 클래스 생성을 위한 단위 테스트.\n- [ ] 경과 시간 계산을 검증하기 위한 `Stamp` 및 `Duration` 통합 테스트.\n- [ ] Logger의 생성, 레벨 필터링, 파일 싱크 출력을 위한 단위 테스트.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 컴포넌트**:\n - `core::time::Duration`: 고정밀 시간 간격을 표현하는 핵심 유틸리티입니다. 이 작업에서는 `Scheduler`에 필수적인 생성, 단위(초, 밀리초 등) 간 변환, 비교 로직을 검증해야 합니다.\n - `core::time::Stamp`: 고해상도 시점을 포착하는 핵심 유틸리티입니다. 이 작업에서는 시간을 포착하는 기능과, `Duration`과 함께 사용될 때 차이를 정확하게 계산하는지 검증해야 합니다.\n - `core::Logger`: 애플리케이션 전반의 이벤트 로깅을 위한 핵심 유틸리티입니다. 이 작업에서는 다른 모든 컴포넌트의 진단과 모니터링에 필수적인 레벨 기반 필터링 및 출력 싱크(특히 파일 싱크) 쓰기 기능을 검증해야 합니다.\n - `core::filesystem::Path`: `Logger` 테스트에서 로그 파일 출력 위치를 지정하는 데 사용되는 유틸리티입니다.\n\n### 2.2. 영향 받는 파일\n\n이 작업을 완료하기 위해 다음 파일들이 생성되거나 수정됩니다.\n\n- `tests/unit/time/duration.cpp`\n- `tests/unit/time/stamp.cpp`\n- `tests/integration/time/duration_stamp.cpp`\n- `tests/unit/logger.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `Step`은 **인수 조건**의 한 항목에 대응됩니다. 각 `Step`은 다시 세부적인 `Action`들로 나뉩니다. 각 `Action`은 제목, 명확한 서술적 설명('무엇을', '왜'에 대한 내용 포함), 그리고 정확한 코드 구현으로 구성되어 있습니다.\n\n---\n\n### Step 1: Duration 클래스의 생성 및 비교를 위한 단위 테스트.\n\n#### 1. 기본 생성 확인\n\n**설명**: `core::time::Duration` 객체가 기본 생성될 때, 지원되는 모든 시간 단위에서 0의 시간 간격을 나타내는지 확인하는 테스트 케이스를 작성합니다. 이는 클래스의 예측 가능한 기본 상태를 확립합니다.\n\n**파일**: `tests/unit/time/duration.cpp`\n\n```cpp\n#include \"core/time/duration.hpp\"\n\n#include \"catch2/catch_test_macros.hpp\"\n\nTEST_CASE(\"Duration should be default constructible to zero\",\n \"[core][time][duration]\") {\n // Arrange\n const core::time::Duration DefaultDuration;\n\n // Act\n const auto nanoseconds =\n DefaultDuration.Get(core::time::Duration::Unit::kNanoseconds);\n const auto milliseconds =\n DefaultDuration.Get(core::time::Duration::Unit::kMilliseconds);\n const auto seconds = DefaultDuration.Get(core::time::Duration::Unit::kSeconds);\n\n // Assert\n REQUIRE(nanoseconds == 0);\n REQUIRE(milliseconds == 0);\n REQUIRE(seconds == 0);\n}\n```\n\n#### 2. 값과 단위로부터의 생성 확인\n\n**설명**: 정수 값과 `Duration::Unit`으로부터 `Duration` 객체가 올바르게 생성될 수 있는지 검증하는 테스트 케이스를 구현합니다. 이 테스트는 다른 여러 단위로 시간 간격을 조회했을 때 정확히 변환된 값이 반환되는지를 검증(assert)해야 합니다. 이를 통해 핵심 생성자와 내부 변환 로직의 정확성을 확인합니다.\n\n**파일**: `tests/unit/time/duration.cpp`\n\n```cpp\nTEST_CASE(\"Duration should be constructible from a value and unit\",\n \"[core][time][duration]\") {\n // Arrange\n const core::time::Duration TwoSeconds(2,\n core::time::Duration::Unit::kSeconds);\n const core::time::Duration FiveHundredMilliseconds(\n 500, core::time::Duration::Unit::kMilliseconds);\n\n // Act & Assert\n REQUIRE(TwoSeconds.Get(core::time::Duration::Unit::kSeconds) == 2);\n REQUIRE(TwoSeconds.Get(core::time::Duration::Unit::kMilliseconds) == 2000);\n REQUIRE(TwoSeconds.Get(core::time::Duration::Unit::kMicroseconds) == 2000000);\n REQUIRE(TwoSeconds.Get(core::time::Duration::Unit::kNanoseconds) ==\n 2000000000);\n\n REQUIRE(FiveHundredMilliseconds.Get(\n core::time::Duration::Unit::kMilliseconds) == 500);\n REQUIRE(FiveHundredMilliseconds.Get(\n core::time::Duration::Unit::kNanoseconds) == 500000000);\n}\n```\n\n#### 3. 비교 연산자 확인\n\n**설명**: 모든 비교 연산자(`==`, `!=`, `<`, `>`, `<=`, `>=`)를 검증하는 포괄적인 테스트 케이스를 작성합니다. `Scheduler`와 같이 시간에 민감한 다른 컴포넌트들이 이 연산자들을 통해 시간 간격을 비교하므로, 이들의 정확성을 보장하는 것은 매우 중요합니다. 테스트에서는 서로 다른 단위로 생성되었지만 값은 같거나 다른 시간 간격들을 비교해야 합니다.\n\n**파일**: `tests/unit/time/duration.cpp`\n\n```cpp\nTEST_CASE(\"Duration comparison operators should work correctly\",\n \"[core][time][duration]\") {\n // Arrange\n using core::time::Duration;\n const Duration OneSecond(1000, Duration::Unit::kMilliseconds);\n const Duration AnotherOneSecond(1, Duration::Unit::kSeconds);\n const Duration TwoSeconds(2000, Duration::Unit::kMilliseconds);\n const Duration HalfASecond(500, Duration::Unit::kMilliseconds);\n\n // Act & Assert\n REQUIRE(OneSecond == AnotherOneSecond);\n REQUIRE(OneSecond != TwoSeconds);\n REQUIRE(HalfASecond < OneSecond);\n REQUIRE(TwoSeconds > OneSecond);\n REQUIRE(OneSecond <= AnotherOneSecond);\n REQUIRE(TwoSeconds >= AnotherOneSecond);\n}\n```\n\n---\n\n### Step 2: Stamp 클래스 생성을 위한 단위 테스트.\n\n#### 1. 기본 생성 확인\n\n**설명**: `core::time::Stamp` 객체가 예외를 던지지 않고 기본 생성될 수 있는지 확인하는 간단한 테스트 케이스를 구현합니다. 이는 생성자의 핵심 기능인 현재 시스템 시간 포착이 성공적으로 이루어졌음을 암묵적으로 검증하는 것입니다.\n\n**파일**: `tests/unit/time/stamp.cpp`\n\n```cpp\n#include \"core/time/stamp.hpp\"\n\n#include \n\nTEST_CASE(\"Stamp can be default constructed\", \"[core][time][stamp]\") {\n REQUIRE_NOTHROW(core::time::Stamp());\n}\n```\n\n---\n\n### Step 3: 경과 시간 계산 검증을 위한 `Stamp`와 `Duration`의 통합 테스트.\n\n#### 1. 경과 시간 계산 확인\n\n**설명**: `Stamp`와 `Duration`의 상호작용을 검증하기 위한 통합 테스트를 작성합니다. 테스트는 시작 `Stamp`를 기록하고, 의도적으로 측정 가능한 지연 시간을 발생시킨 후, 종료 `Stamp`를 기록합니다. 그 다음, 종료 스탬프에서 시작 스탬프를 빼서 경과 시간을 계산하고, 그 결과로 나온 `Duration` 객체가 사전에 설정된 지연 시간의 허용 오차 범위 내에 있는지 검증합니다. 이를 통해 `Stamp::operator-`와 타이밍 메커니즘의 정확성을 확인합니다.\n\n**파일**: `tests/integration/time/duration_stamp.cpp`\n\n```cpp\n#include \n#include \n#include \n\n#include \"catch2/catch_test_macros.hpp\"\n#include \"core/time/duration.hpp\"\n#include \"core/time/stamp.hpp\"\n\nTEST_CASE(\"Duration Get returns correct values for all time units\",\n \"[core][time][duration_stamp]\") {\n // 1. Setup: 측정 가능한 지연을 발생시킵니다.\n const int64_t SleepMilliseconds = 50; // 고정된 값 또는 임의의 값을 사용합니다\n \n const core::time::Stamp Start;\n std::this_thread::sleep_for(std::chrono::milliseconds(SleepMilliseconds));\n const core::time::Stamp End;\n\n // 2. Action: 경과 시간을 계산합니다.\n const core::time::Duration Elapsed = End - Start;\n\n // 3. Assert: 경과 시간이 허용 가능한 범위 내에 있는지 확인합니다.\n const auto ElapsedMilliseconds =\n Elapsed.Get(core::time::Duration::Unit::kMilliseconds);\n REQUIRE(ElapsedMilliseconds >= SleepMilliseconds);\n // 시스템 스케줄링 지연은 허용하지만, 과도한 지연은 없어야 합니다.\n REQUIRE(ElapsedMilliseconds < SleepMilliseconds * 5); \n}\n```\n\n---\n\n### Step 4: Logger의 생성, 레벨 필터링, 파일 싱크 출력을 위한 단위 테스트.\n\n#### 1. 기본 로거 기능 확인\n\n**설명**: `core::Logger`가 정상적으로 생성되고, 모든 공개 로깅 메서드(`Trace`, `Debug` 등)가 예외를 발생시키지 않고 호출될 수 있는지 확인하는 테스트 케이스를 추가합니다. 이는 로거 API에 대한 기본적인 온전성 검사(sanity check) 역할을 합니다.\n\n**파일**: `tests/unit/logger.cpp`\n\n```cpp\n#include \"core/logger.hpp\"\n#include \"catch2/catch_test_macros.hpp\"\n\n// ... (다른 include 및 헬퍼 함수)\n\nTEST_CASE(\"Logger class functionality\", \"[core][logger]\") {\n SECTION(\"Logger can be constructed and destructed\") {\n REQUIRE_NOTHROW([]() { core::Logger logger(\"TestLogger1\"); }());\n }\n\n SECTION(\"Logging methods can be called without throwing exceptions\") {\n core::Logger logger(\"TestLogger2\");\n REQUIRE_NOTHROW(logger.Info(\"This is an info message.\"));\n REQUIRE_NOTHROW(logger.Warn(\"This is a warning message.\"));\n // ... 모든 레벨에 대해 동일하게 반복\n }\n}\n```\n\n#### 2. 레벨 기반 메시지 필터링 및 파일 출력 확인\n\n**설명**: 로거의 레벨 기반 필터링 로직을 철저하게 검증하기 위해 데이터 기반 테스트를 구현합니다. 이 테스트는 메시지의 심각도가 로거에 설정된 레벨보다 높거나 같은 경우에만 지정된 로그 파일에 메시지가 쓰이는지 확인해야 합니다. 이를 위해서는 테스트 로그 파일(생성, 정리)을 관리하고 그 내용을 확인하는 헬퍼 함수를 만들어야 합니다.\n\n**파일**: `tests/unit/logger.cpp`\n\n```cpp\n// ... (AssertMessageWasLogged/NotLogged 같은 include 및 헬퍼 함수)\n\nTEST_CASE(\"Logger correctly filters messages by level\", \"[core][logger]\") {\n const auto* const LogFilePath = \"test_log.log\";\n const auto* const LoggerName = \"FileVerificationLogger\";\n\n const std::vector logger_levels = {\n core::Logger::Level::kTrace, core::Logger::Level::kDebug,\n core::Logger::Level::kInfo, core::Logger::Level::kWarn,\n core::Logger::Level::kError, core::Logger::Level::kFatal};\n\n // 대표적인 메시지 테스트 케이스 정의\n const struct {\n core::Logger::Level message_level;\n std::function log_function;\n } message_case = {\n .message_level = core::Logger::Level::kWarn,\n .log_function = [](core::Logger& logger){ logger.Warn(\"Test warning\"); }\n };\n\n for (const auto& logger_level : logger_levels) {\n // Arrange: 테스트 전에 로그 파일이 깨끗한 상태인지 확인\n if (std::filesystem::exists(LogFilePath)) {\n std::filesystem::remove(LogFilePath);\n }\n\n // Act: 특정 레벨로 로거를 생성하고 메시지 기록\n {\n core::Logger logger(LoggerName, logger_level);\n logger.AddFileSink(core::filesystem::Path(LogFilePath));\n message_case.log_function(logger);\n } // 여기서 로거가 소멸되며 메시지를 flush 함\n\n // Assert\n const bool should_be_logged = message_case.message_level >= logger_level;\n if (should_be_logged) {\n // 헬퍼 함수가 파일 존재 여부와 정확한 메시지 포함 여부 확인\n AssertMessageWasLogged(LogFilePath, LoggerName, ...);\n } else {\n // 헬퍼 함수가 파일이 비어있거나 존재하지 않음을 확인\n AssertMessageWasNotLogged(LogFilePath);\n }\n\n // Cleanup\n if (std::filesystem::exists(LogFilePath)) {\n std::filesystem::remove(LogFilePath);\n }\n }\n}\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n- 개발자는 구현을 검증하기 위해 테스트 타겟을 빌드하고 실행해야 합니다. 아래 명령어는 표준적인 out-of-source CMake 빌드 프로세스를 기준으로 합니다.\n\n```bash\n# 1. 빌드 디렉터리로 이동합니다\ncd build/\n\n# 2. 테스트가 활성화되도록 프로젝트를 구성합니다 (이미 완료된 경우 생략)\n# 이 명령어는 프로젝트의 CMake 구성에 따라 달라질 수 있습니다\ncmake -DENABLE_TESTING=ON ..\n\n# 3. 테스트 실행 파일을 빌드합니다\ncmake --build .\n\n# 4. CTest를 사용하여 모든 테스트를 실행합니다\nctest --verbose\n```\n\n### 4.2. 예상 결과\n\n- 모든 테스트가 통과하면 검증이 성공한 것입니다. `ctest` 명령어 실행 시, 모든 테스트 스위트에서 100% 통과율을 보여야 합니다. 출력 결과는 아래와 유사합니다.\n\n```\nTest project /path/to/readable-code-cpp-core-framework/build\n Start 1: unit_tests_time\n1/3 Test #1: unit_tests_time .................... Passed 0.01 s\n Start 2: unit_tests_logger\n2/3 Test #2: unit_tests_logger .................. Passed 0.02 s\n Start 3: integration_tests_time\n3/3 Test #3: integration_tests_time ............. Passed 0.06 s\n\n100% tests passed, 0 tests failed out of 3\n\nTotal Test time (real) = 0.10 s\n```","고정밀 시간 계산 및 레벨 기반 로그 필터링을 검증하는 테스트 스위트",[2184,2187,2189,2191],{"_24":2185,"_83":39,"_84":2186,"_85":61},"생성 및 비교에 대한 Duration 클래스 유닛 테스트",29,{"_24":2188,"_83":39,"_84":2186,"_85":88},"생성에 대한 Stamp 클래스 유닛 테스트",{"_24":2190,"_83":39,"_84":2186,"_85":91},"경과 시간 계산을 검증하기 위한 `Stamp`와 `Duration`의 통합 테스트",{"_24":2192,"_83":39,"_84":2186,"_85":94},"생성, 레벨 필터링, 파일 싱크 출력에 대한 Logger 유닛 테스트","시간(`Duration`, `Stamp`) 및 로깅(`Logger`) 컴포넌트를 검증",{"_22":2195,"_24":2196,"_75":2197,"_77":2198,"_79":2199,"_51":2207,"_42":99},"task-1751727160543","동시성 기본 요소 유닛 테스트","# 과제: 동시성 프리미티브를 위한 단위 테스트\n\n> **에픽**: 포괄적인 시스템 검증\n\n## 1. 과제 정의\n\n### 1.1. 목표\n- **목표**: 핵심 동시성 구성 요소(`ThreadPool`, `ExecutionEntry`)의 정확성과 스레드 안전성을 검증합니다.\n- **근거**: `ThreadPool`과 `ExecutionEntry` 클래스는 전체 동시성 엔진의 핵심 기반입니다. `ThreadPool`은 모든 비동기 작업의 핵심 실행자이며, `ExecutionEntry`는 `Scheduler`가 작업의 우선순위를 정하는 데 필수적입니다. 이들의 안정성, 스레드 안전성, 설계 명세 준수를 증명하기 위해 엄격한 단위 테스트가 필요합니다. 이를 통해 `Pipeline`이나 `Scheduler` 같은 상위 수준 구성 요소에서 발생할 수 있는, 디버깅하기 어려운 시스템 장애를 예방할 수 있습니다.\n\n### 1.2. 결과물\n- **예상 결과**: 스레드 풀이 작업을 올바르게 관리하고 실행 항목이 우선순위에 따라 적절히 처리되는지 확인하는 단위 테스트 세트.\n- **명세**:\n - `core::concurrency::ThreadPool`을 위한 테스트 스위트: 생명주기 관리(생성/소멸), 작업 큐잉, 다중 작업 실행, 정상 종료, 큐가 가득 찼을 때의 스레드 안전한 블로킹을 검증합니다.\n - `core::concurrency::ExecutionEntry`를 위한 테스트 스위트: 데이터 멤버 저장 및 최소 우선순위 큐(max-heap인 `std::priority_queue`로 에뮬레이션)에서 사용하기 위한 `operator>`의 정확성을 검증합니다.\n- **결과 파일 구조**\n```bash\n# ./\n# └── tests/\n# └── unit/\n# └── concurrency/\n# ├── execution_entry.cpp <-- 신규\n# └── thread_pool.cpp <-- 신규\n```\n\n- **프로세스 흐름도**\n 이 다이어그램은 본 과제의 개발 및 검증 워크플로우를 보여줍니다. 개발자는 라이브러리 구성 요소를 직접 대상으로 하는 단위 테스트를 작성하며, 이는 테스트 러너에 의해 컴파일되고 실행되어 동작을 검증합니다.\n\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"개발 단계\"\n Dev[\"개발자\"] -- \"다음을 위한 테스트 작성\" --> TestFiles[\"execution_entry.cpp
thread_pool.cpp\"];\n end\n\n subgraph \"검증 단계\"\n TestFiles -- \"다음에 대해 컴파일\" --> LibComponents[\"ThreadPool & ExecutionEntry
(라이브러리 코드)\"];\n BuildSystem[\"빌드 시스템 (CMake/Make)\"] -- \"컴파일 및 링크\" --> TestExecutable[\"테스트 실행 파일\"];\n Dev -- \"호출\" --> BuildSystem;\n TestExecutable -- \"다음에 대해 테스트 실행\" --> LibComponents;\n TestExecutable -- \"결과 보고\" --> TestRunnerOutput[\"테스트 러너 출력 (Catch2)\"];\n end\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 과제를 완료로 표시하기 위해 다음 항목들을 완료해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 상세 구현은 3절에 기술되어 있습니다.\n\n- [ ] 생성/소멸, 작업 실행, 종료에 대한 ThreadPool 단위 테스트.\n- [ ] 스레드 풀 큐가 가득 찼을 때의 블로킹 동작에 대한 테스트 케이스.\n- [ ] 데이터 저장 및 우선순위 큐 비교 로직에 대한 ExecutionEntry 단위 테스트.\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 구성 요소**:\n - **`ThreadPool`**: 시스템의 핵심 동시성 엔진으로서, 이 구성 요소의 정확성을 직접 검증합니다. 테스트는 스레드 관리, 공개 메서드 `EnqueueJob`을 통한 작업 수락, 그리고 깔끔한 종료 능력을 검증할 것입니다.\n - **`ExecutionEntry`**: 이 데이터 구조는 `Scheduler`의 전제 조건입니다. 테스트는 단순한 데이터 컨테이너로서의 역할과, `Scheduler`의 우선순위 큐가 올바르게 작동하도록 하는 핵심적인 비교 로직을 검증할 것입니다.\n - **`Catch2` (테스팅 프레임워크)**: 단위 테스트는 Catch2 프레임워크를 사용하여 테스트 케이스와 단언(assertion)을 구조화하여 구현될 것입니다.\n\n### 2.2. 영향받는 파일\n\n이 과제를 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `tests/unit/concurrency/thread_pool.cpp`\n- `tests/unit/concurrency/execution_entry.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `Step`은 **완료 조건**의 항목에 해당합니다. 각 `Step`은 세분화된 `Action`들로 나뉩니다. 각 `Action`에 대해 제목, 명확한 서술적 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### Step 1: 생성/소멸, 작업 실행, 종료에 대한 ThreadPool 단위 테스트.\n\n#### 1. 생성 및 소멸 테스트 추가\n\n이 작업은 `ThreadPool`의 기본 생명주기를 검증합니다. 테스트는 생성자가 성공적으로 리소스를 할당하고 작업자 스레드를 시작할 수 있는지, 그리고 소멸자가 교착 상태나 비정상 종료 없이 스레드에 정지 신호를 보내고 join 할 수 있는지 확인합니다. 이는 구성 요소의 안정성에 대한 가장 기본적인 테스트입니다.\n\n**파일**: `tests/unit/concurrency/thread_pool.cpp`\n\n```cpp\n#include \"core/concurrency/thread_pool.hpp\"\n\n#include \n// ... other includes\n\nTEST_CASE(\"ThreadPool constructs and destructs correctly\",\n \"[core][concurrency][thread_pool]\") {\n // Arrange\n constexpr auto kNumberOfThreads = 4U;\n constexpr auto kQueueCapacity = 10U;\n\n // Act & Assert\n // This block should execute without any crashes or hangs.\n // The constructor should start the threads, and the destructor must join them\n // all.\n REQUIRE_NOTHROW([&]() {\n core::concurrency::ThreadPool pool(kNumberOfThreads, kQueueCapacity);\n }());\n}\n```\n\n#### 2. 단일 작업 실행 테스트 추가\n\n이 작업은 `ThreadPool`이 단일 작업 단위를 수락하고 실행할 수 있는지 검증합니다. `std::promise`와 `std::future`를 사용하여 작업자 스레드에서 메인 테스트 스레드로 작업이 성공적으로 완료되었음을 알립니다. 이를 통해 핵심적인 작업 큐잉 및 실행 메커니즘이 작동하는지 확인합니다.\n\n**파일**: `tests/unit/concurrency/thread_pool.cpp`\n\n```cpp\n// ... previous test case\n\nTEST_CASE(\"ThreadPool executes a single job\",\n \"[core][concurrency][thread_pool]\") {\n // Arrange\n core::concurrency::ThreadPool pool(1U, 1U);\n std::promise job_executed_promise;\n std::future job_executed_future = job_executed_promise.get_future();\n\n // Act\n pool.EnqueueJob([&job_executed_promise]() { job_executed_promise.set_value(); });\n\n // Assert\n const auto status = job_executed_future.wait_for(std::chrono::seconds(1));\n REQUIRE(status == std::future_status::ready);\n}\n```\n\n#### 3. 다중 작업 실행 테스트 추가\n\n이 작업은 스레드 풀이 여러 작업을 동시에 처리하는 능력을 검증합니다. 사용 가능한 스레드보다 더 많은 작업을 큐에 넣어 큐잉 메커니즘이 작동하고 모든 작업이 결국 실행되는지 확인합니다. 원자적 카운터와 조건 변수를 사용하여 모든 작업이 완료될 때까지 안정적으로 대기하며, 중간 정도의 부하 상태에서 풀의 처리량과 정확성을 테스트합니다.\n\n**파일**: `tests/unit/concurrency/thread_pool.cpp`\n\n```cpp\n// ... previous test cases\n\nTEST_CASE(\"ThreadPool should execute multiple jobs\",\n \"[core][concurrency][thread_pool]\") {\n constexpr uint32_t kNumberOfThreads = 4;\n constexpr uint32_t kQueueCapacity = 16;\n constexpr int kNumberOfJobs = 10;\n\n core::concurrency::ThreadPool thread_pool(kNumberOfThreads, kQueueCapacity);\n std::atomic jobs_executed_count = 0;\n std::mutex all_jobs_done_mutex;\n std::condition_variable all_jobs_done_condition_variable;\n\n for (int i = 0; i < kNumberOfJobs; ++i) {\n thread_pool.EnqueueJob([&] {\n jobs_executed_count++;\n if (jobs_executed_count.load() == kNumberOfJobs) {\n all_jobs_done_condition_variable.notify_one();\n }\n });\n }\n\n std::unique_lock lock(all_jobs_done_mutex);\n REQUIRE(all_jobs_done_condition_variable.wait_for(\n lock, std::chrono::seconds(1),\n [&] { return jobs_executed_count.load() == kNumberOfJobs; }));\n}\n```\n\n#### 4. 정상 종료 테스트 추가\n\n이 작업은 `ThreadPool`의 소멸자가 큐에 있는 모든 작업이 완료될 때까지 블로킹되는지 검증합니다. 이는 풀이 소멸될 때 작업 손실이 없도록 보장하는 중요한 기능입니다. 테스트는 약간의 시간이 걸리는 여러 작업을 큐에 넣은 다음 풀이 범위를 벗어나도록 하여, 모든 작업이 실행되었는지 확인합니다.\n\n**파일**: `tests/unit/concurrency/thread_pool.cpp`\n\n```cpp\n// ... previous test cases\n\nTEST_CASE(\"ThreadPool shuts down gracefully after completing all jobs\",\n \"[core][concurrency][thread_pool]\") {\n // Arrange\n constexpr int kNumberOfJobs = 10;\n std::atomic jobs_executed_count = 0;\n\n // Act\n {\n core::concurrency::ThreadPool pool(4, 10);\n for (int i = 0; i < kNumberOfJobs; ++i) {\n pool.EnqueueJob([&jobs_executed_count] {\n std::this_thread::sleep_for(std::chrono::milliseconds(10));\n jobs_executed_count++;\n });\n }\n // Destructor is called here, and it should block until all jobs are done.\n }\n\n // Assert\n REQUIRE(jobs_executed_count.load() == kNumberOfJobs);\n}\n```\n\n---\n\n### Step 2: 스레드 풀 큐가 가득 찼을 때의 블로킹 동작에 대한 테스트 케이스.\n\n#### 1. 블로킹 큐잉 테스트 구현\n\n이 작업은 중요한 스레드 안전성 기능, 즉 작업 큐가 가득 찼을 때 `EnqueueJob`이 블로킹되어야 함을 테스트합니다. 테스트는 작업자 스레드가 큐의 유일한 슬롯을 점유한 채로 일시 중지되는 시나리오를 신중하게 조율합니다. 그런 다음 별도의 스레드가 두 번째 작업을 큐에 넣으려고 시도하며, 이 작업은 블로킹되어야 합니다. 테스트는 첫 번째 작업이 완료되어 두 번째 스레드의 블로킹이 해제되기 전에 이 블로킹 동작을 확인합니다.\n\n**파일**: `tests/unit/concurrency/thread_pool.cpp`\n\n```cpp\n// ... previous test cases\n\nTEST_CASE(\"Enqueue should block when queue is full\",\n \"[core][concurrency][thread_pool]\\\") {\n core::concurrency::ThreadPool thread_pool(1, 1);\n std::atomic first_job_started = false;\n std::atomic first_job_can_finish = false;\n std::atomic second_job_enqueued = false;\n\n // Enqueue a job that will block.\n thread_pool.EnqueueJob([&] {\n first_job_started.store(true);\n while (!first_job_can_finish.load()) {\n std::this_thread::yield();\n }\n });\n\n // Wait for the first job to start.\n while (!first_job_started.load()) {\n std::this_thread::yield();\n }\n\n // Attempt to enqueue a second job, which should block.\n std::thread enqueuer([&] {\n thread_pool.EnqueueJob([&] { /* Second job */ });\n second_job_enqueued.store(true);\n });\n\n // Verify the second job has not been enqueued yet.\n REQUIRE_FALSE(second_job_enqueued.load());\n\n // Unblock the first job.\n first_job_can_finish.store(true);\n enqueuer.join();\n\n // Verify the second job was finally enqueued.\n REQUIRE(second_job_enqueued.load());\n}\n```\n\n---\n\n### Step 3: 데이터 저장 및 우선순위 큐 비교 로직에 대한 ExecutionEntry 단위 테스트.\n\n#### 1. 데이터 저장 및 검색 테스트 추가\n\n이 작업은 `ExecutionEntry` 클래스가 생성자에 제공된 `execution_time`과 `task_id`를 올바르게 저장하는지 확인하는 테스트를 생성합니다. 공개 getter 메서드가 정확히 동일한 값을 반환하는지 확인하여 객체가 상태를 올바르게 유지하는지 보장합니다. 이는 기본적이지만 필수적인 온전성 검사입니다.\n\n**파일**: `tests/unit/concurrency/execution_entry.cpp`\n\n```cpp\n#include \"core/concurrency/execution_entry.hpp\"\n\n#include \n#include \n\nusing core::concurrency::ExecutionEntry;\nusing core::concurrency::TaskId;\nusing namespace std::chrono_literals;\n\nTEST_CASE(\"ExecutionEntry correctly stores and retrieves data\",\n \"[execution_entry]\") {\n const auto Now = std::chrono::steady_clock::now();\n const TaskId TaskId = 123;\n\n ExecutionEntry entry(Now, TaskId);\n\n SECTION(\"Getters should return the values passed to the constructor\") {\n REQUIRE(entry.GetExecutionTime() == Now);\n REQUIRE(entry.GetTaskId() == TaskId);\n }\n}\n```\n\n#### 2. 비교 연산자 테스트 추가\n\n이 작업은 `operator>` 구현을 검증합니다. 이 연산자는 `std::priority_queue`(max-heap)가 항목들을 올바르게 정렬하는 데 매우 중요합니다. 스케줄러는 *가장 이른* 작업을 먼저 실행해야 하므로, 우선순위 큐는 *가장 작은* 타임스탬프를 가진 항목을 *가장 높은* 우선순위로 처리해야 합니다. 테스트는 `EntryLater > EntryNow`가 참인지 확인하며, 이는 `std::priority_queue`가 우리의 `ExecutionEntry` 객체에 대해 최소 우선순위 큐처럼 동작하기 위한 올바른 로직입니다.\n\n**파일**: `tests/unit/concurrency/execution_entry.cpp`\n\n```cpp\n// ... previous test case\n\nTEST_CASE(\n \"ExecutionEntry comparison operator works correctly for priority queue\",\n \"[execution_entry]\") {\n const auto Now = std::chrono::steady_clock::now();\n const auto Later = Now + 10ms;\n\n const ExecutionEntry EntryNow(Now, 1);\n const ExecutionEntry EntryLater(Later, 2);\n\n SECTION(\"operator> should return true for the entry with the later time\") {\n REQUIRE(EntryLater > EntryNow);\n }\n\n SECTION(\"operator> should return false for the entry with the earlier time\") {\n REQUIRE_FALSE(EntryNow > EntryLater);\n }\n\n SECTION(\"operator> should return false for entries with the same time\") {\n const ExecutionEntry AnotherEntryNow(Now, 3);\n REQUIRE_FALSE(EntryNow > AnotherEntryNow);\n REQUIRE_FALSE(AnotherEntryNow > EntryNow);\n }\n}\n```\n\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n- 개발자는 단위 테스트 스위트를 빌드하고 실행해야 합니다. 정확한 명령어는 프로젝트의 빌드 시스템 구성(예: CMake)에 따라 다릅니다. 다음은 대표적인 예시입니다.\n\n```bash\n# 1. 빌드 디렉토리로 이동\ncd build\n\n# 2. 프로젝트가 구성되고 빌드되었는지 확인\ncmake ..\nmake\n\n# 3. 테스트 실행 파일을 실행합니다. Catch2의 태그 시스템을 사용하여 이 테스트들만 실행합니다.\n./tests/unit/unit_tests \"[core][concurrency][thread_pool]\" \"[execution_entry]\"\n```\n\n### 4.2. 예상 결과\n\n- 테스트 러너는 모든 테스트 케이스가 실패나 비정상 종료 없이 통과했다고 보고해야 합니다. Catch2의 출력은 다음과 유사해야 합니다.\n\n```\n===============================================================================\nAll tests passed (12 assertions in 7 test cases)\n```","스레드 풀이 작업을 올바르게 관리하고 실행 엔트리가 적절하게 우선순위화되는지 확인하는 유닛 테스트 세트",[2200,2203,2205],{"_24":2201,"_83":39,"_84":2202,"_85":61},"생성/소멸, 작업 실행, 종료에 대한 ThreadPool 유닛 테스트",30,{"_24":2204,"_83":39,"_84":2202,"_85":88},"스레드 풀 큐가 가득 찼을 때의 블로킹 동작에 대한 테스트 케이스",{"_24":2206,"_83":39,"_84":2202,"_85":91},"데이터 저장 및 우선순위 큐 비교 로직에 대한 ExecutionEntry 유닛 테스트","기본 동시성 컴포넌트(`ThreadPool`, `ExecutionEntry`)의 정확성과 스레드 안전성을 보장하기 위해 검증",{"_22":2209,"_24":2210,"_75":2211,"_77":2212,"_79":2213,"_51":2221,"_42":99},"task-1751727172698","파이프라인 및 스케줄러 프레임워크 유닛 테스트","# 과제: 파이프라인 및 스케줄러 프레임워크 유닛 테스트\n\n> **에픽**: 종합적인 시스템 검증\n\n## 1. 과제 정의\n\n### 1.1. 목표\n- **목표**: 고수준 동시성 프레임워크 컴포넌트(`Node`, `Pipeline`, `Scheduler`) 검증.\n- **근거**: 이 과제는 \"종합적인 시스템 검증\" 에픽의 핵심적인 부분입니다. 비동기 데이터 처리 시스템의 핵심 컴포넌트인 `Node`, `Pipeline`, `Scheduler`가 견고하고, 타입 안전하며, 아키텍처 명세에 따라 동작하도록 보장합니다. 이러한 컴포넌트를 개별적으로 검증하면 상위 수준 통합에서 발생할 수 있는 버그를 예방하고, 전체 동시성 엔진에 대한 신뢰성의 기반을 마련합니다.\n\n### 1.2. 결과물\n- **예상 결과**: 파이프라인이 올바르게 실행되고, 노드가 타입을 안전하게 처리하며, 스케줄러가 주기적인 작업을 예상대로 관리하는지 확인하는 유닛 테스트 스위트.\n- **사양**:\n - `core::concurrency::pipeline::Node` 테스트 스위트: 팩토리 생성, 타입 검사, 실행 로직, 제어 흐름 신호 검증.\n - `core::concurrency::Pipeline` 테스트 스위트: 선형 실행, 노드 추가 로직(타입 불일치 오류 처리 포함), 종료 신호 전파 검증.\n - `core::concurrency::Scheduler` 테스트 스위트: 작업 관리(추가/취소), 생명주기 제어(시작/정지), `ThreadPool`과의 상호작용 검증.\n- **결과 파일 구조**\n```bash\n# ./tests/unit/concurrency/\n# ├── pipeline/\n# │ └── node.cpp <-- 생성됨\n# ├── pipeline.cpp <-- 생성됨\n# └── scheduler.cpp <-- 생성됨\n```\n\n- **프로세스 흐름도**\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"테스트 실행\"\n TestRunner[\"테스트 러너 (Catch2)\"]\n end\n\n subgraph \"테스트 스위트 (구현 예정)\"\n NodeTests[\"Node 테스트 스위트
(tests/unit/concurrency/pipeline/node.cpp)\"]\n PipelineTests[\"Pipeline 테스트 스위트
(tests/unit/concurrency/pipeline.cpp)\"]\n SchedulerTests[\"Scheduler 테스트 스위트
(tests/unit/concurrency/scheduler.cpp)\"]\n end\n \n subgraph \"테스트 대상 컴포넌트\"\n NodeClass[\"core::concurrency::pipeline::Node\"]\n PipelineClass[\"core::concurrency::Pipeline\"]\n SchedulerClass[\"core::concurrency::Scheduler\"]\n ThreadPoolClass[\"core::concurrency::ThreadPool\"]\n end\n\n TestRunner -->|실행| NodeTests\n TestRunner -->|실행| PipelineTests\n TestRunner -->|실행| SchedulerTests\n\n NodeTests -->|검증| NodeClass\n PipelineTests -->|검증| PipelineClass\n SchedulerTests -->|검증| SchedulerClass\n \n PipelineTests -->|인스턴스화| ThreadPoolClass\n SchedulerTests -->|인스턴스화| ThreadPoolClass\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 과제를 완료로 표시하기 위해 다음 항목들을 완수해야 합니다. 이는 개괄적인 체크리스트이며, 각 항목에 대한 상세 구현은 3장에 기술되어 있습니다.\n\n- [ ] 생성자/변환자 노드 생성, 타입 안전성, 제어 흐름 결과에 대한 Node 유닛 테스트.\n- [ ] 선형 실행, 오류 처리(타입 불일치), 종료 신호 전파에 대한 Pipeline 유닛 테스트.\n- [ ] 작업 관리, 시작/정지 생명주기, 스레드 풀 상호작용에 대한 Scheduler 유닛 테스트.\n\n## 2. 기술적 컨텍스트\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **주요 관련 컴포넌트**:\n - **`pipeline::Node`**: 근본적인, 타입 소거(type-erased) 처리 단위. 테스트는 팩토리 함수(`Producer`, `Transformer`), 실행 중 타입 안전성, `NodeResult`의 정확한 반환을 검증합니다.\n - **`Pipeline`**: 노드의 선형 시퀀스를 조율하는 오케스트레이터. 테스트는 노드 관리, 노드 간 타입 호환성 강제, `kKill`과 같은 제어 흐름 신호의 정확한 처리를 검증합니다.\n - **`Scheduler`**: 주기적인 작업 관리자. 테스트는 작업 추가, `ThreadPool`에서 올바른 주기로 작업 실행, 자체 생명주기(시작/정지)의 올바른 관리를 보장합니다.\n - **`ThreadPool`**: 기반이 되는 동시성 엔진. 이 과제에서 직접 테스트하지는 않지만, `Pipeline`과 `Scheduler` 테스트에서 비동기 작업을 위한 필수 실행 컨텍스트를 제공하기 위해 인스턴스화하여 사용합니다.\n\n### 2.2. 영향받는 파일\n\n이 과제를 완료하기 위해 다음 파일들이 생성되거나 수정될 것입니다.\n\n- `tests/unit/concurrency/pipeline/node.cpp`\n- `tests/unit/concurrency/pipeline.cpp`\n- `tests/unit/concurrency/scheduler.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `Step`은 **완료 조건**의 항목에 해당합니다. 각 `Step`은 더 세분화된 `Action`들로 나뉩니다. 각 `Action`에 대해, 제목과 명확한 설명('무엇을'과 '왜'를 포함), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 단계 1: 생성자/변환자 노드 생성, 타입 안전성, 제어 흐름 결과에 대한 Node 유닛 테스트.\n\n#### 1. 생성자 및 변환자 노드 기능 검증\n\n이 액션은 `Node` 생성에 대한 핵심 검증을 수행합니다. 정적 팩토리 메서드인 `Producer`와 `Transformer`가 노드를 예상된 메타데이터(ID, 입력 타입, 출력 타입)로 올바르게 초기화하고, 캡슐화된 작업 로직이 의도대로 실행되는지 확인합니다. 이는 노드가 파이프라인 내에서 예측 가능하게 동작하도록 보장하는 데 필수적입니다.\n\n**파일**: `tests/unit/concurrency/pipeline/node.cpp`\n```cpp\n#include \"core/concurrency/pipeline/node.hpp\"\n\n#include \n// ... other includes\n\nusing core::concurrency::pipeline::ControlFlow;\nusing core::concurrency::pipeline::Node;\nusing core::concurrency::pipeline::NodeResult;\n\n// ...\n\nSCENARIO(\"Node core functionality and execution\", \"[core][concurrency][pipeline][node]\") {\n GIVEN(\"A Producer Node\") {\n // ...\n Node producer = Node::Producer(ProducerNodeId, producer_job);\n\n THEN(\"it has the correct metadata\") {\n REQUIRE(producer.GetId() == ProducerNodeId);\n REQUIRE(producer.GetInputType() == typeid(void));\n REQUIRE(producer.GetOutputType() == typeid(int));\n }\n\n WHEN(\"executed\") {\n THEN(\"it returns the correct value and ignores any input\") {\n auto result_no_input = producer.Execute(std::any{});\n REQUIRE(result_no_input.control == ControlFlow::kContinue);\n REQUIRE(std::any_cast(result_no_input.data) == ExpectedValue);\n }\n }\n }\n\n GIVEN(\"A Transformer Node\") {\n // ...\n Node transformer = Node::Transformer(TransformerNodeId, double_job);\n\n THEN(\"it has the correct metadata\") {\n REQUIRE(transformer.GetId() == TransformerNodeId);\n REQUIRE(transformer.GetInputType() == typeid(int));\n REQUIRE(transformer.GetOutputType() == typeid(int));\n }\n\n WHEN(\"executed with a valid input\") {\n std::any input = InputValue;\n auto result = transformer.Execute(input);\n\n THEN(\"it returns the correctly transformed value\") {\n REQUIRE(result.control == ControlFlow::kContinue);\n REQUIRE(std::any_cast(result.data) == InputValue * 2);\n }\n }\n }\n}\n```\n\n#### 2. 타입 불일치에 대한 노드 오류 처리 검증\n\n`Node`의 핵심 기능 중 하나는 런타임 타입 안전성입니다. 이 액션은 변환자 노드가 예상 입력 타입과 일치하지 않는 타입의 `std::any` 입력을 받았을 때 `Execute` 메서드가 `std::invalid_argument` 예외를 던지는지 검증합니다. 이 테스트는 런타임 충돌을 방지하고 파이프라인의 무결성을 보장하는 데 매우 중요합니다.\n\n**파일**: `tests/unit/concurrency/pipeline/node.cpp`\n```cpp\nSCENARIO(\"Node error handling for invalid inputs\", \"[core][concurrency][pipeline][node]\") {\n GIVEN(\"A Transformer Node that expects an integer\") {\n Node transformer = Node::Transformer(1, [](int x) {\n return NodeResult{.data = x + 1, .control = ControlFlow::kContinue};\n });\n\n WHEN(\"executed with an empty std::any\") {\n THEN(\"it throws an invalid_argument exception\") {\n REQUIRE_THROWS_AS(transformer.Execute(std::any{}), std::invalid_argument);\n }\n }\n\n WHEN(\"executed with a mismatched type (std::string)\") {\n THEN(\"it throws an invalid_argument exception\") {\n REQUIRE_THROWS_AS(transformer.Execute(std::string(\"not an int\")),\n std::invalid_argument);\n }\n }\n }\n}\n```\n\n#### 3. 노드 제어 흐름 신호 검증\n\n이 액션은 노드가 `ControlFlow` 열거형의 모든 변형(`kContinue`, `kSkip`, `kKill`)을 올바르게 반환할 수 있는지 확인합니다. `Pipeline` 오케스트레이터는 실행 흐름을 관리하기 위해 이러한 신호에 의존합니다. 이 테스트들은 노드의 작업이 의도한 신호를 생성하고 그것이 `NodeResult`에 올바르게 패키징되는지 확인합니다.\n\n**파일**: `tests/unit/concurrency/pipeline/node.cpp`\n```cpp\nTEST_CASE(\"Node can return a kSkip control flow\", \"[core][concurrency][pipeline][node]\") {\n auto producer_node = Node::Producer(1, []() {\n return NodeResult{.data = 123, .control = ControlFlow::kSkip};\n });\n\n auto result = producer_node.Execute(std::any{});\n REQUIRE(std::any_cast(result.data) == 123);\n REQUIRE(result.control == ControlFlow::kSkip);\n}\n\nTEST_CASE(\"Node can return a kKill control flow\", \"[core][concurrency][pipeline][node]\") {\n auto transformer_node = Node::Transformer(1, [](double) {\n return NodeResult{.data = std::any{}, .control = ControlFlow::kKill};\n });\n\n auto result = transformer_node.Execute(3.14);\n REQUIRE(!result.data.has_value());\n REQUIRE(result.control == ControlFlow::kKill);\n}\n```\n---\n### 단계 2: 선형 실행, 오류 처리(타입 불일치), 종료 신호 전파에 대한 Pipeline 유닛 테스트.\n\n#### 1. 선형 파이프라인 실행 검증\n\n이 액션은 `Pipeline` 클래스의 주요 기능, 즉 일련의 노드를 순서대로 실행하고 그 사이에서 데이터를 전달하는 기능을 검증합니다. 테스트는 간단한 생성자-변환자-소비자 체인을 구성하고 최종 출력이 올바른지 확인합니다. 이를 통해 `Pipeline`이 `ThreadPool`을 사용하여 노드를 올바르게 스케줄링하고 데이터 전달을 관리하는지 확인합니다.\n\n**파일**: `tests/unit/concurrency/pipeline.cpp`\n```cpp\n#include \"core/concurrency/pipeline.hpp\"\n// ... other includes\n\nTEST_CASE(\"Pipeline executes a single linear cycle correctly\", \"[core][concurrency][pipeline]\") {\n // Arrange\n auto thread_pool = std::make_shared(kThreadPoolSize, kQueueCapacity);\n Pipeline pipeline(thread_pool);\n std::promise result_promise;\n auto result_future = result_promise.get_future();\n\n // Define a simple pipeline: Producer -> Transformer -> Consumer\n pipeline.AddNode(Node::Producer(1, [] { return 10; }));\n pipeline.AddNode(Node::Transformer(2, [](int value) { return value * 2; }));\n pipeline.AddNode(Node::Transformer(3, [&result_promise](int final_result) {\n result_promise.set_value(final_result);\n }));\n\n // Act\n pipeline.RunCycle();\n\n // Assert\n REQUIRE(result_future.wait_for(kTimeout) == std::future_status::ready);\n REQUIRE(result_future.get() == 20);\n}\n```\n\n#### 2. 종료 신호 전파 검증\n\n이 액션은 중요한 제어 흐름 기능을 테스트합니다. 파이프라인의 어떤 노드가 `kKill` 신호를 반환하면, 파이프라인이 즉시 실행을 중지하고 후속 노드의 실행을 막으며 \"종료됨(killed)\" 상태로 전환되는지 확인합니다. 이 동작은 데이터 처리 스트림을 안전하게 종료하는 데 필수적입니다.\n\n**파일**: `tests/unit/concurrency/pipeline.cpp`\n```cpp\nTEST_CASE(\"Pipeline is killed when a node returns kKill\", \"[core][concurrency][pipeline]\") {\n // Arrange\n auto thread_pool = std::make_shared(kThreadPoolSize, kQueueCapacity);\n Pipeline pipeline(thread_pool);\n // ...\n\n // 2. Transformer: Sets a promise and returns kKill.\n pipeline.AddNode(\n Node::Transformer(2, [&kill_promise](int) -> NodeResult {\n kill_promise.set_value();\n return {.data = std::any{}, .control = ControlFlow::kKill};\n }));\n\n // 3. Consumer: Should never be executed.\n pipeline.AddNode(Node::Transformer(\n 3, [](int) { FAIL(\"This node should not execute.\"); }));\n\n // Act\n pipeline.RunCycle();\n REQUIRE(kill_future.wait_for(kTimeout) == std::future_status::ready);\n\n // Assert\n REQUIRE(pipeline.IsKilled());\n // ...\n}\n```\n\n#### 3. 타입 불일치에 대한 `AddNode` 오류 처리 검증\n\n이 액션은 파이프라인의 구성 시점 안전성 검사를 검증합니다. 개발자가 이전 노드의 출력 타입과 일치하지 않는 입력 타입을 가진 노드를 추가하려고 하면 `AddNode` 메서드는 오류를 반환해야 합니다. 이 테스트는 유효하지 않은 파이프라인이 구성되는 것을 막아 런타임 타입 오류를 방지합니다.\n\n**파일**: `tests/unit/concurrency/pipeline.cpp`\n```cpp\nTEST_CASE(\"Pipeline AddNode returns error on type mismatch\", \"[core][concurrency][pipeline]\") {\n // Arrange\n auto thread_pool =\n std::make_shared(kThreadPoolSize, kQueueCapacity);\n Pipeline pipeline(thread_pool);\n\n // Add a producer that returns an int.\n pipeline.AddNode(Node::Producer(1, [] { return 5; }));\n\n // Act: Try to add a transformer that expects a double.\n auto result2 = pipeline.AddNode(\n Node::Transformer(2, [](double) { return 1; }));\n\n // Assert\n REQUIRE(result2.has_value());\n REQUIRE(result2.value() == Pipeline::AddNodeError::kTypeMismatch);\n}\n```\n---\n### 단계 3: 작업 관리, 시작/정지 생명주기, 스레드 풀 상호작용에 대한 Scheduler 유닛 테스트.\n\n#### 1. 주기적 작업 실행 검증\n\n이 액션은 `Scheduler`의 핵심 목적인 지정된 주기로 작업을 실행하는 기능을 테스트합니다. 스케줄러가 시작되기 전에 각기 다른 간격을 가진 여러 작업을 추가한 다음, 고정된 시간 동안 스케줄러를 실행합니다. 각 작업이 대략적으로 올바른 횟수만큼 실행되었는지 검증하여 타이밍 및 `ThreadPool` 상호작용 로직을 확인합니다.\n\n**파일**: `tests/unit/concurrency/scheduler.cpp`\n```cpp\n#include \"core/concurrency/scheduler.hpp\"\n// ... other includes\n\nTEST_CASE(\"Scheduler runs tasks added before starting\", \"[scheduler]\") {\n auto thread_pool = std::make_shared(\n kTestThreadPoolSize, kTestThreadPoolQueueSize);\n core::concurrency::Scheduler scheduler(thread_pool);\n\n std::atomic counter10ms = 0;\n std::atomic counter20ms = 0;\n\n scheduler.AddTask([&counter10ms]() { counter10ms++; }, 10ms);\n scheduler.AddTask([&counter20ms]() { counter20ms++; }, 20ms);\n\n scheduler.Start(core::concurrency::Scheduler::ExecutionMode::kThreadPool);\n std::this_thread::sleep_for(45ms);\n scheduler.Stop();\n\n // 10ms task runs ~4 times, 20ms task runs ~2 times.\n CHECK(counter10ms.load() >= 3);\n CHECK(counter10ms.load() <= 5);\n CHECK(counter20ms.load() >= 1);\n CHECK(counter20ms.load() <= 3);\n}\n```\n\n#### 2. 상태 종속적 연산 검증\n\n이 액션은 `Scheduler`가 자신의 상태 머신을 올바르게 강제하는지 확인합니다. 특히 스케줄러의 실행 루프가 활성 상태인 동안에는 새 작업을 추가하거나 취소할 수 없음을 테스트합니다. 이는 경쟁 조건을 방지하고 내부 작업 목록이 안전하고 예측 가능한 상태(즉, 중지된 상태)에서만 수정되도록 보장합니다.\n\n**파일**: `tests/unit/concurrency/scheduler.cpp`\n```cpp\nTEST_CASE(\"Scheduler does not allow adding tasks while running\", \"[scheduler]\") {\n auto thread_pool = std::make_shared(\n kTestThreadPoolSize, kTestThreadPoolQueueSize);\n core::concurrency::Scheduler scheduler(thread_pool);\n\n scheduler.Start(core::concurrency::Scheduler::ExecutionMode::kThreadPool);\n\n std::atomic counter = 0;\n // Attempt to add a task while scheduler is running\n auto task_id = scheduler.AddTask([&counter]() { counter++; }, 10ms);\n\n REQUIRE_FALSE(task_id.has_value());\n\n std::this_thread::sleep_for(20ms);\n scheduler.Stop();\n\n REQUIRE(counter.load() == 0);\n}\n```\n\n#### 3. 작업 취소 및 생명주기 관리 검증\n\n이 액션은 전체 시작-정지-취소-재시작 생명주기를 검증합니다. 작업이 올바르게 실행되고, 스케줄러가 중지될 수 있으며, 그 후 작업이 성공적으로 취소될 수 있고, 스케줄러를 다시 시작했을 때 취소된 작업이 더 이상 실행되지 않음을 확인합니다. 이는 작업을 동적으로 재구성해야 할 수 있는 장기 실행 애플리케이션에 매우 중요합니다.\n\n**파일**: `tests/unit/concurrency/scheduler.cpp`\n```cpp\nTEST_CASE(\"Scheduler allows cancelling a task after stopping\", \"[scheduler]\") {\n auto thread_pool = std::make_shared(\n kTestThreadPoolSize, kTestThreadPoolQueueSize);\n core::concurrency::Scheduler scheduler(thread_pool);\n\n std::atomic counter = 0;\n auto task_id_opt = scheduler.AddTask([&counter]() { counter++; }, 10ms);\n REQUIRE(task_id_opt.has_value());\n auto task_id = *task_id_opt;\n\n scheduler.Start(core::concurrency::Scheduler::ExecutionMode::kThreadPool);\n std::this_thread::sleep_for(55ms);\n scheduler.Stop();\n\n // Wait for the scheduler thread to fully stop and update is_running_\n std::this_thread::sleep_for(20ms);\n\n scheduler.CancelTask(task_id);\n\n // Restarting the scheduler should not run the cancelled task.\n counter = 0;\n scheduler.Start(core::concurrency::Scheduler::ExecutionMode::kThreadPool);\n std::this_thread::sleep_for(30ms);\n scheduler.Stop();\n\n REQUIRE(counter.load() == 0);\n}\n```\n---\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n- 주요 검증 방법은 전체 프로젝트의 유닛 테스트를 컴파일하고 실행하는 것입니다. CMake 기반 빌드 시스템을 가정할 때, 다음 명령어들은 프로젝트를 빌드하고 테스트 러너를 실행하여 새로 생성된 테스트 케이스를 자동으로 찾아 실행합니다.\n\n```bash\n# 1. 빌드 디렉터리로 이동합니다 (없으면 생성).\nmkdir -p build && cd build\n\n# 2. CMake로 프로젝트를 구성합니다.\ncmake ..\n\n# 3. 테스트 실행 파일을 포함하여 프로젝트를 빌드합니다.\ncmake --build .\n\n# 4. 유닛 테스트를 실행합니다. 실행 파일 이름은 CMakeLists.txt에 따라 다를 수 있습니다.\n# 테스트 러너(Catch2)가 결과를 콘솔에 출력합니다.\n./tests/unit/cpp_core_unit_tests\n```\n\n### 4.2. 예상 결과\n\n- 테스트 러너는 새 파일에 정의된 모든 테스트 케이스를 실행합니다. 검증이 성공하면 모든 단언(assertion)이 실패 없이 통과했음을 보여줍니다. 콘솔 출력은 다음 예시와 유사해야 하며, 모든 `[core][concurrency][pipeline]`, `[core][concurrency][pipeline][node]`, `[scheduler]` 테스트가 통과했음을 나타냅니다.\n\n```\n===============================================================================\n모든 테스트 통과 (YY개의 테스트 케이스, XX개의 단언)\n```","파이프라인이 올바르게 실행되고, 노드가 타입을 안전하게 처리하며, 스케줄러가 주기적인 작업을 예상대로 관리하는지 보장하는 유닛 테스트 스위트",[2214,2217,2219],{"_24":2215,"_83":39,"_84":2216,"_85":61},"생산자/변환자 생성, 타입 안전성, 제어 흐름 결과에 대한 Node 유닛 테스트",31,{"_24":2218,"_83":39,"_84":2216,"_85":88},"선형 실행, 오류 처리(타입 불일치), 종료 신호 전파에 대한 Pipeline 유닛 테스트",{"_24":2220,"_83":39,"_84":2216,"_85":91},"작업 관리, 시작/중지 생명주기, 스레드 풀과의 상호 작용에 대한 Scheduler 유닛 테스트","상위 수준 동시성 프레임워크 컴포넌트(`Node`, `Pipeline`, `Scheduler`)를 검증",{"_22":2223,"_24":2224,"_75":2225,"_77":2226,"_79":2227,"_51":2241,"_42":99},"task-1751727180402","종단 간 SLAM 시나리오 테스트","# 작업: End-to-End SLAM 시나리오 테스트\n\n> **에픽**: 포괄적인 시스템 검증\n\n## 1. 작업 정의\n\n### 1.1. 목표\n- **목표**: 실제와 유사한 멀티 파이프라인 애플리케이션을 시뮬레이션하여 전체 프레임워크를 검증합니다.\n- **근거**: 이 End-to-End(E2E) 테스트는 핵심 프레임워크 아키텍처에 대한 최종 검증 역할을 합니다. 이 테스트는 모든 기본 구성 요소(`ThreadPool`, `Scheduler`, `Pipeline`, `Node`)가 현실적인 동시성 워크로드 하에서 올바르게 상호 운용되는지 확인합니다. 여러 데이터 스트림(IMU, 카메라)을 각기 다른 주기로 시뮬레이션함으로써, 복잡한 비동기 워크플로우를 관리하는 시스템의 안정성, 스레드 안전성, 그리고 능력을 증명하며, 이는 핵심 프로젝트 목표를 달성하는 데 기여합니다.\n\n### 1.2. 결과물\n- **예상 결과**: 스케줄러를 통해 여러 파이프라인을 각기 다른 주기로 실행하고, 그 집합적인 동작을 검증하는 단일의 포괄적인 End-to-End 테스트.\n- **사양**:\n - `tests/e2e/slam_scenario.cpp` 파일에 `TEST_CASE` 블록을 생성합니다.\n - 테스트는 `core::concurrency::ThreadPool`, `core::concurrency::Scheduler`, `core::concurrency::Pipeline`을 인스턴스화하여 사용합니다.\n - IMU, 카메라, 최적화 데이터 흐름을 시뮬레이션하기 위해 세 개의 개별 `Pipeline` 인스턴스를 생성합니다.\n - 각 파이프라인은 모의 `core::concurrency::pipeline::Node` 객체로 채워집니다.\n - 비동기 결과는 `std::promise`와 `std::future`를 사용하여 캡처합니다.\n- **결과 파일 구조**\n```bash\n# ./\n# └── tests/\n# └── e2e/\n# └── slam_scenario.cpp <-- 신규\n```\n\n- **프로세스 흐름도**\n```mermaid\n%%{ init: { \"flowchart\": { \"htmlLabels\": true } } }%%\nflowchart TD\n subgraph \"TestSetup\"\n A1[\"ThreadPool 및 Scheduler 인스턴스화\"]\n A2[\"모의 데이터 구조체 정의\"]\n A3[\"결과용 std::promise/future 쌍 생성\"]\n A4[\"IMU 파이프라인 생성 및 구성\"]\n A5[\"카메라 파이프라인 생성 및 구성\"]\n A6[\"최적화 파이프라인 생성 및 구성\"]\n A7[\"Scheduler에 모든 파이프라인 등록\"]\n A1 --> A7\n A2 --> A4 & A5 & A6\n A3 --> A4 & A5 & A6\n end\n\n subgraph \"TestExecution\"\n B1[\"백그라운드 스레드에서 Scheduler 시작\"]\n B2[\"메인 스레드는 테스트 시간 동안 대기\"]\n B3[\"Scheduler 정상적으로 중지\"]\n end\n \n subgraph \"PipelinesExecution\"\n C1[\"Scheduler가 100Hz로 IMU Pipeline.RunCycle() 트리거\"]\n C2[\"Scheduler가 ~30Hz로 Camera Pipeline.RunCycle() 트리거\"]\n C3[\"Scheduler가 2Hz로 Optimization Pipeline.RunCycle() 트리거\"]\n C1 --> D1(\"IMU 파이프라인이 데이터 처리 후 promise 이행\")\n C2 --> D2(\"카메라 파이프라인이 데이터 처리 후 promise 이행\")\n C3 --> D3(\"최적화 파이프라인이 데이터 처리 후 promise 이행\")\n end\n\n subgraph \"Verification\"\n E1[\"future가 준비될 때까지 대기\"]\n E2[\"future.get()으로 결과 검색\"]\n E3[\"검색된 데이터가 올바른지 검증\"]\n end\n \n TestSetup --> TestExecution\n TestExecution --> Verification\n B1 --> PipelinesExecution\n PipelinesExecution --> Verification\n```\n\n### 1.3. 완료 조건\n\n개발자는 이 작업을 완료로 표시하기 위해 다음 항목들을 완수해야 합니다. 이는 상위 수준의 체크리스트이며, 각 항목에 대한 상세 구현은 3절에 기술되어 있습니다.\n\n- [ ] `ThreadPool`과 `Scheduler` 설정\n- [ ] 여러 `Pipeline` 인스턴스 생성 (IMU, 카메라, 최적화)\n- [ ] 모의 `Node` 객체로 파이프라인 채우기\n- [ ] `std::promise`와 `std::future`를 사용하여 비동기 결과 캡처\n- [ ] 파이프라인 `RunCycle` 호출을 `Scheduler`의 작업으로 스케줄링\n- [ ] 모든 파이프라인의 최종 결과 검증\n\n## 2. 기술적 배경\n\n### 2.1. 아키텍처 개요\n\n- **아키텍처 스타일**: 모듈형 코어 프레임워크\n- **관련 주요 구성 요소**:\n - **`ThreadPool`**: 기본적인 동시성 엔진 역할을 합니다. `Scheduler`와 개별 `Pipeline`에 의해 스케줄링된 모든 비동기 작업을 실행할 워커 스레드를 제공합니다.\n - **`Scheduler`**: 작업의 주기적 실행을 관리합니다. 이 테스트에서는 각 파이프라인의 `RunCycle` 메서드를 지정된 주기(예: IMU 100Hz, 카메라 30Hz)로 호출하는 책임을 집니다.\n - **`Pipeline`**: 데이터 처리 `Node`들의 시퀀스를 조율합니다. 독립적인 데이터 흐름을 모델링하기 위해 세 개의 개별 `Pipeline` 인스턴스를 사용하여, 프레임워크가 동시적인 다중 스트림 처리를 관리할 수 있는 능력을 보여줍니다.\n - **`pipeline::Node`**: 단일 계산 단계를 나타냅니다. 모의 `Node`는 데이터 생성(예: `ImuData` 생성), 변환, 소비를 시뮬레이션하여, 테스트가 복잡한 알고리즘 대신 프레임워크의 메커니즘에 집중할 수 있도록 합니다.\n\n### 2.2. 영향받는 파일\n\n이 작업을 완료하기 위해 다음 파일이 생성되거나 수정됩니다.\n\n- `tests/e2e/slam_scenario.cpp`\n\n## 3. 구현 명세\n\n> **참고**: 아래의 각 `단계`는 **완료 조건**의 항목에 해당합니다. 각 `단계`는 일련의 세부적인 `액션`으로 나뉩니다. 각 `액션`에 대해 제목, 명확한 설명('무엇을', '왜'), 그리고 정확한 코드 구현을 제공해야 합니다.\n\n---\n\n### 1단계: `ThreadPool`과 `Scheduler` 설정\n\n#### 1. 핵심 동시성 구성 요소 인스턴스화\n\n이 액션은 전체 테스트의 실행 컨텍스트를 구축합니다. 워커 스레드 집합을 제공하기 위해 `ThreadPool`을 생성하고, `ThreadPool`을 실행 백엔드로 사용하는 `Scheduler`를 인스턴스화합니다. 이러한 구성은 상위 수준의 구성 요소가 공유된 하위 수준 실행 엔진에서 작업을 조율하는 핵심 아키텍처 패턴을 반영합니다.\n\n**파일**: `tests/e2e/slam_scenario.cpp`\n\n```cpp\n#include \n\n// ... other includes\n#include \"core/concurrency/scheduler.hpp\"\n#include \"core/concurrency/thread_pool.hpp\"\n\nusing core::concurrency::Scheduler;\nusing core::concurrency::ThreadPool;\n// ... other usings\n\nnamespace {\n// ... test configuration constants\n} // namespace\n\nTEST_CASE(\"SLAM E2E Scenario using official APIs\", \"[e2e][slam_scenario]\") {\n // 1. ARRANGE\n auto thread_pool = std::make_shared(kTestThreadPoolSize,\n kTestThreadPoolQueueSize);\n Scheduler scheduler(thread_pool);\n\n // ... rest of the test\n}\n```\n\n---\n\n### 2단계: 여러 `Pipeline` 인스턴스 생성 (IMU, 카메라, 최적화)\n\n#### 1. 모의 데이터 구조체 정의\n\n파이프라인을 통해 흐르는 데이터를 시뮬레이션하기 위해 간단한 모의 데이터 구조체가 필요합니다. 이 구조체들은 실제 SLAM 애플리케이션에서 노드 간에 전달될 다양한 유형의 데이터(예: 원시 센서 판독값, 처리된 결과)를 나타냅니다. 이를 정의함으로써 파이프라인의 타입-세이프 템플릿 인스턴스화를 명확하고 검증 가능하게 만듭니다.\n\n**파일**: `tests/e2e/slam_scenario.cpp`\n\n```cpp\nnamespace {\n\n// ... test configuration constants\n\n// --- Mock Data Structures for intra-pipeline data passing ---\nstruct ImuData { int id; };\nstruct ProcessedImu { int imu_id; };\nstruct FrameData { int id; };\nstruct Features { int feature_count; };\nstruct Trigger { bool run; };\nstruct OptimizationResult { bool success; };\n\n} // namespace\n\nTEST_CASE(\"SLAM E2E Scenario using official APIs\", \"[e2e][slam_scenario]\") {\n // ...\n}\n```\n\n#### 2. 파이프라인 객체 인스턴스화\n\n공유 `ThreadPool`과 연관된 세 개의 개별 `Pipeline` 인스턴스를 생성합니다. 이 설정은 다중 센서 시스템의 주요 요구 사항인, 서로 다른 데이터 소스(IMU, 카메라)와 관련 작업(최적화)에 대해 독립적이면서도 동시적인 처리 흐름을 실행할 수 있는 능력을 모델링합니다.\n\n**파일**: `tests/e2e/slam_scenario.cpp`\n\n```cpp\nTEST_CASE(\"SLAM E2E Scenario using official APIs\", \"[e2e][slam_scenario]\") {\n // ... scheduler setup\n\n // ... promises setup\n\n // --- IMU Pipeline (Producer -> Transformer -> Consumer) ---\n auto imu_pipeline = std::make_shared(thread_pool);\n // ... add nodes to imu_pipeline\n\n // --- Camera Pipeline (Producer -> Transformer -> Consumer) ---\n auto camera_pipeline = std::make_shared(thread_pool);\n // ... add nodes to camera_pipeline\n\n // --- Optimization Pipeline (Producer -> Transformer -> Consumer) ---\n auto optimization_pipeline = std::make_shared(thread_pool);\n // ... add nodes to optimization_pipeline\n\n // ...\n}\n```\n\n---\n\n### 3단계: 모의 `Node` 객체로 파이프라인 채우기\n\n#### 1. 모든 파이프라인에 노드 구현 및 추가\n\n각 파이프라인은 생산자-변환자-소비자 패턴을 시뮬레이션하는 노드 시퀀스로 구성됩니다. `Node::Producer`는 초기 데이터를 생성합니다. `Node::Transformer`는 이전 노드의 데이터를 처리합니다. 각 시퀀스의 마지막 노드는 소비자 역할을 하여 최종 결과를 캡처하고 `ControlFlow::kKill`을 사용하여 파이프라인에 사이클 종료 신호를 보냅니다. 이 액션은 이전에 생성된 파이프라인 뼈대에 각각의 특정 처리 로직을 채워 넣습니다.\n\n**파일**: `tests/e2e/slam_scenario.cpp`\n\n```cpp\nTEST_CASE(\"SLAM E2E Scenario using official APIs\", \"[e2e][slam_scenario]\") {\n // ... scheduler and promises setup ...\n\n // --- IMU Pipeline (Producer -> Transformer -> Consumer) ---\n auto imu_pipeline = std::make_shared(thread_pool);\n imu_pipeline->AddNode(\n Node::Producer(0, []() { return ImuData{1}; }));\n imu_pipeline->AddNode(Node::Transformer(\n 1, [](ImuData data) { return ProcessedImu{data.id}; }));\n imu_pipeline->AddNode(Node::Transformer(\n 2, [imu_promise](ProcessedImu data) -> NodeResult {\n imu_promise->set_value(data);\n return {.data = std::any{}, .control = ControlFlow::kKill};\n }));\n\n // --- Camera Pipeline (Producer -> Transformer -> Consumer) ---\n auto camera_pipeline = std::make_shared(thread_pool);\n camera_pipeline->AddNode(\n Node::Producer(0, []() { return FrameData{100}; }));\n camera_pipeline->AddNode(Node::Transformer(\n 1, [](FrameData) { return Features{5}; }));\n camera_pipeline->AddNode(Node::Transformer(\n 2, [camera_promise](Features data) -> NodeResult {\n camera_promise->set_value(data);\n return {.data = std::any{}, .control = ControlFlow::kKill};\n }));\n\n // --- Optimization Pipeline (Producer -> Transformer -> Consumer) ---\n auto optimization_pipeline = std::make_shared(thread_pool);\n optimization_pipeline->AddNode(\n Node::Producer(0, []() { return Trigger{true}; }));\n optimization_pipeline->AddNode(Node::Transformer(\n 1, [](Trigger) { return OptimizationResult{true}; }));\n optimization_pipeline->AddNode(Node::Transformer(\n 2, [optimization_promise](OptimizationResult data) -> NodeResult {\n optimization_promise->set_value(data);\n return {.data = std::any{}, .control = ControlFlow::kKill};\n }));\n \n // ... rest of test\n}\n```\n\n---\n\n### 4단계: `std::promise`와 `std::future`를 사용하여 비동기 결과 캡처\n\n#### 1. Promise/Future 쌍 설정\n\n비동기 파이프라인 실행의 출력을 검증하기 위해 `std::promise`와 `std::future` 쌍을 설정합니다. `promise`는 각 파이프라인의 마지막 노드로 전달되고, `future`는 메인 테스트 스레드가 보유합니다. 이는 비동기 작업의 결과를 대기 중인 스레드로 다시 전달하는 표준 C++ 메커니즘입니다.\n\n**파일**: `tests/e2e/slam_scenario.cpp`\n\n```cpp\n#include \n// ...\n\nTEST_CASE(\"SLAM E2E Scenario using official APIs\", \"[e2e][slam_scenario]\") {\n // ... scheduler setup ...\n\n // --- Promises to capture final results from each pipeline ---\n auto imu_promise = std::make_shared>();\n std::future imu_future = imu_promise->get_future();\n\n auto camera_promise = std::make_shared>();\n std::future camera_future = camera_promise->get_future();\n\n auto optimization_promise =\n std::make_shared>();\n std::future optimization_future =\n optimization_promise->get_future();\n\n // ... pipeline setup ...\n}\n```\n\n---\n\n### 5단계: 파이프라인 `RunCycle` 호출을 `Scheduler`의 작업으로 스케줄링\n\n#### 1. Scheduler에 파이프라인 실행 주기 등록\n\n이 액션은 `Scheduler`를 `Pipeline`에 연결합니다. 각 파이프라인의 `RunCycle` 메서드는 람다로 래핑되어 원하는 실행 주기와 함께 `Scheduler`에 작업으로 등록됩니다. 이는 스케줄러에게 주기적으로 `ThreadPool`에 작업을 큐잉하여 각 파이프라인에 대한 새로운 처리 사이클을 시작하도록 지시하며, 이는 센서의 연속적인 작동을 시뮬레이션합니다.\n\n**파일**: `tests/e2e/slam_scenario.cpp`\n\n```cpp\nTEST_CASE(\"SLAM E2E Scenario using official APIs\", \"[e2e][slam_scenario]\") {\n // ... pipeline setup ...\n\n // --- Add pipeline tasks to the scheduler ---\n scheduler.AddTask([imu_pipeline]() { imu_pipeline->RunCycle(); }, kImuPeriod);\n scheduler.AddTask([camera_pipeline]() { camera_pipeline->RunCycle(); },\n kCameraPeriod);\n scheduler.AddTask(\n [optimization_pipeline]() { optimization_pipeline->RunCycle(); },\n kOptimizationPeriod);\n\n // 2. ACT\n // ...\n}\n```\n\n---\n\n### 6단계: 모든 파이프라인의 최종 결과 검증\n\n#### 1. 테스트 시나리오 실행 및 결과 검증\n\n테스트가 \"Act(실행)\" 및 \"Assert(검증)\" 단계에 들어갑니다. 스케줄러는 논블로킹(`kThreadPool` 모드)으로 시작되고, 메인 스레드는 일정 시간 동안 일시 중지하여 파이프라인이 동시에 실행되도록 합니다. 그 후 스케줄러를 중지합니다. 메인 스레드는 `future`가 준비될 때까지 기다렸다가 결과를 검색하고, `catch2` 매크로를 사용하여 결과가 수신되었는지 `REQUIRE`하고 그 값이 올바른지 `CHECK`합니다. 이 마지막 단계는 전체 시스템이 예상대로 작동했음을 검증합니다.\n\n**파일**: `tests/e2e/slam_scenario.cpp`\n\n```cpp\nTEST_CASE(\"SLAM E2E Scenario using official APIs\", \"[e2e][slam_scenario]\") {\n // ... 1. ARRANGE ...\n\n // 2. ACT\n scheduler.Start(Scheduler::ExecutionMode::kThreadPool);\n std::this_thread::sleep_for(kTestDuration);\n scheduler.Stop();\n std::this_thread::sleep_for(std::chrono::milliseconds(100));\n\n // 3. ASSERT\n REQUIRE(imu_future.wait_for(std::chrono::seconds(1)) ==\n std::future_status::ready);\n REQUIRE(camera_future.wait_for(std::chrono::seconds(1)) ==\n std::future_status::ready);\n REQUIRE(optimization_future.wait_for(std::chrono::seconds(1)) ==\n std::future_status::ready);\n\n auto imu_result = imu_future.get();\n CHECK(imu_result.imu_id == 1);\n\n auto camera_result = camera_future.get();\n CHECK(camera_result.feature_count == 5);\n\n auto optimization_result = optimization_future.get();\n CHECK(optimization_result.success == true);\n}\n```\n\n## 4. 검증 프로토콜\n\n### 4.1. 검증 절차\n\n- 구현을 검증하려면, 테스트 스위트를 컴파일하고 `ctest`를 사용하여 실행합니다. 테스트 실행 파일은 표준 빌드 프로세스의 일부로 생성됩니다.\n\n```bash\n# 1. 빌드 디렉토리로 이동\ncd build\n\n# 2. 프로젝트 구성 및 빌드 (아직 안 했다면)\ncmake ..\nmake\n\n# 3. 테스트 스위트 실행, 특히 e2e 테스트를 대상으로 함\nctest -R \"SLAM E2E Scenario\"\n```\n\n### 4.2. 예상 결과\n\n- `ctest`가 \"SLAM E2E Scenario\" 테스트가 오류 없이 통과했다고 보고하면 검증이 성공한 것입니다.\n\n```\n Start 1: e2e.slam_scenario\n1/1 Test #1: e2e.slam_scenario ................ Passed 2.12 sec\n\n100% tests passed, 0 tests failed out of 1\n\nTotal Test time (real) = 2.13 sec\n```","스케줄러를 통해 여러 파이프라인을 다양한 주기로 실행하고 집합적인 동작을 검증하는 단일의 포괄적인 종단 간 테스트",[2228,2231,2233,2235,2237,2239],{"_24":2229,"_83":39,"_84":2230,"_85":61},"`ThreadPool`과 `Scheduler` 설정",32,{"_24":2232,"_83":39,"_84":2230,"_85":88},"여러 `Pipeline` 인스턴스(IMU, 카메라, 최적화) 생성",{"_24":2234,"_83":39,"_84":2230,"_85":91},"모의 `Node` 객체로 파이프라인 채우기",{"_24":2236,"_83":39,"_84":2230,"_85":94},"비동기 결과를 캡처하기 위해 `std::promise`와 `std::future` 사용",{"_24":2238,"_83":39,"_84":2230,"_85":97},"파이프라인 `RunCycle` 호출을 `Scheduler`의 작업으로 스케줄링",{"_24":2240,"_83":39,"_84":2230,"_85":176},"모든 파이프라인의 최종 결과 검증","실제 환경의 다중 파이프라인 애플리케이션을 시뮬레이션하여 전체 프레임워크를 검증",[2243,2245],{"_28":29,"_26":2244},799000,{"_28":482,"_26":1674},[],{"_22":2248,"_24":1679,"_26":2244,"_28":29,"_30":31,"_32":1675,"_34":1676,"_36":2249,"_38":39,"_40":2250,"_484":2474},"44cddddb-7e9d-4cbc-93b7-c3a7dae53154","2025-07-05T14:58:55.583Z",{"_22":1675,"_24":1679,"_42":1680,"_44":31,"_45":46,"_47":1681,"_49":1682,"_51":1683,"_53":1684,"_55":39,"_56":1685,"_58":59,"_60":61,"_62":61,"_63":2251,"_70":2252,"_478":2242},[1687,1688,1689,1690],[2253,2260,2267,2275,2281,2289,2294,2301,2307,2314,2320,2327,2333,2342,2349,2356,2364,2372,2377,2383,2388,2395,2402,2409,2416,2423,2431,2437,2445,2450,2456,2461,2466],{"_22":1693,"_24":1694,"_75":1695,"_77":1696,"_79":2254,"_51":1708,"_42":99},[2255,2256,2257,2258,2259],{"_24":1699,"_83":39,"_84":61,"_85":61},{"_24":1701,"_83":39,"_84":61,"_85":88},{"_24":1703,"_83":39,"_84":61,"_85":91},{"_24":1705,"_83":39,"_84":61,"_85":94},{"_24":1707,"_83":39,"_84":61,"_85":97},{"_22":1710,"_24":1711,"_75":1712,"_77":1713,"_79":2261,"_51":1725,"_42":99},[2262,2263,2264,2265,2266],{"_24":1716,"_83":39,"_84":88,"_85":61},{"_24":1718,"_83":39,"_84":88,"_85":88},{"_24":1720,"_83":39,"_84":88,"_85":91},{"_24":1722,"_83":39,"_84":88,"_85":94},{"_24":1724,"_83":39,"_84":88,"_85":97},{"_22":1727,"_24":1728,"_75":1729,"_77":1730,"_79":2268,"_51":1744,"_42":99},[2269,2270,2271,2272,2273,2274],{"_24":1733,"_83":39,"_84":91,"_85":61},{"_24":1735,"_83":39,"_84":91,"_85":88},{"_24":1737,"_83":39,"_84":91,"_85":91},{"_24":1739,"_83":39,"_84":91,"_85":94},{"_24":1741,"_83":39,"_84":91,"_85":97},{"_24":1743,"_83":39,"_84":91,"_85":176},{"_22":1746,"_24":1747,"_75":1748,"_77":1749,"_79":2276,"_51":1759,"_42":99},[2277,2278,2279,2280],{"_24":1752,"_83":39,"_84":94,"_85":61},{"_24":1754,"_83":39,"_84":94,"_85":88},{"_24":1756,"_83":39,"_84":94,"_85":91},{"_24":1758,"_83":39,"_84":94,"_85":94},{"_22":1761,"_24":1762,"_75":1763,"_77":1764,"_79":2282,"_51":1778,"_42":99},[2283,2284,2285,2286,2287,2288],{"_24":1767,"_83":39,"_84":97,"_85":61},{"_24":1769,"_83":39,"_84":97,"_85":88},{"_24":1771,"_83":39,"_84":97,"_85":91},{"_24":1773,"_83":39,"_84":97,"_85":94},{"_24":1775,"_83":39,"_84":97,"_85":97},{"_24":1777,"_83":39,"_84":97,"_85":176},{"_22":1780,"_24":1781,"_75":1782,"_77":1783,"_79":2290,"_51":1791,"_42":99},[2291,2292,2293],{"_24":1786,"_83":39,"_84":176,"_85":61},{"_24":1788,"_83":39,"_84":176,"_85":88},{"_24":1790,"_83":39,"_84":176,"_85":91},{"_22":1793,"_24":1794,"_75":1795,"_77":1796,"_79":2295,"_51":1808,"_42":99},[2296,2297,2298,2299,2300],{"_24":1799,"_83":39,"_84":192,"_85":61},{"_24":1801,"_83":39,"_84":192,"_85":88},{"_24":1803,"_83":39,"_84":192,"_85":91},{"_24":1805,"_83":39,"_84":192,"_85":94},{"_24":1807,"_83":39,"_84":192,"_85":97},{"_22":1810,"_24":1811,"_75":1812,"_77":1813,"_79":2302,"_51":1823,"_42":99},[2303,2304,2305,2306],{"_24":1816,"_83":39,"_84":212,"_85":61},{"_24":1818,"_83":39,"_84":212,"_85":88},{"_24":1820,"_83":39,"_84":212,"_85":91},{"_24":1822,"_83":39,"_84":212,"_85":94},{"_22":1825,"_24":1826,"_75":1827,"_77":1828,"_79":2308,"_51":1840,"_42":99},[2309,2310,2311,2312,2313],{"_24":1831,"_83":39,"_84":230,"_85":61},{"_24":1833,"_83":39,"_84":230,"_85":88},{"_24":1835,"_83":39,"_84":230,"_85":91},{"_24":1837,"_83":39,"_84":230,"_85":94},{"_24":1839,"_83":39,"_84":230,"_85":97},{"_22":1842,"_24":1843,"_75":1844,"_77":1845,"_79":2315,"_51":1855,"_42":99},[2316,2317,2318,2319],{"_24":1848,"_83":39,"_84":248,"_85":61},{"_24":1850,"_83":39,"_84":248,"_85":88},{"_24":1852,"_83":39,"_84":248,"_85":91},{"_24":1854,"_83":39,"_84":248,"_85":94},{"_22":1857,"_24":1858,"_75":1859,"_77":1860,"_79":2321,"_51":1872,"_42":99},[2322,2323,2324,2325,2326],{"_24":1863,"_83":39,"_84":266,"_85":61},{"_24":1865,"_83":39,"_84":266,"_85":88},{"_24":1867,"_83":39,"_84":266,"_85":91},{"_24":1869,"_83":39,"_84":266,"_85":94},{"_24":1871,"_83":39,"_84":266,"_85":97},{"_22":1874,"_24":1875,"_75":1876,"_77":1877,"_79":2328,"_51":1887,"_42":99},[2329,2330,2331,2332],{"_24":1880,"_83":39,"_84":284,"_85":61},{"_24":1882,"_83":39,"_84":284,"_85":88},{"_24":1884,"_83":39,"_84":284,"_85":91},{"_24":1886,"_83":39,"_84":284,"_85":94},{"_22":1889,"_24":1890,"_75":1891,"_77":1892,"_79":2334,"_51":1908,"_42":99},[2335,2336,2337,2338,2339,2340,2341],{"_24":1895,"_83":39,"_84":302,"_85":61},{"_24":1897,"_83":39,"_84":302,"_85":88},{"_24":1899,"_83":39,"_84":302,"_85":91},{"_24":1901,"_83":39,"_84":302,"_85":94},{"_24":1903,"_83":39,"_84":302,"_85":97},{"_24":1905,"_83":39,"_84":302,"_85":176},{"_24":1907,"_83":39,"_84":302,"_85":192},{"_22":1910,"_24":1911,"_75":1912,"_77":1913,"_79":2343,"_51":1925,"_42":99},[2344,2345,2346,2347,2348],{"_24":1916,"_83":39,"_84":320,"_85":61},{"_24":1918,"_83":39,"_84":320,"_85":88},{"_24":1920,"_83":39,"_84":320,"_85":91},{"_24":1922,"_83":39,"_84":320,"_85":94},{"_24":1924,"_83":39,"_84":320,"_85":97},{"_22":1927,"_24":1928,"_75":1929,"_77":1930,"_79":2350,"_51":1942,"_42":99},[2351,2352,2353,2354,2355],{"_24":1933,"_83":39,"_84":338,"_85":61},{"_24":1935,"_83":39,"_84":338,"_85":88},{"_24":1937,"_83":39,"_84":338,"_85":91},{"_24":1939,"_83":39,"_84":338,"_85":94},{"_24":1941,"_83":39,"_84":338,"_85":97},{"_22":1944,"_24":1945,"_75":1946,"_77":1947,"_79":2357,"_51":1961,"_42":99},[2358,2359,2360,2361,2362,2363],{"_24":1950,"_83":39,"_84":356,"_85":61},{"_24":1952,"_83":39,"_84":356,"_85":88},{"_24":1954,"_83":39,"_84":356,"_85":91},{"_24":1956,"_83":39,"_84":356,"_85":94},{"_24":1958,"_83":39,"_84":356,"_85":97},{"_24":1960,"_83":39,"_84":356,"_85":176},{"_22":1963,"_24":1964,"_75":1965,"_77":1966,"_79":2365,"_51":1980,"_42":99},[2366,2367,2368,2369,2370,2371],{"_24":1969,"_83":39,"_84":374,"_85":61},{"_24":1971,"_83":39,"_84":374,"_85":88},{"_24":1973,"_83":39,"_84":374,"_85":91},{"_24":1975,"_83":39,"_84":374,"_85":94},{"_24":1977,"_83":39,"_84":374,"_85":97},{"_24":1979,"_83":39,"_84":374,"_85":176},{"_22":1982,"_24":1983,"_75":1984,"_77":1985,"_79":2373,"_51":1993,"_42":99},[2374,2375,2376],{"_24":1988,"_83":39,"_84":392,"_85":61},{"_24":1990,"_83":39,"_84":392,"_85":88},{"_24":1992,"_83":39,"_84":392,"_85":91},{"_22":1995,"_24":1996,"_75":1997,"_77":1998,"_79":2378,"_51":2008,"_42":99},[2379,2380,2381,2382],{"_24":2001,"_83":39,"_84":410,"_85":61},{"_24":2003,"_83":39,"_84":410,"_85":88},{"_24":2005,"_83":39,"_84":410,"_85":91},{"_24":2007,"_83":39,"_84":410,"_85":94},{"_22":2010,"_24":2011,"_75":2012,"_77":2013,"_79":2384,"_51":2021,"_42":99},[2385,2386,2387],{"_24":2016,"_83":39,"_84":428,"_85":61},{"_24":2018,"_83":39,"_84":428,"_85":88},{"_24":2020,"_83":39,"_84":428,"_85":91},{"_22":2023,"_24":2024,"_75":2025,"_77":2026,"_79":2389,"_51":2038,"_42":99},[2390,2391,2392,2393,2394],{"_24":2029,"_83":39,"_84":446,"_85":61},{"_24":2031,"_83":39,"_84":446,"_85":88},{"_24":2033,"_83":39,"_84":446,"_85":91},{"_24":2035,"_83":39,"_84":446,"_85":94},{"_24":2037,"_83":39,"_84":446,"_85":97},{"_22":2040,"_24":2041,"_75":2042,"_77":2043,"_79":2396,"_51":2055,"_42":99},[2397,2398,2399,2400,2401],{"_24":2046,"_83":39,"_84":466,"_85":61},{"_24":2048,"_83":39,"_84":466,"_85":88},{"_24":2050,"_83":39,"_84":466,"_85":91},{"_24":2052,"_83":39,"_84":466,"_85":94},{"_24":2054,"_83":39,"_84":466,"_85":97},{"_22":2057,"_24":2058,"_75":2059,"_77":2060,"_79":2403,"_51":2072,"_42":99},[2404,2405,2406,2407,2408],{"_24":2063,"_83":39,"_84":1477,"_85":61},{"_24":2065,"_83":39,"_84":1477,"_85":88},{"_24":2067,"_83":39,"_84":1477,"_85":91},{"_24":2069,"_83":39,"_84":1477,"_85":94},{"_24":2071,"_83":39,"_84":1477,"_85":97},{"_22":2074,"_24":2075,"_75":2076,"_77":2077,"_79":2410,"_51":2089,"_42":99},[2411,2412,2413,2414,2415],{"_24":2080,"_83":39,"_84":1493,"_85":61},{"_24":2082,"_83":39,"_84":1493,"_85":88},{"_24":2084,"_83":39,"_84":1493,"_85":91},{"_24":2086,"_83":39,"_84":1493,"_85":94},{"_24":2088,"_83":39,"_84":1493,"_85":97},{"_22":2091,"_24":2092,"_75":2093,"_77":2094,"_79":2417,"_51":2107,"_42":99},[2418,2419,2420,2421,2422],{"_24":2097,"_83":39,"_84":2098,"_85":61},{"_24":2100,"_83":39,"_84":2098,"_85":88},{"_24":2102,"_83":39,"_84":2098,"_85":91},{"_24":2104,"_83":39,"_84":2098,"_85":94},{"_24":2106,"_83":39,"_84":2098,"_85":97},{"_22":2109,"_24":2110,"_75":2111,"_77":2112,"_79":2424,"_51":2127,"_42":99},[2425,2426,2427,2428,2429,2430],{"_24":2115,"_83":39,"_84":2116,"_85":61},{"_24":2118,"_83":39,"_84":2116,"_85":88},{"_24":2120,"_83":39,"_84":2116,"_85":91},{"_24":2122,"_83":39,"_84":2116,"_85":94},{"_24":2124,"_83":39,"_84":2116,"_85":97},{"_24":2126,"_83":39,"_84":2116,"_85":176},{"_22":2129,"_24":2130,"_75":2131,"_77":2132,"_79":2432,"_51":2143,"_42":99},[2433,2434,2435,2436],{"_24":2135,"_83":39,"_84":2136,"_85":61},{"_24":2138,"_83":39,"_84":2136,"_85":88},{"_24":2140,"_83":39,"_84":2136,"_85":91},{"_24":2142,"_83":39,"_84":2136,"_85":94},{"_22":2145,"_24":2146,"_75":2147,"_77":2148,"_79":2438,"_51":2163,"_42":99},[2439,2440,2441,2442,2443,2444],{"_24":2151,"_83":39,"_84":2152,"_85":61},{"_24":2154,"_83":39,"_84":2152,"_85":88},{"_24":2156,"_83":39,"_84":2152,"_85":91},{"_24":2158,"_83":39,"_84":2152,"_85":94},{"_24":2160,"_83":39,"_84":2152,"_85":97},{"_24":2162,"_83":39,"_84":2152,"_85":176},{"_22":2165,"_24":2166,"_75":2167,"_77":2168,"_79":2446,"_51":2177,"_42":99},[2447,2448,2449],{"_24":2171,"_83":39,"_84":2172,"_85":61},{"_24":2174,"_83":39,"_84":2172,"_85":88},{"_24":2176,"_83":39,"_84":2172,"_85":91},{"_22":2179,"_24":2180,"_75":2181,"_77":2182,"_79":2451,"_51":2193,"_42":99},[2452,2453,2454,2455],{"_24":2185,"_83":39,"_84":2186,"_85":61},{"_24":2188,"_83":39,"_84":2186,"_85":88},{"_24":2190,"_83":39,"_84":2186,"_85":91},{"_24":2192,"_83":39,"_84":2186,"_85":94},{"_22":2195,"_24":2196,"_75":2197,"_77":2198,"_79":2457,"_51":2207,"_42":99},[2458,2459,2460],{"_24":2201,"_83":39,"_84":2202,"_85":61},{"_24":2204,"_83":39,"_84":2202,"_85":88},{"_24":2206,"_83":39,"_84":2202,"_85":91},{"_22":2209,"_24":2210,"_75":2211,"_77":2212,"_79":2462,"_51":2221,"_42":99},[2463,2464,2465],{"_24":2215,"_83":39,"_84":2216,"_85":61},{"_24":2218,"_83":39,"_84":2216,"_85":88},{"_24":2220,"_83":39,"_84":2216,"_85":91},{"_22":2223,"_24":2224,"_75":2225,"_77":2226,"_79":2467,"_51":2241,"_42":99},[2468,2469,2470,2471,2472,2473],{"_24":2229,"_83":39,"_84":2230,"_85":61},{"_24":2232,"_83":39,"_84":2230,"_85":88},{"_24":2234,"_83":39,"_84":2230,"_85":91},{"_24":2236,"_83":39,"_84":2230,"_85":94},{"_24":2238,"_83":39,"_84":2230,"_85":97},{"_24":2240,"_83":39,"_84":2230,"_85":176},[],"actionData","errors"]}

Project Shop

일반 프로젝트