Skip to content

codex-guide.md

Latest commit

 

History

History
222 lines (159 loc) · 5.61 KB

codex-guide.md

File metadata and controls

222 lines (159 loc) · 5.61 KB
Raw

Using zero-skills with Codex

This guide explains how to use zero-skills with OpenAI Codex, the AI coding agent from OpenAI.

Installation

Step 1: Clone zero-skills

cd your-gozero-project/

# Clone to a local directory
git clone https://github.com/zeromicro/zero-skills.git .ai-context/zero-skills

Step 2: Create AGENTS.md

Create AGENTS.md in your project root:

# go-zero Development Instructions

You are an expert in go-zero microservices framework development.

## Architecture

Follow the three-layer architecture strictly:
- **Handler**: HTTP routing and request/response handling only
- **Logic**: All business logic goes here, injected via ServiceContext
- **Model**: Data access and database operations, generated by goctl

## Code Patterns

### REST API Logic
```go
func (l *UserLogic) GetUser(req *types.GetUserReq) (*types.GetUserResp, error) {
    user, err := l.svcCtx.UserModel.FindOne(l.ctx, req.Id)
    if err != nil {
        return nil, err
    }
    return &types.GetUserResp{
        Id:   user.Id,
        Name: user.Name,
    }, nil
}

Error Handling

  • Use httpx.Error(w, err) for HTTP errors
  • Use httpx.OkJson(w, resp) for success responses
  • Never use fmt.Fprintf() or w.Write() directly

Configuration

  • Load with conf.MustLoad(&c, *configFile)
  • Never hard-code ports, hosts, or credentials
  • Use environment-specific YAML files

Context

  • Always pass ctx context.Context through all layers
  • Use context for tracing, cancellation, and timeouts

Code Generation Commands

# Generate API service code
goctl api go -api user.api -dir .

# Generate RPC service code
goctl rpc protoc user.proto --go_out=. --go-grpc_out=. --zrpc_out=.

# Generate model from database
goctl model mysql datasource -url="user:pass@tcp(localhost:3306)/db" -table="users" -dir="./model"

Key Rules

  1. Never put business logic in handlers
  2. Always use ServiceContext for dependency injection
  3. Always pass ctx through all layers
  4. Use goctl for code generation, never hand-write boilerplate
  5. API definitions go in .api files; RPC definitions go in .proto files

Pattern References

Detailed patterns are in .ai-context/zero-skills/:

  • REST APIs: references/rest-api-patterns.md
  • RPC services: references/rpc-patterns.md
  • Database: references/database-patterns.md
  • Resilience: references/resilience-patterns.md
  • Troubleshooting: troubleshooting/common-issues.md

## Usage

### Running Codex

Run Codex from your project directory:

```bash
codex "Create a user management REST API with go-zero including CRUD operations"

Codex will read AGENTS.md automatically and apply go-zero patterns to all generated code.

Reference Pattern Files

For detailed patterns, tell Codex to read the relevant file:

Read .ai-context/zero-skills/references/rest-api-patterns.md and help me implement a user API

Example Tasks

Creating a REST API:

Create a user management REST API with CRUD operations following go-zero patterns

Adding RPC service:

Add a gRPC user service following the go-zero rpc patterns in .ai-context/zero-skills/references/rpc-patterns.md

Database integration:

Read .ai-context/zero-skills/references/database-patterns.md and add MySQL support with caching to my user service

Troubleshooting:

Read .ai-context/zero-skills/troubleshooting/common-issues.md and help me fix this error: ...

Example Workflows

Creating a New Service

  1. Define the API file:

    Create a user.api file for a user management service with login, register, and profile endpoints

  2. Generate code:

    goctl api go -api user.api -dir .

  3. Implement logic:

    Implement the business logic for all user handlers following go-zero patterns

Adding Database Support

  1. Generate the model:

    goctl model mysql datasource -url="user:pass@tcp(localhost:3306)/db" -table="users" -dir="./model"

  2. Wire it up:

    Add the user model to ServiceContext and implement data access in the logic layer

Tips

Keep AGENTS.md Focused

Codex reads AGENTS.md for every task. Keep it concise:

  • Core principles only
  • Short code examples
  • Reference external files for detailed patterns

Multi-file Tasks

Codex handles multi-file changes well. Describe the full feature:

Add JWT authentication to all protected API routes, following go-zero middleware patterns

Combine with ai-context

For a richer context setup, use ai-context alongside zero-skills:

git clone https://github.com/zeromicro/ai-context.git .ai-context/ai-context

Then reference both in AGENTS.md:

Follow workflows from .ai-context/ai-context/
For detailed go-zero patterns, see .ai-context/zero-skills/

Limitations

Compared to Claude Code, Codex:

  • No native skills support (YAML frontmatter not used)
  • No automatic skill loading by file type
  • No subagent workflows
  • Manual file references needed for detailed patterns

Troubleshooting

AGENTS.md Not Applied

Problem: Codex doesn't follow go-zero patterns.

Solutions:

  1. Ensure AGENTS.md exists in the project root where you run codex
  2. Check that the file is valid Markdown
  3. Reference pattern files explicitly in your prompt

Context Too Large

Problem: Instructions are too long and patterns are ignored.

Solutions:

  1. Keep AGENTS.md under 500 lines
  2. Move detailed patterns to separate files in .ai-context/zero-skills/
  3. Reference them on demand in prompts