Day 3 : Turn Good Prompts Into Version-Controlled Engineering Workflows

  • AI-assisted Dev, GitHub Copilot, Prompt Files, Engineering Workflows
  • 5 min read

How prompt files turn repeatable AI engineering tasks into version-controlled workflows that teams can review, reuse and improve.

Table of contents

Yesterday I moved a class of repeated instructions out of individual prompts and into the repository itself.

Things such as:

Use the existing abstraction.
Do not bypass infrastructure boundaries.
Every behavioral change requires tests.
Keep changes backward compatible.

belong in persistent repository guidance because they describe how engineering should be done.

But that immediately exposed a second problem.

Developers do not only repeat rules. They also repeat workflows.

One developer asks Copilot to review a pull request with:

review this code

Another asks:

find problems

A third says:

review this as a senior engineer

And perhaps one engineer has spent weeks refining a genuinely useful 30-line review procedure.

All four developers are using the same tool, but they are not really running the same engineering process.

That led to the next useful distinction:

Repository instructions encode persistent policy. Prompt files encode repeatable engineering procedures.

Once I understood that, prompt files stopped looking like a convenience feature and started looking like version-controlled workflow infrastructure.

1. Repository instructions and prompt files solve different problems

In Visual Studio Code with GitHub Copilot, reusable prompt files use the .prompt.md format and can live in a repository alongside the persistent instruction files.

A repository might evolve toward something like:

.github/
├── copilot-instructions.md
├── instructions/
│   ├── python.instructions.md
│   └── tests.instructions.md
└── prompts/
    ├── architecture-review.prompt.md
    ├── implement-feature.prompt.md
    ├── review-code.prompt.md
    └── generate-tests.prompt.md

The important distinction is not the directory structure by itself.

It is the responsibility of each layer:

copilot-instructions.md
        │
        │  "How we engineer"
        ▼
Persistent constraints

*.prompt.md
        │
        │  "Perform this workflow"
        ▼
Reusable procedure

Developer request
        │
        │  "Do it for this problem"
        ▼
Specific objective

That separation gives the AI system three different kinds of information instead of mixing everything into one giant prompt.

The repository defines the durable rules.

The prompt file defines the repeatable procedure.

The developer provides the concrete problem.

2. Prompt quality variance does not scale

Prompting skill varies dramatically between developers.

That is not surprising. People learn through experimentation. Some engineers discover useful review structures. Others keep using one-line requests because those appear to work well enough.

But at team scale, this creates a dependency chain:

Developer skill
      ↓
Prompt quality
      ↓
AI analysis quality

If ten developers use Copilot for review and each invents a different procedure, the team has ten different AI-assisted review processes.

That is difficult to train, difficult to improve and almost impossible to evaluate consistently.

A reusable prompt changes the unit of improvement.

Instead of teaching everyone to independently discover the best wording, the team can improve one shared artifact:

.github/prompts/code-review.prompt.md

For example:

Review the selected implementation as a senior software engineer.

First understand the surrounding implementation before reporting findings.

Evaluate:

- correctness
- architecture violations
- error handling
- concurrency issues
- resource handling
- security risks
- performance regressions
- backward compatibility
- missing tests

For every finding provide:

1. severity
2. affected file
3. affected code
4. why it is problematic
5. recommended correction

Do not report stylistic preferences already enforced by automated tooling.

Prioritize defects over suggestions.

Now developers are no longer merely sharing a model.

They are sharing an engineering procedure.

3. Prompt files encode procedures

A reusable prompt should contain more than a command.

This is barely worth version controlling:

Write unit tests.

It tells the model what output category you want, but it does not encode much engineering judgment.

A procedure is different.

For example:

Analyze the changed behavior.

Identify missing test cases.

Generate tests covering:
- happy path
- boundary conditions
- failure paths
- malformed input

Preserve existing test conventions.

Do not weaken existing assertions.

That prompt contains an approach.

It tells the model how to reason through the task, what categories to inspect and what boundaries to preserve.

That is what makes it reusable.

4. Separate policy from procedure

This is the distinction I would teach an engineering team explicitly.

Suppose the repository instruction says:

Every behavioral change requires tests.

That is policy.

It should apply regardless of which developer is working, which feature is being changed or which prompt is being executed.

Now suppose a prompt file says:

Analyze the changed behavior.

Identify missing test cases.

Generate tests covering:
- happy path
- boundary conditions
- failure paths
- malformed input

That is procedure.

It describes how to perform one repeatable engineering workflow.

The relationship starts to look like this:

                    AI Engineering Layer

              ┌─────────────────────────┐
              │ copilot-instructions.md │
              │                         │
              │ POLICY                  │
              └────────────┬────────────┘
                           │
             ┌─────────────▼─────────────┐
             │       *.prompt.md         │
             │                           │
             │ PROCEDURE                 │
             └─────────────┬─────────────┘
                           │
                    Developer task
                           │
                           ▼
                       GPT model
                           │
                           ▼
                       Changes
                           │
                           ▼
                       CI/CD

This separation matters because the two layers evolve differently.

Architecture rules may remain stable for months.

A code-review procedure may improve every few weeks as the team learns which prompts produce useful findings and which produce noise.

Treating both as one document would make each harder to maintain.

5. Build workflows, not clever one-liners

A good prompt file should represent a bounded piece of engineering work.

Useful examples include:

architecture-review.prompt.md
implementation-plan.prompt.md
implement-feature.prompt.md
generate-tests.prompt.md
review-code.prompt.md

Each has a clear responsibility.

This also helps with one of the most dangerous habits in agentic development: giving the model an enormous objective and allowing every phase of engineering to collapse into one opaque execution.

Instead of:

Analyze architecture,
fix problems,
generate tests,
update documentation,
run everything,
commit changes.

prefer composable workflows:

architecture-review
        ↓
implementation-plan
        ↓
implement-change
        ↓
test-generation
        ↓
code-review

The difference is not just prompt organization.

It creates explicit checkpoints where a human can inspect what the model believes before the next action begins.

6. Today’s repository exercise: architecture review

The first prompt file I would create is deliberately read-only:

.github/prompts/architecture-review.prompt.md

A useful starting procedure is:

Analyze the repository architecture.

Do not modify files.

Determine:

- application entry points
- major modules
- dependency direction
- domain boundaries
- infrastructure boundaries
- external integrations
- important interfaces
- configuration flow
- state management
- test architecture

Then identify:

- dependency violations
- duplicated abstractions
- infrastructure leaking into business logic
- inappropriate coupling
- circular dependencies
- unclear ownership boundaries
- architectural inconsistencies

For every conclusion, reference repository evidence.

Separate:

CONFIRMED
Evidence directly exists in the repository.

INFERRED
Strongly implied by repository structure.

UNKNOWN
Insufficient evidence.

Finish with a Mermaid dependency diagram.

This prompt is useful because it does several things at once without becoming an uncontrolled implementation task.

It defines the investigation surface.

It asks for evidence.

It separates facts from inference.

And it prevents modification while you are evaluating the agent’s understanding.

7. Do not merely consume the output: try to prove it wrong

The architecture report is not the end of the exercise.

The important next step is to challenge it.

Pick three conclusions the agent made.

Open the referenced files yourself.

Ask:

Is this conclusion actually supported by the code?

Did the model miss another implementation?

Did it mistake an old pattern for the current one?

Did it describe an inference as if it were a fact?

This changes your relationship with AI output.

You move from:

AI produced analysis
      ↓
I consumed it

into:

AI produced hypothesis
      ↓
Repository provides evidence
      ↓
Engineer validates conclusion

That is the beginning of AI reliability engineering at the developer-workflow level.

The goal is not to make the model sound authoritative.

The goal is to make its reasoning inspectable enough that a human can challenge it.

8. Common mistakes

8.1 Version-controlling trivial commands

Write tests.

There is too little procedure here to justify a shared workflow artifact.

A prompt file should encode a repeatable reasoning pattern, not merely save a few keystrokes.

8.2 Creating a mega-agent prompt

Analyze architecture,
fix all problems,
generate tests,
update documentation,
run everything,
and commit the changes.

This bundles discovery, design, implementation, validation and publication into one operation.

The result may be impressive, but it becomes much harder to understand where a wrong assumption entered the process.

Prefer bounded, composable stages.

8.3 Hardcoding repository facts into generic workflows

This is subtle.

Suppose a reusable prompt says:

StateStore lives in src/state/interface.py.

That may be true today and false after the next refactor.

A stronger procedure says:

Locate the existing state-management abstraction before implementing.

The workflow remains stable while the repository evolves.

Prompts should encode procedures, not stale repository facts.

9. Advanced challenge: build an AI change pipeline

Once one prompt works, create four deliberately bounded workflows:

.github/prompts/

01-analyze.prompt.md
02-plan.prompt.md
03-implement.prompt.md
04-review.prompt.md

The development flow becomes:

Ticket
  │
  ▼
ANALYZE
"What actually exists?"
  │
  ▼
PLAN
"What should change?"
  │
  ▼
IMPLEMENT
"Make only those changes."
  │
  ▼
REVIEW
"Try to prove the implementation wrong."
  │
  ▼
Human review
  │
  ▼
CI

This is one of the most important patterns in the entire training sequence.

We are decomposing software engineering into bounded LLM operations.

That has several benefits:

  • assumptions surface earlier;
  • scope is easier to inspect;
  • each stage has a clearer objective;
  • a bad plan can be corrected before code is generated;
  • review becomes a separate adversarial activity rather than self-confirmation;
  • human judgment remains present between meaningful transitions.

Compare this with giving an agent:

Implement ticket ABC-123.

and receiving seventeen changed files before you have seen its architectural assumptions.

The second workflow gives the model more autonomy than the engineering process can safely absorb.

10. Prompt files become engineering artifacts

Once prompts live in Git, something important changes.

You can version them.

architecture-review v1
        ↓
architecture-review v2
        ↓
architecture-review v3

Now the team can ask engineering questions about the prompt itself:

Did v3 detect more real defects?

Did false positives decrease?

Did token usage increase?

Did developers accept more recommendations?

This is a much stronger mindset than:

I found a prompt that seems good.

The prompt becomes a maintained artifact with a history, reviewers and measurable outcomes.

And that is where prompt files start connecting naturally to evals.

If the workflow is stable enough to version, it is stable enough to compare.

If it is stable enough to compare, it can eventually be evaluated against known examples.

At that point, prompt engineering begins to look much more like ordinary engineering.

11. What this changes for engineering leads

For an individual developer, a prompt file saves repetition.

For an engineering lead, the more interesting benefit is workflow standardization.

The team can now have a shared answer to questions such as:

How do we ask AI to review architecture?

How do we ask it to review a patch?

How do we distinguish fact from inference?

What evidence should an AI reviewer return?

Which phases are allowed to modify files?

That reduces dependency on individual prompt-writing skill.

It also gives the team something concrete to review during adoption.

A prompt change can be discussed in a pull request just like a test strategy or CI rule:

Why did we add this review category?

Does this instruction create noise?

Should this stage remain read-only?

What outcome are we trying to improve?

That is a healthier organizational model than asking every engineer to become a prompt specialist.

12. A measurable team experiment

Introduce one standardized code-review prompt into one repository.

Use it for the next 10 pull requests.

For each run, record:

AI findings accepted by human reviewer
--------------------------------------
Total AI findings

For example:

Copilot findings:      34
Accepted as valid:     26
Rejected/noise:         8

Precision = 26 / 34
          = 76%

Do not optimize for the number of findings.

A review prompt that produces forty warnings but only five useful ones is not necessarily better than a prompt that produces eight findings and seven are actionable.

The target from this exercise is to evolve the workflow until developers trust it enough that roughly 80% or more of the reported findings are genuinely useful.

That metric is simple, but it introduces a much more important principle:

Do not measure whether engineers are using AI. Measure whether AI workflows produce reliable engineering outcomes.

Usage is not quality.

Adoption is not correctness.

The interesting question is whether the standardized workflow improves engineering decisions.

13. Where to go next

At this point the repository contains two complementary layers:

Repository instructions
        ↓
Persistent engineering policy

Prompt files
        ↓
Reusable engineering procedures

The next step is where things become more powerful and more dangerous.

A workflow no longer has to stop at producing text.

The model can begin using tools, editing files, running tests and iterating against the environment.

That is the transition from reusable prompting into agentic engineering.

And once the model can act, the decomposition we built here becomes even more important.

Next lesson: Day 4 : Control What Copilot Reads Before It Reasons

Tags :
  • AI-assisted Dev
  • GitHub Copilot
  • Prompt Files
  • Engineering Workflows