# 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**:
```json
{
  "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):
```powershell
[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