A Reusable Context Block for Every Codex Project

At work, we have many microservices. Each service has its own Git repository. This is good for keeping services separate, but it creates another problem: no single repository explains the full system.

Repository A may contain the orders service. Repository B may contain the payments service. But a task in orders may still depend on a payment rule, a shared database field, or an event used by another team.

Codex needs this wider context to make the right change. But I also do not want to add every code repository to every Codex project. A project should contain only the code needed for that task.

My solution is to keep the shared information in a separate context repository and attach it wherever it is needed.

Think of context as a Tetris block

The picture above shows the main idea.

The context repository is like a reusable Tetris block. I can fit the same block into different Codex projects. The code beside it changes based on the task, but the shared context block stays available.

This keeps each project focused:

• Project A contains Repository A and the context block.
• Project B contains Repository B and the context block.
• Project C contains Repositories A and B with the same context block.

The third setup is useful when one task needs simultaneous changes across two services. Codex can see both codebases and the shared rules that connect them.

What is the context repository?

The context repository is a normal Git repository. It mainly contains Markdown files that explain the system.

It can include:

• database schemas;
• business rules;
• API contracts;
• event details;
• links between services; and
• notes about which team owns each service.

The repository does not run in production. Its purpose is to give developers and Codex a clear map of the system.

Why keep it in Git?

We can store this information in Lucidchart, Confluence, or another documentation tool. Those tools are useful for people, especially when we want to explain something visually.

But Git gives us a few extra benefits:

• Codex can read the files while working with the code.
• Every change is tracked.
• We can review changes through pull requests.
• We can see who changed a rule and why.
• Every developer can use the same version of the context.

This makes the context part of our engineering work instead of a document that slowly becomes outdated.

How I use it with Codex

I attach the context repository to every Codex project that needs system-level information, just like adding the same Tetris block to a new layout.

The code repositories depend on the task. I add only the codebase—or part of the architecture—that I am working on.

Project A

If I am changing Repository A, I create a focused Codex project with:

• Repository A as the main work repository; and
• the context repository as a reference.

Codex reads the shared rules and schemas, then makes the change in Repository A.

Project B

If the task belongs to Repository B, I create another focused project with:

• Repository B as the main work repository; and
• the same context repository as a reference.

The code repository changes, but the source of shared context stays the same.

Project C

Some tasks need simultaneous changes in more than one service. For example, a schema change in Repository A may also require an update in Repository B.

For that task, the Codex project can include:

• Repository A;
• Repository B; and
• the context repository.

Codex can now understand the shared rule and work across both repositories at the same time. The context block helps it see how the two codebases fit together.

A simple example

Suppose I want to add partial order cancellation.

The orders repository contains the order code. The payments repository contains refund code. The context repository explains the cancellation rules, the order schema, and the events shared by both services.

My prompt can be simple:

Add support for partial order cancellation. Read the cancellation rules, order schema, and event details from the context repository first. Update the orders and payments repositories where needed. Tell me if the code and the documents do not match.

Codex now has three things:

• the task;
• the repositories where it must make changes; and
• the shared context needed to make those changes correctly.

Keeping the context useful

This approach works only if the context repository stays up to date.

When we change a schema, business rule, API, or event, we also update the related document. The update should be reviewed just like a code change.

A few simple rules help:

• give important documents clear owners;
• review changes through pull requests;
• explain why a rule changed;
• link rules to the services that use them; and
• clearly mark old or proposed information.

If the document and the code do not match, Codex should point out the difference. It should not silently guess which one is correct.

The main benefit

Without shared context, every task starts with searching across repositories and asking people how the system works. Codex faces the same problem.

With a context repository, the important knowledge is in one tracked place. I can attach that reusable block to a project with one code repository or to a project with several repositories for a simultaneous change.

The idea is simple: keep each Codex project focused on the code it needs, then attach the shared context block for better results.