CLAUDE.md and context engineering for coding agents

When building a product with coding agents, a substantial part of the work is deciding which information the agent should use to make decisions. In Monafy, I use a workspace-level CLAUDE.md file together with short repository-specific instructions to keep recurring development decisions visible.

I define the product behavior, architectural boundaries and acceptance criteria before implementation. The agent implements within that context. A useful instruction file makes this division of responsibility explicit, explains how work is checked and identifies the source to consult when information is uncertain.

Establishing which sources carry authority

A multi-repository product exposes an agent to code, design notes, earlier plans and summaries of previous sessions. Treating all of them as equally authoritative can turn an outdated assumption into a new implementation decision. I therefore put source priority near the beginning of the instructions.

If the current request conflicts with an older plan, the plan should not silently win. Third-party files and generated output are reference material rather than project instructions. A sentence written as a command does not gain authority simply because the agent encounters it while reading a file.

Making acceptance criteria checkable

“Make it work correctly” leaves too much interpretation to the implementation. I describe the input, the expected result, the error condition that should stop an operation and the place where its outcome can be observed. The implementer and reviewer can then use the same checkpoint.

Missing financial data is a useful example. Displaying zero when a value was not provided can imply a measurement that never existed. The instruction specifies the intended missing-value presentation and the fallback patterns to look for, rather than merely asking the agent to handle missing data carefully.

The same principle applies to completion reports. A command that was not run must remain unverified. A source file containing a test is evidence of intended behavior, while an actual passing run establishes something different. Keeping these distinctions explicit makes the development record easier to review.

Refreshing context during a long task

A file read at the start of a long session may have changed. A conversation summary may also omit the reason or boundary behind a decision. Before significant edits, I require the current source and current task to be read again.

This is the context-engineering part of the workflow. It is not just a matter of writing a longer prompt. The relevant source needs to be available when the decision is made. A compact progress record can preserve the task's purpose, current decisions and checks that remain unrun without making every step reread the entire history.

Giving shared rules a single home

The workspace file carries rules that apply across repositories. Local files contain the service's commands and specific boundaries. Copying the full shared policy into each repository creates versions that can drift apart, as I describe in the case study on instruction consistency.

When changing a rule, I search for its earlier wording too. Updating the authoritative file does not establish that another handbook has stopped describing the old behavior. References also need to resolve from the actual checkout or worktree where the agent will use them.

Separating work across parallel sessions

One session can examine a data contract while another works on the interface. I give each a bounded task, the area it may change and an expected result. Ownership of shared files is agreed before editing. If both tasks depend on the same unresolved decision, I settle that decision before trying to advance them independently.

Separate Git worktrees can isolate independent changes within a repository. A Git worktree provides another working directory; it does not automatically isolate databases or external services. Separating source files and separating the runtime environment therefore require different checks.

When a session reports completion, I read the change and its verification output. Once the pieces are integrated, their shared behavior needs checking too. The Claude Code parallel-work guide explains the tools; defining useful task boundaries remains part of our engineering work.

A compact instruction example

This simplified example keeps scope and completion criteria together. The commands depend on the technology in use, but the expected result should remain observable.

1## Scope
2Change only the requested behavior.
3
4## Verification
5Define the input, expected result and failure case.
6State which checks were not run.

Including the reason for a rule

A rule becomes more useful when its reason helps the agent evaluate a related situation that was not listed explicitly. Knowing why per-event logging becomes expensive in a busy stream is more transferable than memorizing a ban on one particular log statement.

I keep the incident history in its report. The instruction file retains the decision that changes behavior and the reason it exists. Because the file is read repeatedly, each new paragraph should earn its place by improving a decision the agent will actually make.