📃 Docs: #21 TCA 컨벤션 가이드라인 및 코드 템플릿 작성 by doyeonk429 · Pull Request #26 · DevaultProject/Devault-macOS

doyeonk429 · 2026-06-30T13:32:37Z

✨ What's this PR?

📌 관련 이슈 (Related Issue)

Closes Docs: TCA Convention & Code Template 작성 #21

🧶 주요 변경 내용 (Summary)

TCA 컨벤션 가이드라인 신규 작성 (docs/TCA_GUIDELINES.md)
- State / Action / Reducer / Effect / Dependency / Navigation / View / Testing 전 영역 커버
- 마인드모델 · 핵심 원칙 · 상황별 가이드(Cookbook) · 안티패턴 · 리뷰 체크리스트(A~J) · 리뷰 출력 형식 포함
- TCA 초보 협업자가 따라오기 쉽도록 언제 · 왜 · 어떻게 톤으로 풀어쓰고 callout으로 의도 설명 보강
- Dependency 절은 Composition Root 분리(Option B) 패턴 — DVPresentation에 TestDependencyKey, App 타겟에 liveValue. 우리 프로젝트의 FetchSecretUseCase / SecretRepository 기반 SecretClient 어댑터 예시 + 의존 그래프 수록
가독성용 styled HTML 버전 추가 (docs/TCA_GUIDELINES.html) — TOC, syntax 하이라이트, callout 박스
Tuist scaffold 템플릿 추가 (Tuist/Templates/feature/) — tuist scaffold feature --name X로 가이드라인 준수 보일러플레이트 생성

🧪 테스트 / 검증 내역

docs/TCA_GUIDELINES.md GitHub 렌더링 확인
docs/TCA_GUIDELINES.html 브라우저 렌더링 확인 (open docs/TCA_GUIDELINES.html)

💬 기타 공유 사항

Dependency 패턴은 Option A(DVPresentation 단일 위치) 와 Option B(App 타겟 Composition Root 분리) 두 가지를 검토했고, 모듈 수준에서도 Clean Architecture 의존 화살표를 지키는 Option B를 권장안으로 채택했습니다.
아직 SecretListFeature 등 실제 Feature는 미구현 상태 — 첫 Feature 구현 시 본 가이드의 6.4 패턴을 그대로 적용 예정입니다.

🙇🏻‍♀️ 리뷰 가이드

6절 Dependency / Composition Root 분리 — 패턴 채택에 합의가 필요합니다. App 타겟에 +Live.swift를 두는 구조에 동의하는지 의견 부탁드려요.

- DVPresentation 모듈용 TCA 컨벤션 가이드라인 작성 (docs/TCA_GUIDELINES.md) - AI 코드 리뷰용 체크리스트 및 출력 포맷 정의 - tuist scaffold feature 템플릿 추가 (Feature/View 자동 생성) - TCA 의존성 버전 1.15.0 → 1.25.0 업그레이드

- TCA 처음 사용자를 위해 마인드모델·상황별 가이드(Cookbook) 절 추가 - 가독성용 styled HTML 버전(TCA_GUIDELINES.html) 신규 추가

coderabbitai · 2026-06-30T13:32:53Z

Walkthrough

swift-composable-architecture 의존성을 1.25.0으로 올리고, Tuist 피처 스캐폴딩 템플릿(feature.swift, Feature.stencil, View.stencil) 3개 파일과 TCA 컨벤션 가이드 문서(TCA_GUIDELINES.md, TCA_GUIDELINES.html)를 신규 추가한다.

Changes

TCA 버전 업 및 피처 템플릿·가이드 추가

Layer / File(s)	Summary
TCA 의존성 버전 업 `Tuist/Package.swift`	`swift-composable-architecture` 최소 버전을 `1.15.0`에서 `1.25.0`으로 변경.
Tuist 피처 스캐폴딩 템플릿 `Tuist/Templates/feature/feature.swift`, `Tuist/Templates/feature/Feature.stencil`, `Tuist/Templates/feature/View.stencil`	`name` 속성을 필수로 받아 `@Reducer` 기반 Feature(State, Action, Delegate, body 스텁)와 SwiftUI View(content, task 액션 디스패치, `#Preview`) 두 파일을 생성하는 Tuist 템플릿을 추가.
TCA 컨벤션 가이드 문서 `docs/TCA_GUIDELINES.md`, `docs/TCA_GUIDELINES.html`	TCA 1.25.0 Observation 기반 컨벤션 전체(State/Action/Reducer/Effect/Dependency/Navigation/View/Testing, 안티패턴, AI 에이전트용 리뷰 체크리스트 및 출력 형식)를 MD·HTML 두 형태로 문서화.

추정 코드 리뷰 노력

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

✨ Feature

Suggested reviewers

yeseonglee

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	`#21의` 문서, feature.swift, View.stencil, Feature.stencil, 버전 업그레이드 요구를 모두 충족합니다.
Out of Scope Changes check	✅ Passed	추가된 HTML 문서는 가이드 문서의 렌더링용 보조 산출물로 보이며, 변경 범위는 요청된 TCA 문서·템플릿 작업에 맞습니다.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	TCA 가이드라인 문서와 scaffold 코드 템플릿 추가라는 핵심 변경을 정확히 요약합니다.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/#21

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

doyeonk429 · 2026-06-30T13:35:54Z

.html 파일을 열면 가독성 좋은 파일로 읽을 수 있습니다. .md 파일은 AI agent가 리뷰할 때 참고할 수 있도록 프롬프트 작성하시면 됩니다.

coderabbitai

Actionable comments posted: 5

🧹 Nitpick comments (1)

Tuist/Templates/feature/Feature.stencil (1)
3-4: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

생성되는 Feature 스켈레톤도 저장소 스타일을 바로 따르도록 맞춰 주세요.

지금 템플릿은 ComposableArchitecture를 Foundation보다 먼저 import하고, Action 하위 섹션도 // MARK: View 형식으로 생성합니다. 스캐폴드 출력물이 곧바로 리뷰 기준을 통과하게 하려면 import 순서와 // MARK: - 표기를 템플릿에서 맞춰 두는 편이 좋습니다. As per path instructions, "**/*.swift: // MARK: - 위아래에 빈 줄이 있는지 확인하세요." and "**/*.swift: 모듈 임포트가 알파벳 순으로 정렬되어 있는지 확인하세요. (내장 프레임워크 먼저, 빈 줄로 서드파티 구분)".
예시 수정
-import ComposableArchitecture
 import Foundation
+
+import ComposableArchitecture
@@
-    // MARK: View
+    // MARK: - View
@@
-    // MARK: Internal
+    // MARK: - Internal
@@
-    // MARK: Child
+    // MARK: - Child
@@
-    // MARK: Delegate
+    // MARK: - Delegate
Also applies to: 22-30
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@Tuist/Templates/feature/Feature.stencil` around lines 3 - 4, The Feature
template is generating code that violates the repository’s Swift style by
placing ComposableArchitecture before Foundation and by emitting MARK comments
without the required separator format. Update the Feature.stencil template so
the import block follows alphabetic order with built-in frameworks first and a
blank line before third-party imports, and make sure the generated section
headers use the `// MARK: -` convention with blank lines around them. Use the
template’s import declarations and MARK sections as the main points to adjust so
all generated Feature scaffolds conform immediately.
Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/TCA_GUIDELINES.html`:
- Around line 373-377: The section link text in the read-note is inconsistent
with the target anchor, so update the “11. 리뷰 체크리스트” label to match the
`#sec-12` destination. Adjust the text in the read-note block within the HTML
doc so the visible section number aligns with the linked section title, keeping
the existing `href` and surrounding guidance unchanged.

In `@docs/TCA_GUIDELINES.md`:
- Around line 67-69: Several fenced code blocks in TCA_GUIDELINES.md are missing
language tags, which triggers markdownlint warnings and removes syntax
highlighting. Update the affected fences to use the appropriate language
identifiers based on content, such as bash for shell commands, swift for Swift
snippets, and text for plain examples; check the nearby fenced blocks around the
referenced examples and make the same fix consistently across the document.
- Around line 10-12: The intro and cross-reference links in TCA_GUIDELINES.md
are pointing to the wrong checklist section number and fragment. Update the
links that currently reference “11. 리뷰 체크리스트” so they match the actual heading
for the checklist section, using the same section name and anchor as the
existing “12. 리뷰 체크리스트 (AI 에이전트용)” heading, and verify any repeated references
in the document stay consistent.
- Around line 471-475: `CancelID` 설명이 본문/체크리스트의 요구사항과 예제에서 서로 다르게 보이므로,
`cancellable(id:)`와 함께 쓰는 취소 식별자 설명을 “cancellation ID용 enum”처럼 일관된 표현으로 바꾸고
`CancelID` 예시와 체크리스트 문구를 같은 형태로 맞추세요. 특히 `CancelID`의 정의 방식과 예제에서의 사용 방식이 모순되지
않도록 문장 전체를 통일해 독자가 동일한 패턴으로 구현할 수 있게 정리하세요.
- Around line 452-454: The `projectsResponse` example in the TCA guidelines uses
`Result { try await ... }`, which is not compatible with Swift 5.9. Update this
example to use a Swift 5.9-safe pattern such as `do/catch` or `TaskResult`, and
make the same replacement anywhere the same `Result { try await ... }` pattern
is repeated in the document. Use the surrounding `return .run { send in ... }`
snippet as the reference point when editing.

---

Nitpick comments:
In `@Tuist/Templates/feature/Feature.stencil`:
- Around line 3-4: The Feature template is generating code that violates the
repository’s Swift style by placing ComposableArchitecture before Foundation and
by emitting MARK comments without the required separator format. Update the
Feature.stencil template so the import block follows alphabetic order with
built-in frameworks first and a blank line before third-party imports, and make
sure the generated section headers use the `// MARK: -` convention with blank
lines around them. Use the template’s import declarations and MARK sections as
the main points to adjust so all generated Feature scaffolds conform
immediately.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 14b95faf-ad31-4b72-8970-e25475668866

📥 Commits

Reviewing files that changed from the base of the PR and between 2176f22 and 9c08aa0.

📒 Files selected for processing (6)

Tuist/Package.swift
Tuist/Templates/feature/Feature.stencil
Tuist/Templates/feature/View.stencil
Tuist/Templates/feature/feature.swift
docs/TCA_GUIDELINES.html
docs/TCA_GUIDELINES.md

coderabbitai · 2026-06-30T13:39:48Z

+<div class="read-note">
+  <strong>이 문서를 읽는 사람에게</strong><br>
+  TCA를 처음 사용한다면 <a href="#sec-0">0. 시작하기 전에 — 마인드모델</a>부터 순서대로 읽으세요.
+  이미 익숙하다면 <a href="#sec-12">11. 리뷰 체크리스트</a>로 바로 가도 됩니다.
+  본문 각 절에는 <em>언제 이걸 쓰는가 → 왜 이렇게 쓰는가 → 어떻게 쓰는가</em> 순서로 정리돼 있습니다.


📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

섹션 링크 텍스트가 본문 번호와 어긋납니다.

href는 #sec-12로 맞는데, Line 376 텍스트는 아직 11. 리뷰 체크리스트입니다. HTML 버전만 읽는 사람도 혼동하니 번호를 12로 맞춰 주세요.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/TCA_GUIDELINES.html` around lines 373 - 377, The section link text in the read-note is inconsistent with the target anchor, so update the “11. 리뷰 체크리스트” label to match the `#sec-12` destination. Adjust the text in the read-note block within the HTML doc so the visible section number aligns with the linked section title, keeping the existing `href` and surrounding guidance unchanged.

coderabbitai · 2026-06-30T13:39:48Z

+> **이 문서를 읽는 사람에게**
+> TCA를 처음 사용한다면 [0. 시작하기 전에 — 마인드모델](#0-시작하기-전에--마인드모델)부터 순서대로 읽으세요.
+> 이미 익숙하다면 [11. 리뷰 체크리스트](#11-리뷰-체크리스트-ai-에이전트용)로 바로 가도 됩니다.


📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

체크리스트 링크 번호와 fragment를 실제 섹션에 맞춰 주세요.

Line 12와 Line 79가 아직 11. 리뷰 체크리스트를 가리켜서 문서 내 이동이 깨집니다. 현재 헤딩은 ## 12. 리뷰 체크리스트 (AI 에이전트용)이므로 링크 텍스트와 fragment를 함께 맞춰야 합니다.

Also applies to: 79-79

🧰 Tools

🪛 markdownlint-cli2 (0.22.1)

[warning] 12-12: Link fragments should be valid

(MD051, link-fragments)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/TCA_GUIDELINES.md` around lines 10 - 12, The intro and cross-reference links in TCA_GUIDELINES.md are pointing to the wrong checklist section number and fragment. Update the links that currently reference “11. 리뷰 체크리스트” so they match the actual heading for the checklist section, using the same section name and anchor as the existing “12. 리뷰 체크리스트 (AI 에이전트용)” heading, and verify any repeated references in the document stay consistent.

Source: Linters/SAST tools

coderabbitai · 2026-06-30T13:39:48Z

+```bash
+tuist scaffold feature --name ProjectList
+```


📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

코드 펜스 언어를 지정해 두는 편이 좋습니다.

현재 여러 fenced code block에 언어가 빠져 있어서 markdownlint 경고가 나고, 렌더링 시 하이라이팅도 잃습니다. bash, swift, text처럼 block 성격에 맞는 언어를 붙여 주세요.

Also applies to: 73-77, 92-104, 556-569, 843-861, 1319-1336

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/TCA_GUIDELINES.md` around lines 67 - 69, Several fenced code blocks in TCA_GUIDELINES.md are missing language tags, which triggers markdownlint warnings and removes syntax highlighting. Update the affected fences to use the appropriate language identifiers based on content, such as bash for shell commands, swift for Swift snippets, and text for plain examples; check the nearby fenced blocks around the referenced examples and make the same fix consistently across the document.

Source: Linters/SAST tools

coderabbitai · 2026-06-30T13:39:48Z

+  return .run { send in
+    await send(.projectsResponse(Result { try await projectClient.fetchAll() }))
+  }


🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

Does Swift 5.9 support initializing Resultwith an async throwing closure likeResult { try await foo() }?

💡 Result:

As of June 30, 2026, Swift does not support initializing Result with an async throwing closure (e.g., Result { try await foo }) in Swift 5.9 [1]. This feature was added in Swift 6.4 via the proposal SE-0530, "Async Result Support" [1][2]. While the syntax await Result { try await foo() } is available in the current Swift versions (Swift 6.4+), it was not part of the language in Swift 5.9 [1]. In versions like Swift 5.9, developers typically handled this by manually performing the work in a do-catch block or by creating a custom extension to provide the missing async initializer [3][1][4].

Citations:

1: https://livsycode.com/swift/swift-6-4-adds-async-support-to-result-2/

2: https://forums.swift.org/t/se-0530-async-result-support/86346

3: https://github.com/apple/swift-evolution/blob/main/proposals/0530-async-result-support.md

4: https://www.hackingwithswift.com/swift/5.5/async-await

🏁 Script executed:

#!/bin/bash set -euo pipefail file="docs/TCA_GUIDELINES.md" # Show the relevant sections around both mentioned locations. sed -n '440,465p' "$file" printf '\n---\n' sed -n '514,530p' "$file"

Repository: DevaultProject/Devault-macOS

Length of output: 1158

Result { try await ... } 예제는 Swift 5.9와 맞지 않습니다.

Result의 async throwing initializer는 Swift 6.4부터라서, 툴체인 5.9 독자가 그대로 복사하면 컴파일이 막힙니다. do/catch 또는 TaskResult 예제로 바꾸는 편이 안전합니다. 같은 패턴이 아래 예제에도 반복됩니다.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/TCA_GUIDELINES.md` around lines 452 - 454, The `projectsResponse` example in the TCA guidelines uses `Result { try await ... }`, which is not compatible with Swift 5.9. Update this example to use a Swift 5.9-safe pattern such as `do/catch` or `TaskResult`, and make the same replacement anywhere the same `Result { try await ... }` pattern is repeated in the document. Use the surrounding `return .run { send in ... }` snippet as the reference point when editing.

coderabbitai · 2026-06-30T13:39:48Z

+검색·디바운스 등 **이전 작업을 취소해야 하는 Effect**는 `cancellable(id:)`를 씁니다.
+ID는 enum case 없는 `enum CancelID { case search }` 패턴으로 정의합니다.
+
+```swift
+private enum CancelID { case search }


🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

CancelID 설명이 예제와 모순됩니다.

본문과 체크리스트는 "case 없는 enum"을 요구하지만, 바로 아래 예제는 CancelID.search를 사용합니다. 지금 표현대로면 독자가 잘못된 타입을 만들기 쉬우니 "cancellation ID용 enum"처럼 설명을 고치고 예제/체크리스트를 같은 표현으로 통일해 주세요.

Also applies to: 1276-1276

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/TCA_GUIDELINES.md` around lines 471 - 475, `CancelID` 설명이 본문/체크리스트의 요구사항과 예제에서 서로 다르게 보이므로, `cancellable(id:)`와 함께 쓰는 취소 식별자 설명을 “cancellation ID용 enum”처럼 일관된 표현으로 바꾸고 `CancelID` 예시와 체크리스트 문구를 같은 형태로 맞추세요. 특히 `CancelID`의 정의 방식과 예제에서의 사용 방식이 모순되지 않도록 문장 전체를 통일해 독자가 동일한 패턴으로 구현할 수 있게 정리하세요.

doyeonk429 added 2 commits June 30, 2026 15:40

[#21] docs: TCA 가이드라인 튜토리얼 내용 확장 및 HTML 버전 추가

9c08aa0

- TCA 처음 사용자를 위해 마인드모델·상황별 가이드(Cookbook) 절 추가 - 가독성용 styled HTML 버전(TCA_GUIDELINES.html) 신규 추가

doyeonk429 requested review from dlguszoo and yeseonglee June 30, 2026 13:33

doyeonk429 self-assigned this Jun 30, 2026

doyeonk429 added the 📃 Docs 문서 작업 및 수정 label Jun 30, 2026

doyeonk429 changed the title ~~[#21] docs: TCA 컨벤션 가이드라인 및 코드 템플릿 작성~~ 📃 Docs: #21 TCA 컨벤션 가이드라인 및 코드 템플릿 작성 Jun 30, 2026

coderabbitai Bot reviewed Jun 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

📃 Docs: #21 TCA 컨벤션 가이드라인 및 코드 템플릿 작성#26

📃 Docs: #21 TCA 컨벤션 가이드라인 및 코드 템플릿 작성#26
doyeonk429 wants to merge 2 commits into
developfrom
docs/#21

doyeonk429 commented Jun 30, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

doyeonk429 commented Jun 30, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

coderabbitai Bot Jun 30, 2026

Uh oh!

coderabbitai Bot Jun 30, 2026

Uh oh!

coderabbitai Bot Jun 30, 2026

Uh oh!

coderabbitai Bot Jun 30, 2026

Uh oh!

coderabbitai Bot Jun 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

doyeonk429 commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✨ What's this PR?

📌 관련 이슈 (Related Issue)

🧶 주요 변경 내용 (Summary)

🧪 테스트 / 검증 내역

💬 기타 공유 사항

🙇🏻‍♀️ 리뷰 가이드

Uh oh!

coderabbitai Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

추정 코드 리뷰 노력

Suggested labels

Suggested reviewers

Uh oh!

doyeonk429 commented Jun 30, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

doyeonk429 commented Jun 30, 2026 •

edited

Loading

coderabbitai Bot commented Jun 30, 2026 •

edited

Loading