# საუკეთესო პრაქტიკები {#best-practices}

სხვადასხვა გუნდებთან და პროექტებთან მუშაობის წლების განმავლობაში, ჩვენ გამოვყავით საუკეთესო პრაქტიკების ნაკრები, რომლის დაცვასაც ვურჩევთ Tuist-ისა და Xcode-ის პროექტებთან მუშაობისას. ეს პრაქტიკები არ არის სავალდებულო, მაგრამ ისინი დაგეხმარებათ თქვენი პროექტების ისეთი სტრუქტურიზებით, რაც მათ შენარჩუნებასა და მასშტაბირებას გაუმარტივებს.

## Xcode {#xcode}

### არასასურველი შაბლონები {#discouraged-patterns}

#### კონფიგურაციები დაშორებული გარემოების მოდელირებისთვის {#configurations-to-model-remote-environments}

ბევრი ორგანიზაცია იყენებს აგების კონფიგურაციებს სხვადასხვა დაშორებული გარემოს მოდელირებისთვის (მაგ., `Debug-Production` ან `Release-Canary`), მაგრამ ამ მიდგომას აქვს გარკვეული უარყოფითი მხარეები:

- **შეუსაბამობები:** თუ გრაფში არსებობს კონფიგურაციის შეუსაბამობები, აგების სისტემამ ზოგიერთი სამიზნისთვის შეიძლება არასწორი კონფიგურაცია გამოიყენოს.
- **სირთულე:** პროექტებში შეიძლება გაჩნდეს ადგილობრივი კონფიგურაციებისა და დაშორებული გარემოების გრძელი სია, რომლის გააზრება და შენარჩუნება რთულია.

აგების კონფიგურაციები შექმნილია სხვადასხვა აგების პარამეტრების განსახიერებისთვის და პროექტებს იშვიათად სჭირდებათ მეტი, ვიდრე უბრალოდ `Debug` და `Release`. სხვადასხვა გარემოს მოდელირების საჭიროება შესაძლებელია სხვაგვარად მიღწეულ იქნას:

- **Debug აგებებში:** შეგიძლიათ ჩართოთ ყველა კონფიგურაცია, რომელიც განვითარების ეტაპზე უნდა იყოს ხელმისაწვდომი აპლიკაციაში (მაგ., ბოლოწერტილები) და გადაერთოთ მათ შორის შესრულების დროს. გადართვა შეიძლება მოხდეს ან სქემის გაშვების გარემოს ცვლადების გამოყენებით, ან აპლიკაციის შიგნით არსებული UI-ით.
- **Release აგებებში:** რელიზის შემთხვევაში, შეგიძლიათ ჩართოთ მხოლოდ ის კონფიგურაცია, რომელთანაც არის დაკავშირებული რელიზის აგება, და არ ჩართოთ კონფიგურაციების გადართვის შესრულების დროის ლოგიკა კომპილატორის დირექტივების გამოყენებით.

> [!NOTE]
> **არასტანდარტული კონფიგურაციები**
>
> მიუხედავად იმისა, რომ Tuist მხარს უჭერს არასტანდარტულ კონფიგურაციებს და მათი მართვა უფრო მარტივია, ვიდრე ჩვეულებრივ Xcode-ის პროექტებში, თქვენ მიიღებთ გაფრთხილებებს, თუ კონფიგურაციები არ არის თანმიმდევრული დამოკიდებულობების გრაფში. ეს ეხმარება აგების საიმედოობის უზრუნველყოფას და კონფიგურაციასთან დაკავშირებული პრობლემების თავიდან აცილებას.


## გენერირებული პროექტები

### ასაგები საქაღალდეები

Tuist 4.62.0-მა დაამატა მხარდაჭერა **ასაგები საქაღალდეებისთვის** (Xcode-ის სინქრონიზებული ჯგუფები), ფუნქცია, რომელიც წარმოდგენილი იყო Xcode 16-ში merge-კონფლიქტების შესამცირებლად.

მიუხედავად იმისა, რომ Tuist-ის ვაილდქარდის შაბლონები (მაგ., `Sources/**/*.swift`) უკვე აღმოფხვრის merge-კონფლიქტებს გენერირებულ პროექტებში, ასაგებ საქაღალდეებს აქვთ დამატებითი უპირატესობები:

- **ავტომატური სინქრონიზაცია**: თქვენი პროექტის სტრუქტურა რჩება სინქრონიზებული ფაილურ სისტემასთან — ფაილების დამატების ან წაშლისას ხელახალი გენერაცია არ არის საჭირო
- **AI-ზე მორგებული სამუშაო პროცესები**: კოდირების ასისტენტებსა და აგენტებს შეუძლიათ შეცვალონ თქვენი კოდბაზა პროექტის ხელახალი გენერაციის გამოწვევის გარეშე
- **უფრო მარტივი კონფიგურაცია**: განსაზღვრეთ საქაღალდეების გზები ფაილების ცხადი სიების მართვის ნაცვლად

ჩვენ ვურჩევთ ასაგები საქაღალდეების გამოყენებას ტრადიციული `Target.sources` და `Target.resources` ატრიბუტების ნაცვლად განვითარების უფრო გამარტივებული გამოცდილებისთვის.

::: code-group

```swift [With buildable folders]
let target: Target = .target(
  name: "App",
  destinations: .iOS,
  product: .app,
  bundleId: "dev.tuist.App",
  buildableFolders: ["App/Sources", "App/Resources"]
)
```

```swift [Without buildable folders]
let target: Target = .target(
  name: "App",
  destinations: .iOS,
  product: .app,
  bundleId: "dev.tuist.App",
  sources: ["App/Sources/**"],
  resources: ["App/Resources/**"]
)
```
<!-- -->
:::

### დამოკიდებულებები

#### CI-ზე ვერსიების იძულებითი რეზოლუცია

Swift Package Manager-ის დამოკიდებულებების CI-ზე ინსტალაციისას, ჩვენ ვურჩევთ `--force-resolved-versions` ფლაგის გამოყენებას დეტერმინისტული აგებების უზრუნველსაყოფად:

```bash
tuist install --force-resolved-versions
```

ეს ფლაგი უზრუნველყოფს, რომ დამოკიდებულებები გადაწყდეს `Package.resolved`-ში მიმაგრებული ზუსტი ვერსიების გამოყენებით, რაც აღმოფხვრის დამოკიდებულობების რეზოლუციაში არადეტერმინიზმით გამოწვეულ პრობლემებს. ეს განსაკუთრებით მნიშვნელოვანია CI-ზე, სადაც განმეორებადი აგებები კრიტიკულია.

#### დამოკიდებულებების cached ინსტალაცია GitHub Actions-ზე {#dependency-cache-volumes}

გენერირებული პროექტებისთვის, გამოიყენეთ [tuist/install](https://github.com/tuist/install) `Package.resolved`-ში მიმაგრებული დამოკიდებულებების ინსტალაციისა და გაშვებებს შორის მათი cache-ში შენახვისთვის. ის ავტომატურად იყენებს <.localized_link href="/guides/features/runners/cache-volumes">cache volumes</.localized_link>-ს Tuist Runners-ზე და GitHub-ის cache-ს სხვა runners-ზე.

```yaml
name: Generate project
on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  generate:
    runs-on: tuist-macos
    steps:
      - uses: actions/checkout@v4
      - uses: jdx/mise-action@v4
      - uses: tuist/install@v1
      - run: tuist generate --no-open
```

ქვესაქაღალდეში მყოფი პროექტისთვის, გადაეცით მისი გზა checkout-ის მიმართებაში:

```yaml
- uses: tuist/install@v1
  with:
    path: apps/ios
```

დამატებითი პარამეტრებისთვის იხილეთ [action reference](https://github.com/tuist/install#usage).

### Agentic კოდირება და worktrees {#agentic-coding-and-worktrees}

კოდირების აგენტები და ადამიანი კონტრიბუტორები სულ უფრო ხშირად მუშაობენ პარალელურად: დეველოპერი ტოვებს worktree-ს გახსნილ იმ ფუნქციისთვის, რომელსაც ის აკვირდება, ხოლო ერთი ან მეტი აგენტი იტერაციას აკეთებს საკუთარ ბრენჩებზე დაძმობილებულ worktree-ებში. რამდენიმე პროექტის არჩევანი ამას ბევრად უფრო გლუვს ხდის.

#### გამოიყენეთ ასაგები საქაღალდეები აგენტის მიერ განხორციელებული ცვლილებებისთვის {#worktrees-buildable-folders}

როდესაც აგენტი ამატებს ან შლის ფაილებს, ყველაფერი, რაც დამოკიდებულია `Project.swift`-ში არსებულ ფაილების სიაზე, მოითხოვს `tuist generate`-ს, სანამ პროექტი ხელახლა აიგება. [ასაგები საქაღალდეები](#buildable-folders) ამ პასუხისმგებლობას Xcode-ის სინქრონიზებულ ჯგუფებზე გადაიტანს, ასე რომ ფაილური ხის ცვლილებები აღარ იწვევს ხელახალ გენერაციას.

შეუთავსეთ ეს `generated-projects` <.localized_link href="/guides/features/agentic-coding/skills">skill</.localized_link>-თან, რომელიც აგენტებს ასწავლის Tuist პროექტის ყოველდღიურ სამუშაო პროცესს.

#### არ გამოყოთ cache თითოეული worktree-ისთვის {#worktrees-shared-cache}

Tuist მიჰყვება <.localized_link href="/cli/directories">XDG Base Directory Specification</.localized_link>-ს, ამიტომ ნაგულისხმევად ერთსა და იმავე მანქანაზე ყოველი worktree იზიარებს `~/.cache/tuist`-ს და `~/.local/state/tuist`-ს. ეს არის ის, რაც გსურთ: ერთ worktree-ში კომპილირებული helper-ები, მეორეში ჩამოტვირთული პლაგინები და მესამის მიერ მიღებული module-cache ბინარები ყველა ხელახლა გამოყენებადია.

პარალელურად `tuist`-ის გამოძახებების გაშვება worktree-ებში უსაფრთხოა. აიცილეთ `TUIST_XDG_CACHE_HOME`-ის მიმართვა worktree-ის ლოკალურ გზაზე, თუ კონკრეტულად იზოლაცია არ გჭირდებათ; ამის გაკეთება აიძულებს ყოველ worktree-ს ხელახლა „გააცხელოს“ helper-ები, პლაგინები და ბინარები.

#### შეინახეთ SwiftPM scratch თითოეული worktree-ისთვის {#worktrees-swiftpm-scratch}

Swift Package Manager-ს აქვს საკუთარი გზის კონტროლი. `--scratch-path` არის ცვალებადი სამუშაო მდგომარეობა და ნაგულისხმევად არის `.build`, ხოლო `--cache-path` არის საერთო cache დირექტორია. ეს ორი გზა არ უნდა განიხილებოდეს ერთნაირად, როდესაც რამდენიმე worktree არის აქტიური.

Tuist-ის ნაგულისხმევი `tuist install` ქცევა უკვე ინახავს SwiftPM scratch-ს პაკეტის დირექტორიაში, ამიტომ თითოეულ worktree-ს აქვს საკუთარი `.build`. შეინარჩუნეთ ეს იზოლაცია. ერთი საერთო SwiftPM scratch დირექტორია შეიძლება აურიოს checkouts, ბილდის შუალედური ფაილები, პლაგინები, მაკროები და lock ფაილები არადაკავშირებული ბრენჩებიდან.

თუ SwiftPM არგუმენტებს გადასცემთ `tuist install -- ...`-ით ან `Tuist.swift`-ში მყოფი `installOptions`-ით, გააზიარეთ `--cache-path`, როცა დამოკიდებულებების უფრო სწრაფად მიღება გსურთ, მაგრამ `--scratch-path` დატოვეთ დაყენების გარეშე ან მიმართეთ worktree-ის ლოკალურ დირექტორიაზე:

```swift
import ProjectDescription

let tuist = Tuist(
    project: .tuist(
        installOptions: .options(
            passthroughSwiftPackageManagerArguments: [
                "--cache-path",
                "/Users/Shared/swiftpm/cache/xcode-16-macos",
            ]
        )
    )
)
```

გამოიყენეთ wrapper ან CI გარემოს ცვლადი cache-ის გზისთვის, თუ ის უნდა განსხვავდებოდეს Xcode-ის, Swift toolchain-ის ან პლატფორმის მიხედვით. აიცილეთ რეპოზიტორიაში საერთო `--scratch-path`-ის commit-ება.

თუ დამოკიდებულებების მდგომარეობა დაზიანებულად ჩანს მხოლოდ ერთ worktree-ში, წაშალეთ ამ worktree-ის `.build` დირექტორია და ხელახლა გაუშვით `tuist install`. თუ საერთო SwiftPM cache ეჭვმიტანილი ჩანს worktree-ებში, დამოკიდებულებების ხელახლა ინსტალაციამდე გამოიყენეთ `swift package purge-cache`.

#### დაეყრდენით module cache-ს {#worktrees-module-cache}

<.localized_link href="/guides/features/cache/module-cache">module cache</.localized_link> ხდის პარალელურ worktree-ებს მართვადს. ვინაიდან Tuist თითოეული target-ისთვის ითვლის დეტერმინისტულ <.localized_link href="/guides/features/projects/hashing">hash</.localized_link>-ს, ორი worktree, რომელიც მიმართულია ბრენჩებზე, რომლებიც თავიანთი ისტორიის უმეტეს ნაწილს იზიარებენ, ერთსა და იმავე ბინარებს მოხვდება. CI-დან `main`-ზე ყოველი commit-ისას გაუშვით `tuist cache`; ლოკალურად, თითოეულ worktree-ში `tuist generate` იღებს cache-დან ყველაფერს, რაც შესაძლებელია და კომპილაციას უკეთებს მხოლოდ იმას, რაც თქვენმა ბრენჩმა რეალურად შეცვალა.

თუ worktree გადადის source builds-ზე, როცა ქეშში მოხვედრას ელოდით, მიჰყევით <.localized_link href="/guides/features/projects/hashing#debugging">hashing debugging steps</.localized_link>-ს; არადეტერმინისტული hashes (ჩვეულებრივ გამოწვეული პროექტში აბსოლუტური გზებით) არის ყველაზე ხშირი მიზეზი და ისინი მკაფიოდ ჩანან ორი worktree-ის შედარებისას.

#### Swift Package-ების რეზოლუციის დაჩქარება registry-ით {#worktrees-registry}

თითოეული worktree დამოუკიდებლად ახდენს Swift პაკეტების რეზოლუციას. დიდი დამოკიდებულების გრაფის მქონე პროექტებზე ეს სწრაფად იკრიბება. <.localized_link href="/guides/features/package-registries/swift">Tuist Registry</.localized_link>-ზე გადასვლა თავიდან აიცილებს git ისტორიების ხელახლა კლონირებას და რეზოლუციის დროს წუთებიდან წამებამდე ამცირებს.

#### აგენტებისთვის პროექტის ინსაიტებზე წვდომის მიცემა {#worktrees-mcp}

როდესაც ბილდები და ტესტები ბევრ worktree-შია გაშვებული, ყველაზე სასარგებლო, რაც აგენტს შეუძლია გააკეთოს, არის იმის ანალიზი, *რომელი* გაშვებებში მოხდა რეგრესია, რომელი ტესტებია არასტაბილური ან როგორ შეიცვალა bundle-ის ზომა. Tuist ამ მონაცემებს <.localized_link href="/guides/features/agentic-coding/mcp">MCP server</.localized_link>-ისა და <.localized_link href="/guides/features/agentic-coding/skills">Skills</.localized_link> პაკეტის მეშვეობით აწვდის. აირჩიეთ ერთ-ერთი სამუშაო პროცესისთვის და მიჰყევით მას; ორივეს ერთი და იგივე ამოცანისთვის შერევა ჩვეულებრივ არათანმიმდევრულ აგენტის ქცევას იწვევს.

## დაკავშირებული {#related}

წაიკითხეთ [როგორ ინარჩუნებს Monzo მზარდი მოდულური პროექტის თანმიმდევრულობას Tuist-ით](https://tuist.dev/customers/monzo), რათა გაეცნოთ გუნდის გამოცდილებას გენერირებული პროექტების მასშტაბურად გამოყენების შესახებ.
