A project rule can be clear about its preferred behavior and still leave its boundary unclear. One small counterexample can show where the rule stops applying.
My thesis: when an APC instruction is easy to overgeneralize, add a nearby case that looks similar but requires a different decision. This gives reviewers a concrete way to check the instruction's meaning.
APC is the portable context layer: repository-owned guidance in AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer that works with that context. Neither distinction removes the need to write instructions that a new contributor can interpret correctly.
Show the boundary, not just the happy path
Consider a hypothetical repository with this instruction:
Every user-visible label starts with a capital letter.
An agent could reasonably apply that sentence to every string rendered on screen. That would include command names, file paths, and fragments inserted into a longer sentence. The instruction needs a sharper definition of “label.”
A more useful version might say:
Start interface labels with a capital letter: buttons, headings, and tabs.
Example: "Project memory".
Preserve literal commands and paths exactly.
Counterexample: displaying `apx restart` does not make it "Apx restart".
Sentence fragments follow the sentence they join.
The counterexample does useful work because it is close to the rule. Both cases involve text on screen. The difference is whether the text names an interface element or represents a literal value.
This example is grounded in the APX repository's engineering guide, which distinguishes labels, sentence fragments, and data such as commands and slugs. The shortened wording above is an illustration, not a replacement for that repository's full contract.
Choose a plausible mistake
“Do not capitalize binary files” would be a weak counterexample here. It is too far from the decision an agent is likely to face.
A useful counterexample has three properties:
- It shares the feature that could trigger the rule: here, visible text.
- It identifies the distinguishing property: here, an exact command spelling.
- It states the correct action: preserve the literal value.
The same pattern works in other domains. A hypothetical instruction to retry read failures could distinguish a failed read from a write whose outcome is unknown. A rule to normalize display names could explicitly preserve stable identifiers. Those are writing examples; each repository must define its actual behavior and constraints.
Avoid building a catalog of every possible exception. Choose the nearest misunderstanding that changes the outcome. If many exceptions are necessary, rewrite the main rule or split it into narrower rules.
Keep examples beside the instruction
The APC rules specification separates the root contract in AGENTS.md from reusable or path-scoped guidance in .apc/rules/. It also asks that rules remain concise, concrete, and reviewable.
Put the boundary example next to the relevant rule, wherever that rule belongs. A counterexample buried in a separate chat will not help a reader who receives only the instruction. Duplicating it across several files creates another maintenance problem.
During review, ask someone to classify two cases: one that should follow the rule and one that should not. If reasonable readers disagree, the text still needs work. This is a proposed review technique, not an APC validator or an APX feature that automatically checks prose.
Executable checks remain valuable where the distinction can be tested. The written rule explains the intended boundary; a test can catch a specific violation. An example alone does not enforce anything.
Portable context should carry enough meaning to survive a change of reader. Sometimes the most useful addition is one sentence showing exactly where an otherwise sensible rule stops.
Explore Agent Project Context on GitHub.
Top comments (0)