debug-generated-project
Debugs issues users encounter with Tuist-generated projects by reproducing the scenario locally, building Tuist from source when needed, and triaging whether it is a bug, misconfiguration, or something that needs team input. Use when users report generation failures, build errors after generation, or unexpected project behavior.
tuist · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add tuist/agent-skills --skill debug-generated-project技能说明
name: debug-generated-project description: Debugs issues users encounter with Tuist-generated projects by reproducing the scenario locally, building Tuist from source when needed, and triaging whether it is a bug, misconfiguration, or something that needs team input. Use when users report generation failures, build errors after generation, or unexpected project behavior.
Debug Tuist Project Issue
Quick Start
- Ask the user to describe the issue and the project setup (targets, dependencies, configurations, platform).
- Confirm the issue exists with the latest release by running
mise exec tuist@latest -- tuist generateagainst a reproduction project. - If confirmed, clone the Tuist repository and build from source to test against main.
- Triage: fix the bug and open a PR, advise on misconfiguration, or recommend the user files an issue with a reproduction.
Step 1: Gather Context
Ask the user for:
- What command they ran (e.g.
tuist generate) - The error message or unexpected behavior
- When the issue happens: generation time, compile time, or runtime (app launch or later)
- Their project structure: targets, platforms, dependencies (SwiftPM, XCFrameworks, local packages)
- Their
Project.swiftandTuist.swiftcontent (or relevant excerpts) - Their Tuist version (
tuist version)
The answer to "when" determines the verification strategy:
- Generation time: the issue might be a Tuist bug or a project misconfiguration. Reproduce with
tuist generate. - Compile time: the generated project has incorrect build settings, missing sources, or wrong dependency wiring. Reproduce with
xcodebuild buildafter generation. - Runtime: the app builds but crashes or misbehaves on launch or during use. Reproduce by installing and launching on a simulator.
Step 2: Reproduce with the latest release
Before investigating the source code, confirm the issue is not already fixed in the latest release.
Set up a temporary reproduction project
REPRO_DIR=$(mktemp -d)
cd "$REPRO_DIR"
Create minimal Tuist.swift, Project.swift, and source files that reproduce the user's scenario. Keep it as small as possible while still triggering the issue.
Run generation with the latest Tuist release
mise exec tuist@latest -- tuist generate --no-open --path "$REPRO_DIR"
If the issue involves dependencies, install them first:
mise exec tuist@latest -- tuist install --path "$REPRO_DIR"
Check the result
- If generation succeeds and the issue is gone, tell the user to update to the latest version.
- If the issue persists, continue to Step 3.
Step 3: Build Tuist from Source
Clone the repository and build the tuist executable and ProjectDescription library from source to test against the latest code on main.
TUIST_SRC=$(mktemp -d)
git clone --depth 1 https://github.com/tuist/tuist.git "$TUIST_SRC"
cd "$TUIST_SRC"
swift build --product tuist --product ProjectDescription --replace-scm-with-registry
The built binary will be at .build/debug/tuist. Use it to test the reproduction project:
"$TUIST_SRC/.build/debug/tuist" generate --no-open --path "$REPRO_DIR"
If the issue is fixed on main
Tell the user the fix is already on main, and it hasn't been released, tell them it'll be in the nest release and point them to the relevant commit if you can identify it.
If the issue persists on main
Continue to Step 4.
Step 4: Triage the Issue
Investigate the Tuist source code to understand why the issue occurs.
Outcome A: It is a bug
- Identify the root cause in the source code.
- Apply the fix.
- Verify by rebuilding and running against the reproduction project:
cd "$TUIST_SRC" swift build --product tuist --product ProjectDescription --replace-scm-with-registry "$TUIST_SRC/.build/debug/tuist" generate --no-open --path "$REPRO_DIR" - Zip the reproduction project and include it in the PR:
cd "$REPRO_DIR" && cd .. zip -r reproduction.zip "$(basename "$REPRO_DIR")" -x '*.xcodeproj/*' -x '*.xcworkspace/*' -x 'Derived/*' -x '.build/*' - Open a PR on the Tuist repository with:
- The fix
- The zipped reproduction project attached or committed as a fixture
- A clear description of the root cause and how to verify the fix
Outcome B: It is a misconfiguration
Tell the user what is wrong and how to fix it. Common misconfigurations:
- Missing
tuist installbeforetuist generatewhen using external dependencies - Incorrect source or resource globs that exclude or double-include files
- Mismatched build configurations between the project and external dependencies
- Wrong product types for dependencies (static vs dynamic)
- Missing
-ObjClinker flag for Objective-C dependencies - Using
sourcesandresourcesglobs together withbuildableFolders
Provide the corrected manifest snippet so the user can apply the fix directly.
Outcome C: Unclear or needs team input
If you cannot determine whether it is a bug or misconfiguration, recommend the user:
- Open a GitHub issue at https://github.com/tuist/tuist/issues with:
- The reproduction project (zipped)
- The error output
- Their Tuist version and environment details
Provide a summary of what you investigated and what you ruled out, so the user does not have to repeat the triage.
Build Verification
When testing a fix, always verify the full cycle:
# Build the patched tuist
cd "$TUIST_SRC"
swift build --product tuist --product ProjectDescription --replace-scm-with-registry
# Install dependencies if needed
"$TUIST_SRC/.build/debug/tuist" install --path "$REPRO_DIR"
# Generate the project
"$TUIST_SRC/.build/debug/tuist" generate --no-open --path "$REPRO_DIR"
# Build the generated project
xcodebuild build \
-workspace "$REPRO_DIR"/*.xcworkspace \
-scheme <scheme> \
-destination "platform=iOS Simulator,name=iPhone 16 Pro"