Claude-Code-Workflow/.codex/AGENTS.md

Codex Code Guidelines

Code Quality Standards

Code Quality

• Follow project's existing patterns
• Match import style and naming conventions
• Single responsibility per function/class
• DRY (Don't Repeat Yourself)
• YAGNI (You Aren't Gonna Need It)

Testing

• Test all public functions
• Test edge cases and error conditions
• Mock external dependencies
• Target 80%+ coverage

Error Handling

• Proper try-catch blocks
• Clear error messages
• Graceful degradation
• Don't expose sensitive info

Core Principles

Incremental Progress:

• Small, testable changes
• Commit working code frequently
• Build on previous work (subtasks)

Evidence-Based:

• Study 3+ similar patterns before implementing
• Match project style exactly
• Verify with existing code

Pragmatic:

• Boring solutions over clever code
• Simple over complex
• Adapt to project reality

Context Continuity (Multi-Task):

• Leverage resume for consistency
• Maintain established patterns
• Test integration between subtasks

Git Operations (Parallel Task Safety):

• Only stage/commit files directly produced by current task
• Never touch unrelated changes or other task outputs
• Use git add <specific-files> instead of git add .
• Verify staged files before commit to avoid cross-task conflicts

System Optimization

Direct Binary Calls: Always call binaries directly in functions.shell, set workdir, avoid shell wrappers (bash -lc, cmd /c, etc.)

Text Editing Priority:

1. Use apply_patch tool for all routine text edits
2. Fall back to sed for single-line substitutions if unavailable
3. Avoid Python editing scripts unless both fail

apply_patch invocation:

{
  "command": ["apply_patch", "*** Begin Patch\n*** Update File: path/to/file\n@@\n- old\n+ new\n*** End Patch\n"],
  "workdir": "<workdir>",
  "justification": "Brief reason"
}

Windows UTF-8 Encoding (before commands):

[Console]::InputEncoding  = [Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
chcp 65001 > $null

Context Acquisition (MCP Tools Priority)

For task context gathering and analysis, ALWAYS prefer MCP tools:

1. mcp__ace-tool__search_context - HIGHEST PRIORITY for code discovery

   • Semantic search with real-time codebase index
   • Use for: finding implementations, understanding architecture, locating patterns
   • Example: mcp__ace-tool__search_context(project_root_path="/path", query="authentication logic")

2. smart_search - Fallback for structured search

   • Use smart_search(query="...") for keyword/regex search
   • Use smart_search(action="find_files", pattern="*.ts") for file discovery
   • Supports modes: auto, hybrid, exact, ripgrep

3. read_file - Batch file reading

   • Read multiple files in parallel: read_file(path="file1.ts"), read_file(path="file2.ts")
   • Supports glob patterns: read_file(path="src/**/*.config.ts")

Priority Order:

ACE search_context (semantic) → smart_search (structured) → read_file (batch read) → shell commands (fallback)

NEVER use shell commands (cat, find, grep) when MCP tools are available.

Execution Checklist

Before:

• Understand PURPOSE and TASK clearly
• Use ACE search_context first, fallback to smart_search for discovery
• Use read_file to batch read context files, find 3+ patterns
• Check RULES templates and constraints

During:

• Follow existing patterns exactly
• Write tests alongside code
• Run tests after every change
• Commit working code incrementally

After:

• All tests pass
• Coverage meets target
• Build succeeds
• All EXPECTED deliverables met