Closing the loop on project scaffolding with Copier¶

This is a repost of my original article in Siemens' blog with some formatting enhancements.

Standards that ship, foundations that evolve: Copier distributes engineering and organizational standards through versioned templates and reconciles shared improvements with project-specific changes.

Starting a software project requires establishing a project foundation for its development and evolution. To establish this foundation, teams must decide how the project will be structured, developed, validated, maintained, and delivered. These decisions affect the project throughout its lifecycle and often draw on experience accumulated across earlier projects.

The difficulty lies not only in the individual decisions but also in their combination. Together, they must form a coherent, maintainable foundation that meets the project's needs and puts applicable standards into practice.

When teams establish this foundation independently for each project, whether manually or with coding agents, they duplicate design and implementation effort and risk inconsistent implementations or nonconformance with applicable requirements. Variation can be justified when project contexts differ, but independently recreating a shared project foundation increases maintenance effort and limits the transfer of improvements between projects.

Documentation and checklists can communicate requirements and prescribed practices, but applying them remains a separate implementation task for each project. They specify expected outcomes without providing a complete and validated realization. Applying them consistently therefore requires a maintained technical implementation, not only documented guidance.

This article examines how templates turn standards and established practices into maintained project foundations. We show how Copier enables a closed loop between templates and projects, distributing the effort required to maintain and evolve the shared foundation. And we consider the complementary roles of templates and coding agents in combining reliable foundations with project-specific flexibility.

Introducing Copier¶

Copier is an open-source library and command-line application for generating projects from parameterized templates. A template consists of a copier.yml configuration file and a file tree whose contents and paths may contain Jinja constructs. Templates can be maintained and released through Git, providing a versioned source from which projects are generated.

The copier.yml file defines the questions through which Copier obtains project-specific parameters, together with the settings that govern how the template is processed. Copier exposes the resulting answers as variables during rendering, evaluating the template's Jinja constructs to interpolate project-specific values and reflect any parameter-dependent variation in the generated project.

For example, a template may support projects hosted on either GitLab or GitHub. The questionnaire may capture this variation as a repository platform choice. Conditional patterns in the _exclude setting ensure that the generated project includes only the files for the selected platform:

_subdirectory: template
_exclude:
  - "{% if repository_platform != 'gitlab' %}/.gitlab-ci.yml{% endif %}"
  - "{% if repository_platform != 'github' %}/.github/{% endif %}"

repository_platform:
  type: str
  help: Where will the project be hosted?
  choices:
    GitLab: gitlab
    GitHub: github
  default: gitlab

The template contains the shared project files and the platform-specific CI configuration files:

📁 copier-project-template/
├── 📁 template/
│   ├── 📁 .github/
│   │   └── 📁 workflows/
│   │       └──  ci.yml.jinja
│   ├── 📁 src/
│   ├── 📁 tests/
│   ├──  .gitlab-ci.yml.jinja
│   ├──  README.md.jinja
│   └──  {{ _copier_conf.answers_file }}.jinja
└──  copier.yml

Selecting GitLab excludes the .github/ directory, whereas selecting GitHub excludes the .gitlab-ci.yml file. The same answer may also determine platform-specific references in contribution guidelines, package metadata, and other files. More generally, answers can determine file contents, paths, and the presence of files or directories.

Closing the loop between templates and projects¶

Project generators are often treated as disposable bootstrap tools. They reduce work on day one, but the generated project immediately becomes a disconnected copy. Copier's central value is stronger: it can retain the relationship between a generated project and its versioned template and use that provenance to reconcile changes from later template releases with project-specific changes.

After installing Copier, for example using uv with uv tool install copier, we can generate a project from the template introduced above:

copier copy <template-url> my-project

Selecting GitLab as the repository platform produces the shared project files and the corresponding GitLab CI configuration file:

📁 my-project/
├── 📁 src/
├── 📁 tests/
├──  .copier-answers.yml
├──  .gitlab-ci.yml
└──  README.md

In addition, Copier renders the template file {{ _copier_conf.answers_file }}.jinja as the project's answers file, named .copier-answers.yml by default, which may look like this:

# Changes here will be overwritten by Copier
_commit: v2.3.1
_src_path: <template-url>
repository_platform: gitlab

The _src_path and _commit entries record template provenance; the other entries capture the answers that produced this project variant. The file should be committed but not edited manually. Copier updates it during project updates to keep the recorded provenance and project parameters aligned with the resulting project state.

Suppose template version 2.4.0 improves dependency caching in the .gitlab-ci.yml file. We can update the project to the latest stable template release with the following command:

copier update

Using the recorded template provenance and project parameters, Copier reconciles the changes from template version 2.4.0 with project-specific changes, incorporating the change to the .gitlab-ci.yml file and producing an ordinary working-tree diff.

Now, we can inspect the diff, resolve conflicts if present, run tests, and submit it through the same merge-request workflow as any other change. The project remains independently owned and can diverge where its requirements differ; project maintainers retain control over which proposed changes to incorporate and how.

Distributing and evolving project foundations¶

Copier templates provide a technical means of distributing shared project foundations aligned with applicable engineering and organizational standards. Initial generation creates these foundations for new projects, while subsequent template releases allow project maintainers to incorporate later improvements through reviewable project updates. Templates thus provide project developers with a maintained implementation of documented guidance, rather than requiring them to interpret and implement each revision independently for every project.

As project developers build their software on the shared project foundation, practical experience with project-specific requirements may reveal improvements of broader relevance. Project developers or maintainers can feed these insights back to the template maintainers, who can implement or review them, validate them across supported project variants, and publish them in a new release.

This feedback loop allows the shared project foundation to evolve through use, grounded in practical experience. Improvements are implemented and validated in the template, and project maintainers can incorporate them into generated projects by running copier update. Renovate's Copier manager can partially automate this process by submitting project updates for review.

Distribution through a template does not enforce adoption or guarantee compliance with a particular template version. Where specific standards are mandatory, they require separate policies and controls.

Deterministic foundations for coding agents¶

The rise of coding agents may raise a question: if an agent can generate an entire repository from a natural-language request, why maintain templates?

Coding agents generate output nondeterministically based on their instructions, context, tools, models, and other factors; the same prompt may therefore produce different results across runs or LLMs. Engineering and organizational standards must also be available to the agent and interpreted as intended. For initial scaffolding, this variability means that a prompt alone does not guarantee a reproducible, vetted project foundation for use across projects. For subsequent project updates, even versioned prompts do not guarantee that differences between generated outputs reflect only intentional prompt changes, which can make targeted updates difficult to derive reliably.

In contrast, Copier reproducibly generates an initial project from a specific template release and the answers supplied during generation, allowing template maintainers to validate the resulting project variants centrally. For subsequent project updates, the generated project retains its template provenance, allowing Copier to reconcile template changes with project-specific changes in a controlled manner. When generated from a vetted template release, the tooling and configuration aligned with the applicable engineering and organizational standards are present by construction. Coding agents can focus on project-specific changes within these established guardrails rather than regenerating the shared project foundation nondeterministically. This division of responsibilities reserves inference resources for differentiating work without sacrificing the reliability of the project foundation.

Conclusion¶

Establishing a project foundation requires related decisions about its structure, tooling, and workflows, aligned with applicable engineering and organizational standards. Repeating these decisions across projects duplicates effort and risks inconsistency and nonconformance. Parameterized templates capture their technical realization in a reusable form and derive supported project variants from explicit inputs.

Copier extends this value beyond initial generation. By retaining template provenance and reconciling template changes with project-specific changes, it allows project maintainers to incorporate improvements from later template releases through reviewable project updates. Insights gained while developing projects on the shared project foundation can be fed back into the template, closing the cycle and grounding its evolution in practical use.

Coding agents complement rather than replace templates. Templates provide a reproducible and vetted project foundation aligned with applicable standards, while agents can focus their inference resources on differentiating work within those guardrails. Thus, coding agents benefit from a reliable project foundation while retaining the flexibility to address project-specific requirements.

If you find Copier useful, consider giving the project on GitHub a star. And if you find this article useful, please consider sharing your feedback and experience via the comment box below.

Comments