Update Instruction

Manage Instruction Templates

Instructions are persistent context and rules that apply to AI conversations, scoped by file patterns or always-on.

Finding the Right Instruction

1. Search existing instructions

List files in <%= instructionTemplatePath() %>/ and read their frontmatter (description, globs) to understand what each covers and its scope.

2. Match the user's intent to existing files

Look for instructions that already cover the same topic or a closely related topic. Consider:

• Exact match: an instruction about the same subject exists → update it
• Partial overlap: the topic fits within the scope of a broader instruction → add to it rather than creating a separate file
• Multiple candidates: several instructions touch on the topic → pick the one whose globs and purpose align best with the user's intent

3. Determine scope for new instructions

If no existing instruction fits, investigate the project to decide where the instruction belongs:

1. Search the codebase for how the topic is used — find which files and directories are relevant
2. Cross-reference with the user's wording — the instruction may apply broadly (e.g. "always validate env vars") or narrowly (e.g. "feature flags in API routes should use env vars")
3. Choose the right scoping:
   • If the rule is universal across the project → use alwaysApply: true
   • If it applies to a specific area → use globs matching only the relevant files/directories
   • If the topic appears in many places but the instruction only makes sense for a subset, scope to that subset

Example: The user says "feature flags should be loaded from env vars." Feature flags might appear in 10 places across the codebase, but if only the API layer loads them from config, the right scope is globs: ["src/api/**"] rather than alwaysApply: true.

Deciding What to Do

• Create new: when the topic is distinct from all existing instructions
• Update existing: when an instruction already covers the topic but needs changes — modify its content or frontmatter
• Add per-target override: when a frontmatter field needs different values per target, use the override object syntax:

  description:
    claude: Claude-specific description
    copilot: Copilot-specific description
    default: Default description
  

• Delete: when an instruction is obsolete or fully superseded by another

Creating a New Instruction

1. Create a .md file in <%= instructionTemplatePath() %>/ with a descriptive name (e.g. error-handling.md)
2. Add YAML frontmatter with at minimum a description
3. Write the instruction body

Frontmatter Fields

See the Instructions section in <%= instructionPath('uac-template-guide') %> for the complete field reference. Key fields: description, globs, alwaysApply, excludeAgent.

When to use alwaysApply vs globs

• Use alwaysApply: true for project-wide conventions that should always be active
• Use globs to scope instructions to specific file types or directories (e.g. ["src/api/**"] for API-specific rules)
• If neither is set, the instruction may still be applied by some targets based on relevance

Codex routing

For Codex, multiple instruction templates consolidate into a single AGENTS.md at the project root or per-directory AGENTS.override.md files (see the "Codex caveats" section in <%= instructionPath('uac-template-guide') %>). Routing rules:

• alwaysApply: true → root AGENTS.md
• globs with a resolvable directory prefix (e.g. packages/frontend/**) → <dir>/AGENTS.override.md
• Leading-wildcard or absent globs → root AGENTS.md

If you want a template to land at a specific directory in Codex but not affect other targets, use a per-target glob override: globs: { codex: ["src/api/**"], default: ["**/*.ts"] }.

Editing globs moves the Codex output file. Changing packages/frontend/** to packages/api/** emits packages/api/AGENTS.override.md and leaves the old packages/frontend/AGENTS.override.md behind, where Codex keeps reading it. Run uac generate --clean (not plain uac generate) after any glob change — clean scans the project tree for that basename and removes the orphan.

Example

---
description: TypeScript coding conventions
globs: ["**/*.ts", "**/*.tsx"]
---

Follow these TypeScript conventions:

- Use strict mode
- Prefer interfaces over type aliases for object shapes
- Use explicit return types on exported functions