> ## Documentation Index
> Fetch the complete documentation index at: https://docs.factory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Proven tips and workflows to get the most out of cloud templates in Factory

Cloud templates let you spin up consistent, production-ready development environments in seconds. Below are field-tested practices that keep templates fast, predictable, and team-friendly.

## 1. Smart Setup Script Practices

| Practice                          | Why it matters                                      | How to do it                                                                                                |
| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Order commands by dependency**  | Later commands may depend on earlier installs.      | Run package installation first: `npm ci && npm run build` or `pip install -r requirements.txt && pytest -q` |
| **Use exact package managers**    | Consistent lockfiles prevent version drift.         | Use `npm ci` (not `npm install`), `pnpm -w i`, or `pip install -r requirements.txt` for reproducible builds |
| **Add error handling**            | Stops build on first failure, saves debugging time. | Start your script with `#!/usr/bin/env bash` and `set -euo pipefail` for proper error handling              |
| **Make scripts executable early** | Avoid permission errors mid-build.                  | Add `chmod +x ./scripts/setup.sh && bash ./scripts/setup.sh` or use `bash ./scripts/setup.sh` directly      |
| **Keep scripts idempotent**       | Re-running setup shouldn't break things.            | Use flags like `pip install --no-deps` or check for existing files before creating them                     |
| **Minimize heavy operations**     | Long builds slow down template creation.            | Focus on essential setup; defer optional tools to manual installation later                                 |

> **Tip:** Test your setup script locally first. The script runs with `bash` at the repo root, and you can add `set -euo pipefail` for strict error handling.

***

## 2. Workflow Patterns That Scale

<AccordionGroup>
  <Accordion title="Spin-Up-Per-Task">
    Treat remote sessions as disposable: create one per ticket or PR, then archive when merged.\
    **Benefits:** perfect isolation, zero “works on my machine” drift.
  </Accordion>

  <Accordion title="Parallel Environments">
    Need to test multiple branches? Launch two separate sessions; switch context without killing processes.
  </Accordion>
</AccordionGroup>

***

## 3. Team Collaboration Tips

| Tip                         | Details                                                                                                         |
| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Name templates clearly**  | Name templates according to the tracked repository, e.g. `repo-name` to work on a repository named `repo-name`. |
| **Document entry commands** | Add an `AGENTS.md` file with common tasks (`npm run dev`, `pytest`). Droid automatically reads this file.       |

## 5. Troubleshooting at a Glance

| Symptom                      | Resolution                                                                   |
| ---------------------------- | ---------------------------------------------------------------------------- |
| **Rebuild is slow**          | Verify `.dockerignore`, cache heavy installs in image, use lighter base.     |
| **Git asks for credentials** | Ensure repository integration is enabled in **Integrations → Repositories**. |
| **Out-of-disk errors**       | Prune package caches (`npm cache clean --force`) or rebuild template.        |

Following these practices keeps your cloud templates fast, secure, and collaborative—so you can focus on shipping code, not configuring machines.