Write AGENTS.md Rules for a Social Content Repository

A social content repository can contain facts, drafts, examples, templates, and publishing notes. When Codex works in that repository, it needs to understand which files are evidence and which are editable output. A well-written AGENTS.md file gives it durable guidance without forcing every task prompt to repeat the same editorial rules.

The useful goal is a small set of instructions that can be checked. “Write excellent content” is not enough. “Use the current product-facts file for availability claims and list unsupported claims before drafting” tells the assistant what to do and gives a reviewer something concrete to inspect.

Understand where the instructions apply

OpenAI's AGENTS.md documentation explains how Codex discovers project instructions and how more specific guidance can apply within a repository. Read that documentation for the current rules rather than assuming every instruction file in every folder is automatically loaded.

For an editorial workspace, put broad expectations near the root and specialized requirements near the content they govern. A shared rule might prohibit invented customer results. A folder for release announcements might additionally require an approved release identifier. A folder for evergreen education may need a review date for factual sources.

Keep the scope understandable to humans as well. Someone opening the repository should know which instructions govern a draft and where to change them. If the rules are spread across several unexplained files, the assistant and the team may both miss important context.

This is different from a brand voice guide. The voice guide describes editorial expression; AGENTS.md tells the agent how to work with files, evidence, and verification in this project.

Write rules around observable behavior

Choose instructions that address actual failure modes. If drafts repeatedly invent numbers, require every numerical claim to name its source or be removed. If old screenshots cause confusion, require a current asset reference before describing a visible interface.

A good rule identifies the action and the reason. “Do not overwrite research notes while editing a draft; preserve the evidence used for factual review” is clearer than a vague warning to be careful with sources. It also tells the assistant what to preserve when making a change.

Avoid turning the file into a giant style dictionary. Rules that rarely matter can obscure the few that protect the workflow. Keep examples and detailed reference material in separate documents and link to them from the relevant instruction.

For a Caroush content project, an instruction could require the agent to distinguish draft creation from publication. That is a meaningful product boundary. It should not merely demand that the writing “sound less AI,” which gives no reliable test for success.

Define the source hierarchy

Name the authoritative files or documentation locations for product facts. Explain how to handle contradictions. A current approved feature record should not lose to an older campaign draft simply because the older wording is more polished.

Separate fact sources from style examples. A sample caption can show a useful opening but contain a historical price or a retired feature. Tell Codex to use examples for expression only unless they are explicitly marked as current factual material.

Add a missing-information rule: if a requested claim is unsupported, the agent should identify the gap and continue work that does not depend on it. This avoids two unhelpful extremes: inventing an answer or stopping the whole task because one optional detail is absent.

The content audit guide can help you establish which materials remain current before you encode the hierarchy. An instruction file cannot repair a repository whose “approved facts” document is itself outdated.

Give editing tasks a clear finish line

Specify what the agent should return after an edit. A useful handoff includes changed files, important factual decisions, checks performed, and unresolved questions. It should not be a transcript of every action taken.

For example, a task might require a Markdown draft, metadata, and a source note. The instruction should make clear whether the agent may alter all three or only the draft. If a title changes, dependent metadata may need updating, but that relationship should be explicit.

A practical test prompt is:

Read the applicable repository instructions. Revise this draft for the specified audience using the current fact sources. Preserve source notes, flag unsupported claims, and report the files changed plus any remaining publication conditions. Do not treat an editorial draft as authorization to publish.

Use your approval workflow to define who accepts the result. The repository can describe the review path, but a file should not silently grant powers the user or organization has not authorized.

Test instruction discovery before trusting it

Ask Codex to summarize which instructions it loaded and how they affect the current task. Compare that summary with the actual repository structure and the official documentation. This is especially useful when nested folders contain different guidance.

Then give it a small, deliberate challenge. Provide a draft with one unsupported result, one old product name, and one valid statement. The expected outcome is a focused correction that preserves the valid content. If the assistant rewrites everything, the editing scope may be too vague.

Test a missing-source case too. The agent should explain what evidence is absent rather than treating an old draft as proof. Save the test case as a lightweight review example; you do not need a complex automated suite for every stylistic preference.

OpenAI's MCP documentation describes how Codex can access connected tools. Tool access and repository guidance are separate concerns. A writing rule does not prove that a remote service is configured, available, or authorized for the requested action.

Keep credentials and transient state out of the rules

AGENTS.md should describe where authenticated workflows are documented, not contain access tokens or passwords. A public content repository is especially unsuitable for secrets, but even a private repository should avoid turning instruction files into credential storage.

Do not place temporary outage notes or one-off campaign dates in global rules unless they truly need broad scope. Put time-sensitive information in a current campaign record with an owner and review date. Otherwise a temporary exception can quietly become a permanent instruction.

For Caroush, link to the current client documentation when a task uses MCP. Codex is documented as a client, but users should verify current service availability and follow the approval requirements. Do not invent a static token fallback if the documented workflow uses OAuth.

This keeps the editorial rules stable while letting product configuration and current campaign facts change in the appropriate places.

Include one example of an acceptable handoff in the repository. It can show a concise change summary, a source reference, the checks run, and an unresolved factual question. This example makes the output expectation concrete without adding many abstract instructions. Keep it short enough that a contributor can scan it before starting. When the workflow changes, update the example alongside the rule so the assistant does not receive two different standards for completion.

Review rules when the workflow changes

When an instruction fails, investigate whether it was missing, unclear, not discovered, or contradicted by another instruction. Adding a stronger warning is not always the answer. Sometimes the right fix is a better source file or a narrower task.

Remove rules that no longer reflect the process. If a manual step has been replaced, update the instruction and the example task together. Keep a short rationale for important changes so future editors can understand why the rule exists.

The result should support production through Caroush's social media tools without making the content workspace harder to use. A good instruction file is easy to read, easy to test, and specific enough to help the assistant make the right small decisions repeatedly.