Một ngày nọ, tôi hỏi AI: “Review code này, đồng thời fix bugs và viết documentation.”

Kết quả? Code được sửa nhưng sai logic ban đầu. Documentation viết lung tung. Review thì...không có review.

AI đã cố gắng làm 3 việc cùng lúc, và thất bại ở cả 3.

Đó là lúc tôi học được bài học quan trọng nhất về AI: **”One AI, one job.”**

Hôm nay tôi sẽ chỉ bạn cách tạo nhiều AI assistants chuyên biệt với OpenCode Agents - mỗi “nhân viên AI” chỉ làm đúng một việc, và làm xuất sắc việc đó.

Agents là gì trong OpenCode?

Agents là specialized AI assistants được configure cho specific tasks và workflows. Mỗi agent có thể có:

- Custom prompts riêng cho task cụ thể

- Specific models phù hợp với công việc

- Tool access được giới hạn theo nhu cầu

- Permissions kiểm soát những gì agent được làm

Ví dụ thực tế:

| Agent | Purpose | Tools | Best for |

| ------------ | ---------------- | ------------- | ----------------------- |

| **Build** | Full development | All enabled | Writing code, debugging |

| **Plan** | Analysis only | Read-only | Review, planning |

| **Reviewer** | Code review | No edit/write | Quality assurance |

| **Docs** | Documentation | File ops only | Writing docs |

Hai loại Agents: Primary vs Subagents

Primary Agents

Main assistants bạn interact trực tiếp. Dùng Tab key để switch giữa các primary agents.

OpenCode có 2 built-in primary agents:

1. Build (Default)

- Mode: primary

- All tools enabled

- Dùng cho development work với full access

2. Plan

- Mode: primary

- Restricted permissions (ask before edit/bash)

- Dùng để analyze code, suggest changes mà không modify codebase

Pro tip: Dùng Tab để switch: Build (write code) → Plan (review) → Build (fix)

Subagents

Specialized assistants được primary agents invoke cho specific tasks. Bạn cũng có thể @ mention manual:

@general help me search for this function

OpenCode có 1 built-in subagent:

General

- Mode: subagent

- Research, search code, execute multi-step tasks

- Dùng khi search keywords/files và không confident tìm đúng trong first few tries

Cách sử dụng Agents

1. Switch Primary Agents

# Dùng Tab key để cycle qua primary agents

Build → Plan → Build → ...

2. Invoke Subagents

Automatically: Primary agents tự invoke subagents dựa trên descriptions.

Manually: @ mention trong message:

@general search for authentication functions

@security-auditor check this API endpoint

@docs-writer create README for this module

3. Navigate Sessions

Khi subagents create child sessions, navigate với keybinds:

- <Leader>+Right: Cycle forward (parent → child1 → child2 → parent)

- <Leader>+Left: Cycle backward

Configure Agents: JSON và Markdown

Cách 1: JSON trong opencode.json

{

  “$schema”: “https://opencode.ai/config.json”,

  “agent”: {

    “build”: {

      “mode”: “primary”,

      “model”: “anthropic/claude-sonnet-4-20250514”,

      “prompt”: “{file:./prompts/build.txt}”,

      “tools”: {

        “write”: true,

        “edit”: true,

        “bash”: true

      }

    },

    “plan”: {

      “mode”: “primary”,

      “model”: “anthropic/claude-haiku-4-20250514”,

      “tools”: {

        “write”: false,

        “edit”: false,

        “bash”: false

      }

    },

    “code-reviewer”: {

      “description”: “Reviews code for best practices and potential issues”,

      “mode”: “subagent”,

      “model”: “anthropic/claude-sonnet-4-20250514”,

      “prompt”: “You are a code reviewer. Focus on security, performance, and maintainability.”,

      “tools”: {

        “write”: false,

        “edit”: false

      }

    }

  }

}

Cách 2: Markdown Files

Locations:

- Global: ~/.config/opencode/agent/

- Per-project: .opencode/agent/

File name = Agent name (review.md → @review agent)

Example: ~/.config/opencode/agent/review.md

---

description: Reviews code for quality and best practices

mode: subagent

model: anthropic/claude-sonnet-4-20250514

temperature: 0.1

tools:

  write: false

  edit: false

  bash: false

---

You are in code review mode. Focus on:

- Code quality and best practices

- Potential bugs and edge cases

- Performance implications

- Security considerations

Provide constructive feedback without making direct changes.

Agent Options Chi Tiết

1. Description (Required)

Mô tả agent - dùng để invoke automatically và hiển thị trong UI:

{

  “agent”: {

    “review”: {

      “description”: “Reviews code for best practices and potential issues”

    }

  }

}

2. Temperature

Control creativity của responses:

| Range | Use Case |

| ----------- | --------------------------------------------------------------- |

| **0.0-0.2** | Very focused, deterministic - ideal cho code analysis, planning |

| **0.3-0.5** | Balanced - good cho general development |

| **0.6-1.0** | Creative, varied - useful cho brainstorming |

{

  “agent”: {

    “analyze”: {

      “temperature”: 0.1

    },

    “brainstorm”: {

      “temperature”: 0.7

    }

  }

}

3. Model

Override default model cho specific tasks:

{

  “agent”: {

    “plan”: {

      “model”: “anthropic/claude-haiku-4-20250514”

    },

    “complex-analysis”: {

      “model”: “anthropic/claude-sonnet-4-20250514”

    }

  }

}

Pro tip: Faster models cho planning, capable models cho implementation.

4. Tools

Control available tools:

{

  “$schema”: “https://opencode.ai/config.json”,

  “tools”: {

    “write”: true,

    “bash”: true

  },

  “agent”: {

    “plan”: {

      “tools”: {

        “write”: false,

        “bash”: false

      }

    }

  }

}

Agent config overrides global config!

Wildcards for MCP tools:

{

  “agent”: {

    “readonly”: {

      “tools”: {

        “mymcp_*”: false,

        “write”: false,

        “edit”: false

      }

    }

  }

}

5. Permissions

Fine-grained control - ”ask”, ”allow”, hoặc ”deny”:

{

  “$schema”: “https://opencode.ai/config.json”,

  “permission”: {

    “edit”: “deny”

  },

  “agent”: {

    “build”: {

      “permission”: {

        “edit”: “ask”

      }

    }

  }

}

Permissions cho specific bash commands:

{

  “agent”: {

    “build”: {

      “permission”: {

        “bash”: {

          “git push”: “ask”,

          “git status”: “allow”,

          “*”: “ask”

        }

      }

    }

  }

}

Markdown agents với permissions:

---

description: Code review without edits

mode: subagent

permission:

  edit: deny

  bash:

    “git diff”: allow

    “git log*”: allow

    “*”: ask

  webfetch: deny

---

Only analyze code and suggest changes.

6. Mode

| Mode | Description |

| ---------- | ---------------------------------- |

| `primary` | Main agent, switchable với Tab |

| `subagent` | Specialized, invoked via @ mention |

| `all` | Both (default) |

{

  “agent”: {

    “review”: {

      “mode”: “subagent”

    }

  }

}

7. Additional Provider Options

Pass-through provider-specific parameters:

{

  “agent”: {

    “deep-thinker”: {

      “description”: “Agent with high reasoning effort”,

      “model”: “openai/gpt-5”,

      “reasoningEffort”: “high”,

      “textVerbosity”: “low”

    }

  }

}

Create Agents: Interactive Command

Quick start:

opencode agent create

Interactive process:

1. Choose save location (global/project-specific)

2. Enter description

3. Generate system prompt and identifier

4. Select available tools

5. Create markdown file

Example Agents từ Official Docs

Documentation Agent

~/.config/opencode/agent/docs-writer.md:

---

description: Writes and maintains project documentation

mode: subagent

tools:

  bash: false

---

You are a technical writer. Create clear, comprehensive documentation.

Focus on:

- Clear explanations

- Proper structure

- Code examples

- User-friendly language

Security Auditor

~/.config/opencode/agent/security-auditor.md:

---

description: Performs security audits and identifies vulnerabilities

mode: subagent

tools:

  write: false

  edit: false

---

You are a security expert. Focus on identifying potential security issues.

Look for:

- Input validation vulnerabilities

- Authentication and authorization flaws

- Data exposure risks

- Dependency vulnerabilities

- Configuration security issues

Real-world Agent Workflows

Workflow 1: Feature Development

1. Plan (Tab): Analyze requirements và suggest approach

2. Build (Tab): Implement the feature

3. @reviewer: Review code before commit

4. @docs-writer: Update documentation

Workflow 2: Bug Fixing

1. Plan: Investigate và identify root cause

2. Build: Implement the fix

3. @reviewer: Final review

4. Commit!

Workflow 3: Code Review Process

1. @reviewer: Initial code review

2. @security-auditor: Security check

3. Build: Address feedback

4. @reviewer: Re-review

5. Merge!

Best Practices cho Agents

1. One Agent, One Job

Good:

---

description: Reviews code for security vulnerabilities

---

Focus ONLY on security issues...

Bad:

---

description: Reviews code, fixes bugs, and writes docs

---

Do everything at once... # Don’t do this!

2. Clear, Specific Prompts

Good:

## Output Format

For each issue:

- Location: file:line

- Severity: Critical/Major/Minor

- Issue: Description

- Fix: Suggestion

Bad:

Review the code and tell me what’s wrong.

3. Right Model for the Job

| Task | Recommended Model |

| ------------------ | ------------------- |

| Planning, Analysis | Haiku (fast, cheap) |

| Code Generation | Sonnet (balanced) |

| Complex Reasoning | Opus (powerful) |

| Quick Questions | Haiku |

4. Minimal Tool Access

{

  “agent”: {

    “reviewer”: {

      “tools”: {

        “write”: false,

        “edit”: false,

        “bash”: false

      }

    }

  }

}

Principle: Only enable tools the agent actually needs.

5. Temperature Tuning

| Use Case | Temperature |

| --------------- | ----------- |

| Code analysis | 0.1 |

| Code generation | 0.3 |

| Documentation | 0.4 |

| Brainstorming | 0.7 |

Troubleshooting Common Issues

Issue 1: Agent Not Found

Check file location:

# Global agents

ls ~/.config/opencode/agent/

# Project agents

ls .opencode/agent/

Check file extension: Must be .md

Issue 2: Agent Not Responding Correctly

Check description - primary agents invoke subagents based on descriptions:

---

description: Reviews code for SECURITY vulnerabilities # Be specific!

---

Issue 3: Wrong Model Used

Verify model name:

opencode models  # List available models

Check model config:

{

  “agent”: {

    “myagent”: {

      “model”: “anthropic/claude-sonnet-4-20250514”  # Exact name

    }

  }

}

Issue 4: Tools Not Working

Check tools config:

{

  “agent”: {

    “writer”: {

      “tools”: {

        “write”: true, // Explicitly enable

        “edit”: true

      }

    }

  }

}

Global vs Agent config: Agent config overrides global.

Next Steps: External Tools Integration

Agents là powerful feature để specialize AI assistants. Trong bài tiếp theo, chúng ta sẽ khám phá **External Tools: Kết nối mọi thứ** - cách integrate OpenCode với LSP servers, MCP servers, và external tools.

Bạn sẽ học được:

- LSP Servers setup (TypeScript, Python, Go)

- MCP Servers cho database, API, filesystem

- External tool integration

- Complete development environment

Exercise cho bạn

Level 1: Basic Setup

1. Create code reviewer agent:

opencode agent create

   # Follow prompts to create reviewer

2. Test reviewer:

- Write some code

- Invoke @reviewer to review it

- Verify it focuses on review only

3. Create docs writer:

- Create .opencode/agent/docs-writer.md

- Test with @docs-writer create README

Level 2: Team Setup

1. Create team agents:

- Reviewer

- Security auditor

- Docs writer

2. Test complete workflow:

- Use workflow examples above

- Measure time saved

3. Commit to Git:

- Share .opencode/agent/ with team

- Document usage in team wiki

🎁 Đừng tự build từ đầu: Dùng OpenCodeKit

Bài viết này cover cách tạo agents từ zero theo official docs. Nhưng nếu bạn muốn skip 40+ giờ setup và config, hãy thử OpencodeKit.

OpencodeKit là gì?

OpencodeKit là production-ready configuration package cho OpenCode - bộ configs đã được battle-tested, sẵn sàng dùng ngay.

What’s Included

| Component | Quantity | Description |

| ---------------------- | -------- | --------------------------------------------------------------------------------------- |

| Agents | 10 | Plan, Build, Rush, Code-Auditor, Oracle, Finder, Docs, Librarian, General, Orchestrator |

| Commands | 24 | `/plan`, `/quick-build`, `/pr`, `/fix`, `/commit`, và nhiều hơn |

| Skills | 20 | Brainstorming, TDD, subagent-driven-development, code-review, git-worktrees |

| MCP Services | 6 | Context7, Exa, GitHub Grep, Backlog, Knowledge Graph |

| Anti-Hallucination | ✅ | Task validation, spec enforcement, review gates |

Agents trong OpenCodeKit

OpenCodeKit đi kèm 10 specialized agents đã optimize cho từng task:

| Agent | Purpose | When to use |

| ----------------- | ------------------------------------ | --------------------------------- |

| @plan | Strategic planning, PRD + spec files | Multi-step features, architecture |

| @build | Primary execution agent | Any implementation task |

| @rush | Fast execution, minimal planning | Quick fixes, hotfixes, typos |

| @code-auditor | Security, quality, test coverage | Before merging |

| @oracle | Complex debugging, architecture | Hard bugs, design decisions |

| @finder | Fast codebase search | Navigating unfamiliar code |

| @docs | API docs, config references | Looking up library usage |

| @librarian | Cross-repo GitHub search | Real-world patterns |

| @general | Multi-step exploratory | Research, undefined scope |

| @orchestrator | Multi-agent coordination | Large features (5+ phases) |

Automatic Delegation

Bạn không cần manually call agents - Build agent tự động delegate:

# You ask:

“Add authentication to this API”

# Build agent delegates:

→ @plan (creates auth spec)

→ @docs (looks up better-auth)

→ @build (implements)

→ @code-auditor (security review)

5-minute setup

# Download và extract OpenCodeKit

# Copy configs vào ~/.config/opencode/

# Done! Start coding với fully configured environment

→ Xem chi tiết tại opencodekit.xyz

Comment below: Agent nào bạn tạo đầu tiên? Share experience của bạn! 💪

_Đây là bài 7 trong series “Hành Trình Lập Trình với Opencode”. Đọc các bài trước tại series overview._

Hôm kia tôi review PR của một junior. Code chạy đúng, logic ổn, nhưng...

function getUserData(id) {

  var user = db.query(”SELECT * FROM users WHERE id = “ + id);

  if (user.length > 0) {

    return user[0];

  } else {

    return null;

  }

}

Spacing inconsistent, no semicolons, SQL injection vulnerability, var thay vì let. Tốn 20 phút chỉ để format và fix basic issues.

Đó là khi tôi nhận ra: Code quality không phải là optional, nó là survival skill.

Hôm nay tôi sẽ chỉ bạn cách setup OpenCode để auto-enforce code standards - biến team từ “cha đẻ của spaghetti” thành “sản xuất code chuẩn Michelin”.

Tại sao Code Quality quan trọng hơn bao giờ hết?

Cái giá ẩn sâu của Bad Code

Direct costs:

- 20% time wasted trên formatting issues

- 30% bugs từ inconsistent patterns

- 40% code review time cho basic style issues

Hidden costs:

- New developer onboarding: 2 weeks → 2 months

- Knowledge transfer: “Code này ai viết?” → “Không ai hiểu”

- Technical debt: “Fix sau” → “Never fix”

ROI của Good Code:

- 50% faster code reviews

- 70% fewer style-related bugs

- 90% faster onboarding for new devs

OpenCode Formatters: Auto-magic Code Cleanup

OpenCode tự động format files sau khi write hoặc edit - đảm bảo code generated luôn follow code style của project.

Built-in Formatters Overview

OpenCode có **11 built-in formatters** cho popular languages:

| Formatter | Extensions | Requirements |

| ------------------ | ---------------------------------------------------- | ------------------------------------------ |

| **prettier** | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml | `prettier` dependency trong `package.json` |

| **biome** | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml | `biome.json(c)` config file |

| **ruff** | .py, .pyi | `ruff` command available với config |

| **uv** | .py, .pyi | `uv` command available |

| **gofmt** | .go | `gofmt` command available |

| **zig** | .zig, .zon | `zig` command available |

| **clang-format** | .c, .cpp, .h, .hpp, .ino | `.clang-format` config file |

| **ktlint** | .kt, .kts | `ktlint` command available |

| **rubocop** | .rb, .rake, .gemspec, .ru | `rubocop` command available |

| **standardrb** | .rb, .rake, .gemspec, .ru | `standardrb` command available |

| **htmlbeautifier** | .erb, .html.erb | `htmlbeautifier` command available |

Cách Formatters Hoạt Động

Khi OpenCode write hoặc edit file:

1. Check file extension against all enabled formatters

2. Run formatter command on the file

3. Apply formatting changes tự động

Tất cả diễn ra ở background - code style luôn maintained mà không cần manual steps!

Configure Formatters: Tùy chỉnh theo team

Basic Configuration

Global config trong opencode.json:

{

  “$schema”: “https://opencode.ai/config.json”,

  “formatter”: {}

}

Disable Formatters

Không muốn dùng một formatter cụ thể? Disable nó:

{

  “$schema”: “https://opencode.ai/config.json”,

  “formatter”: {

    “prettier”: {

      “disabled”: true

    }

  }

}

Custom Formatter Configuration

Override built-in formatters hoặc add new ones:

{

  “$schema”: “https://opencode.ai/config.json”,

  “formatter”: {

    “prettier”: {

      “command”: [”npx”, “prettier”, “--write”, “$FILE”],

      “environment”: {

        “NODE_ENV”: “development”

      },

      “extensions”: [”.js”, “.ts”, “.jsx”, “.tsx”]

    },

    “custom-markdown-formatter”: {

      “command”: [”deno”, “fmt”, “$FILE”],

      “extensions”: [”.md”]

    }

  }

}

Key points:

- command: Array of command parts, $FILE placeholder sẽ replaced với file path

- environment: Environment variables khi run formatter

- extensions: File extensions formatter nên handle

- disabled: Set true để disable formatter

Formatter Options cho từng Language

JavaScript/TypeScript với Prettier:

{

  “$schema”: “https://opencode.ai/config.json”,

  “formatter”: {

    “prettier”: {

      “command”: [

        “npx”,

        “prettier”,

        “--write”,

        “--config”,

        “.prettierrc.json”,

        “$FILE”

      ],

      “extensions”: [”.js”, “.jsx”, “.ts”, “.tsx”, “.json”, “.md”]

    }

  }

}

Python với Ruff:

{

  “$schema”: “https://opencode.ai/config.json”,

  “formatter”: {

    “ruff”: {

      “command”: [”ruff”, “format”, “$FILE”],

      “extensions”: [”.py”, “.pyi”]

    }

  }

}

Go với gofmt:

{

  “$schema”: “https://opencode.ai/config.json”,

  “formatter”: {

    “gofmt”: {

      “command”: [”gofmt”, “-w”, “$FILE”],

      “extensions”: [”.go”]

    }

  }

}

AGENTS.md: Custom Instructions cho OpenCode

AGENTS.md là “luật chơi” của project - instructions được include trong LLM context để customize behavior.

Initialize AGENTS.md

Quick start với /init command:

# Trong OpenCode TUI

/init

OpenCode sẽ:

1. Scan project và all contents

2. Understand project structure

3. Generate AGENTS.md với relevant instructions

4. Add to existing file nếu đã có

Pro tip: Commit AGENTS.md vào Git để share với team!

Example AGENTS.md

SST v3 Monorepo Project:

# SST v3 Monorepo Project

This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management.

## Project Structure

- `packages/` - Contains all workspace packages (functions, core, web, etc.)

- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts)

- `sst.config.ts` - Main SST configuration with dynamic imports

## Code Standards

- Use TypeScript with strict mode enabled

- Shared code goes in `packages/core/` with proper exports configuration

- Functions go in `packages/functions/`

- Infrastructure should be split into logical files in `infra/`

## Monorepo Conventions

- Import shared modules using workspace names: `@my-app/core/example`

React Project Example:

# React TypeScript Project

Modern React application with TypeScript, TanStack Router, and Tailwind CSS.

## Project Structure

- `src/components/` - Reusable UI components

- `src/pages/` - Route components

- `src/hooks/` - Custom React hooks

- `src/utils/` - Utility functions

- `src/types/` - TypeScript type definitions

## Code Standards

- Use functional components with TypeScript

- Prefer named exports over default exports

- Use TanStack Router for routing

- Style with Tailwind CSS utility classes

- Write tests with Vitest and Testing Library

## Naming Conventions

- Components: PascalCase (Button.tsx)

- Hooks: camelCase with “use” prefix (useAuth.ts)

- Utils: camelCase (formatDate.ts)

- Types: PascalCase (User.ts)

## Forbidden Patterns

- No `any` types

- No default exports

- No prop spreading without explicit interface

- No inline styles (use Tailwind)

Types of AGENTS.md: Project vs Global

Project-Specific Rules

Location: Project root AGENTS.md

# My Project Rules

Project-specific instructions that apply only when working in this directory.

These are shared with team via Git.

## Project Structure

- `src/` - Source code

- `tests/` - Test files

- `docs/` - Documentation

## Team Conventions

- Use conventional commits

- Run tests before commit

- Keep PRs small (< 400 lines)

Global Rules

Location: ~/.config/opencode/AGENTS.md

# My Personal OpenCode Rules

Personal preferences applied across ALL OpenCode sessions.

Not committed to Git, not shared with team.

## My Coding Style

- Always add type annotations in TypeScript

- Prefer arrow functions over function declarations

- Use descriptive variable names (avoid single letters except i, j in loops)

## My Workflow Preferences

- Run tests after every code change

- Generate documentation comments for all public functions

- Suggest performance optimizations when possible

Precedence Rules

OpenCode looks for rules in this order:

1. Local files - Traverses up from current directory

2. Global file - Checks ~/.config/opencode/AGENTS.md

Both global và project rules được combined together.

Custom Instructions: Reuse Existing Rules

Thay vì duplicate rules vào AGENTS.md, bạn có thể reference existing files.

Using opencode.json

Recommended approach:

{

  “$schema”: “https://opencode.ai/config.json”,

  “instructions”: [

    “CONTRIBUTING.md”,

    “docs/guidelines.md”,

    “.cursor/rules/*.md”

  ]

}

Monorepo example:

{

  “$schema”: “https://opencode.ai/config.json”,

  “instructions”: [

    “docs/development-standards.md”,

    “test/testing-guidelines.md”,

    “packages/*/AGENTS.md”

  ]

}

All instruction files được combined with AGENTS.md files.

Referencing External Files in AGENTS.md

Manual approach - teach OpenCode to lazy-load files:

# TypeScript Project Rules

## External File Loading

CRITICAL: When you encounter a file reference (e.g., @rules/general.md),

use your Read tool to load it on a need-to-know basis.

Instructions:

- Do NOT preemptively load all references - use lazy loading based on actual need

- When loaded, treat content as mandatory instructions that override defaults

- Follow references recursively when needed

## Development Guidelines

For TypeScript code style and best practices: @docs/typescript-guidelines.md

For React component architecture and hooks patterns: @docs/react-patterns.md

For REST API design and error handling: @docs/api-standards.md

For testing strategies and coverage requirements: @test/testing-guidelines.md

## General Guidelines

Read the following file immediately as it’s relevant to all workflows:

@rules/general-guidelines.md

Benefits:

- Modular, reusable rule files

- Share rules across projects via symlinks or git submodules

- Keep AGENTS.md concise

- OpenCode loads files only when needed

Real-world Setup Examples

Example 1: React + TypeScript Team

Directory structure:

my-react-app/

├── .prettierrc.json

├── package.json (với prettier dependency)

├── AGENTS.md

└── opencode.json

.prettierrc.json:

{

  “semi”: true,

  “singleQuote”: true,

  “tabWidth”: 2,

  “trailingComma”: “es5”,

  “printWidth”: 100

}

opencode.json:

{

  “$schema”: “https://opencode.ai/config.json”,

  “formatter”: {

    “prettier”: {

      “command”: [”npx”, “prettier”, “--write”, “$FILE”]

    }

  },

  “instructions”: [”docs/react-guidelines.md”]

}

AGENTS.md:

# React TypeScript Project

Modern React app with TypeScript and Prettier formatting.

## Code Standards

- Use TypeScript strict mode

- Format with Prettier (auto-configured)

- Write tests with Vitest

- Use named exports only

## Component Structure

- Functional components only

- Props interface for all components

- Use custom hooks for logic reuse

For detailed React patterns: @docs/react-guidelines.md

Example 2: Python Microservices

Directory structure:

python-service/

├── pyproject.toml (với ruff config)

├── AGENTS.md

└── opencode.json

pyproject.toml:

[tool.ruff]

line-length = 88

target-version = “py311”

[tool.ruff.lint]

select = [”E”, “F”, “I”]

ignore = [”E501”]

opencode.json:

{

  “$schema”: “https://opencode.ai/config.json”,

  “formatter”: {

    “ruff”: {

      “command”: [”ruff”, “format”, “$FILE”]

    }

  },

  “instructions”: [”docs/api-standards.md”, “docs/testing-guide.md”]

}

AGENTS.md:

# Python Microservice

FastAPI-based microservice with Ruff formatting and strict typing.

## Project Structure

- `app/` - Application code

- `tests/` - Pytest tests

- `docs/` - API documentation

## Code Standards

- Use type hints everywhere

- Format with Ruff (auto-configured)

- Write docstrings for all public functions

- Use Pydantic for data validation

## API Design

Follow REST best practices: @docs/api-standards.md

For testing strategies: @docs/testing-guide.md

Example 3: Monorepo với Multiple Languages

Directory structure:

monorepo/

├── packages/

│   ├── frontend/ (React + TypeScript)

│   ├── backend/ (Node.js + TypeScript)

│   └── shared/ (TypeScript)

├── AGENTS.md

└── opencode.json

opencode.json:

{

  “$schema”: “https://opencode.ai/config.json”,

  “formatter”: {

    “prettier”: {

      “command”: [”npx”, “prettier”, “--write”, “$FILE”],

      “extensions”: [”.js”, “.jsx”, “.ts”, “.tsx”, “.json”, “.md”]

    }

  },

  “instructions”: [”docs/monorepo-guidelines.md”, “packages/*/AGENTS.md”]

}

Root AGENTS.md:

# Monorepo Project

Shared instructions for all packages in this monorepo.

## Monorepo Structure

- `packages/frontend/` - React application

- `packages/backend/` - Node.js API

- `packages/shared/` - Shared utilities and types

## Shared Standards

- Use TypeScript strict mode across all packages

- Format with Prettier (unified config)

- Share types via `@monorepo/shared` package

- Use workspace protocol for internal dependencies

## Package-Specific Rules

Each package has its own AGENTS.md loaded via opencode.json instructions.

For monorepo best practices: @docs/monorepo-guidelines.md

packages/frontend/AGENTS.md:

# Frontend Package

React + TypeScript frontend application.

## Frontend-Specific Standards

- Use TanStack Router for routing

- Style with Tailwind CSS

- Test with Vitest + Testing Library

- Import shared types from `@monorepo/shared`

Best Practices cho Code Quality Setup

1. Start Simple, Scale Gradually

Week 1-2: Basic Formatting

- Setup Prettier/Ruff với default config

- Add basic AGENTS.md với project structure

- No enforcement, just auto-format

Week 3-4: Add Project Standards

- Create comprehensive AGENTS.md

- Add custom instructions files

- Document naming conventions

Week 5-6: Team Alignment

- Share setup với team

- Collect feedback và adjust

- Add team-specific rules

Week 7+: Enforcement

- Add pre-commit hooks (nếu cần)

- Monitor code quality metrics

- Continuous improvement

2. Keep AGENTS.md Focused

Do:

- Explain project structure clearly

- Document team conventions

- Reference external guidelines

- Include forbidden patterns

Don’t:

- Duplicate formatter config (đã có trong .prettierrc)

- Include personal preferences (dùng global AGENTS.md)

- Write essays (keep it concise)

- Hardcode file paths (use references)

3. Leverage opencode.json for Reusability

Good pattern:

{

  “$schema”: “https://opencode.ai/config.json”,

  “instructions”: [”docs/shared-standards.md”, “CONTRIBUTING.md”]

}

Better pattern:

{

  “$schema”: “https://opencode.ai/config.json”,

  “instructions”: [”docs/standards/*.md”, “packages/*/AGENTS.md”]

}

4. Test Your Setup

Checklist:

- [ ] Run `/init` in OpenCode TUI

- [ ] Edit a file và verify auto-formatting works

- [ ] Check AGENTS.md instructions are followed

- [ ] Test external file references load correctly

- [ ] Verify team members can replicate setup

Measuring Code Quality Improvement

Before OpenCode Setup

Metrics:

- Code review time: 45 minutes average

- Formatting discussions: 30% of review comments

- Style-related bugs: 15 per sprint

- Onboarding time: 3 weeks

- Code consistency score: 6/10

After OpenCode Setup

Metrics:

- Code review time: 15 minutes average (-67%)

- Formatting discussions: 2% of review comments (-93%)

- Style-related bugs: 2 per sprint (-87%)

- Onboarding time: 1 week (-67%)

- Code consistency score: 9/10 (+50%)

Track Your Progress

Simple tracking script:

#!/bin/bash

# quality-metrics.sh

echo “📊 Code Quality Metrics”

echo “=======================”

echo “📝 Files formatted last week:”

git log --since=”1 week ago” --name-only --pretty=format: | sort -u | wc -l

echo “🔍 Prettier changes in last week:”

git log --since=”1 week ago” --grep=”prettier” --oneline | wc -l

echo “📏 Average PR size (lines):”

gh pr list --state merged --limit 10 --json additions,deletions \

  | jq ‘[.[] | .additions + .deletions] | add / length’

Troubleshooting Common Issues

Issue 1: Formatter Not Running

Check 1: Formatter requirements met?

# For Prettier

cat package.json | grep prettier

# For Ruff

ruff --version

# For gofmt

gofmt -help

Check 2: File extension supported?

{

  “formatter”: {

    “prettier”: {

      “extensions”: [”.js”, “.ts”, “.jsx”, “.tsx”]

    }

  }

}

Check 3: Formatter not disabled?

{

  “formatter”: {

    “prettier”: {

      “disabled”: false // Make sure this is false

    }

  }

}

Issue 2: AGENTS.md Not Loaded

Debug với OpenCode TUI:

# Check nếu file được recognized

opencode --verbose

# Verify file location

ls -la AGENTS.md

ls -la ~/.config/opencode/AGENTS.md

Common mistakes:

- File trong wrong directory

- Typo trong filename (phải là AGENTS.md, không phải agents.md)

- Git không track file

Issue 3: Formatting Conflicts

Prettier vs ESLint conflicts:

Disable conflicting ESLint rules:

{

  “extends”: [

    “eslint:recommended”,

    “prettier” // Must be LAST to override

  ]

}

Install eslint-config-prettier:

npm install -D eslint-config-prettier

Team Onboarding Checklist

For New Team Members

Setup steps:

1. Clone repo:

   git clone <repo-url>

   cd <repo>

2. Install dependencies:

   npm install  # or yarn/pnpm

3. Check OpenCode config:

   cat opencode.json

   cat AGENTS.md

4. Run OpenCode:

   opencode

5. Test formatting:

- Edit một file

- Save và verify auto-format

- Run /init để verify AGENTS.md loaded

6. Read team guidelines:

- Check AGENTS.md for project structure

- Review files referenced trong `instructions`

- Ask questions trong team chat

For Team Leads

Maintenance checklist:

- [ ] Review AGENTS.md quarterly

- [ ] Update formatter configs when upgrading dependencies

- [ ] Collect feedback on pain points

- [ ] Document new patterns discovered

- [ ] Keep instructions files up-to-date

- [ ] Share success stories với team

Next Steps: Agents & Rules

Code quality là foundation cho consistent codebase. Trong bài tiếp theo, chúng ta sẽ khám phá Agents & Rules: AI assistant chuyên nghiệp - cách tạo specialized AI agents cho từng loại công việc.

Bạn sẽ học được:

- Specialized agents (reviewer, planner, build)

- Custom agent configuration cho team workflows

- Agent best practices và pitfalls to avoid

- Real-world agent workflows

Subscribe để không bỏ lỡ! 🚀

Exercise cho bạn

Level 1: Basic Setup

1. Create AGENTS.md cho project của bạn:

- Run /init trong OpenCode

- Review generated content

- Add project-specific conventions

- Commit to Git

2. Configure formatters:

- Check which formatter applies to your project

- Add opencode.json nếu cần custom config

- Test formatting on sample file

3. Verify setup:

- Edit một file và check auto-format

- Ask OpenCode về project structure

- Confirm AGENTS.md instructions followed

Level 2: Team Integration

1. Create instruction files:

- docs/coding-standards.md

- docs/testing-guide.md

- Reference them trong opencode.json

2. Setup global rules:

- Create ~/.config/opencode/AGENTS.md

- Add personal preferences

- Test project vs global precedence

3. Document for team:

- Write onboarding guide

- Create setup script

- Share trong team wiki

Level 3: Advanced

1. Measure improvements:

- Track formatting time saved

- Monitor code review efficiency

- Survey team satisfaction

2. Optimize setup:

- Fine-tune formatter configs

- Reorganize instruction files

- Create language-specific guides

3. Share learnings:

- Write internal blog post

- Present trong team meeting

- Contribute improvements back to team

Comment below: Setup experience và results! Cùng nhau build better practices! 💪

_Đây là bài 6 trong series “Hành Trình Lập Trình với Opencode”. Đọc các bài trước tại [series overview]._

80% công việc lặp đi lặp lại → 5 phút setup

Tôi đã từng là “con robot” của terminal

Mỗi sáng đến công ty, tôi lại lặp đi lặp lại một chuỗi commands:

git pull origin main

npm install

npm run test

npm run build

docker-compose up -d

Đôi khi còn phải check lint, format code, deploy... Mất 15 phút mỗi ngày chỉ cho việc “setup”. Cho đến khi tôi khám phá ra OpenCode Commands - game changer thực sự.

Hôm nay tôi sẽ chỉ bạn cách biến 80% công việc lặp lại thành vài cái gõ phím.

Commands là gì trong OpenCode?

OpenCode Commands cho phép bạn tạo ra các “lối tắt thông minh” - những câu lệnh tùy chỉnh mà khi bạn gõ /tên-command, OpenCode sẽ tự động thực hiện một chuỗi hành động phức tạp.

Ví dụ thực tế:

• /test → Chạy full test suite, analyze failures, suggest fixes

• /review → Review code changes theo team standards

• /deploy → Build, test, deploy một lần

Không chỉ là simple aliases, Commands có thể:

• Nhận arguments (`$1`, `$2`, `$ARGUMENTS`)

• Chạy shell commands và inject output

• Include files tự động

• Sử dụng agents và models khác nhau

Tạo Command đầu tiên: Magic Test Runner

Cách 1: Dùng Markdown file (recommended)

Tạo file `.opencode/command/test.md`:

---

description: Run tests with coverage and analyze failures

agent: build

model: anthropic/claude-3-5-sonnet-20241022

---

Run the full test suite with coverage report and show any failures.

Focus on the failing tests and suggest fixes.

Current test results:

!`npm test -- --coverage`

Recent changes that might affect tests:

!`git log --oneline -5`

Cách 2: Dùng JSON config

Trong opencode.json:

{

  “$schema”: “https://opencode.ai/config.json”,

  “command”: {

    “test”: {

      “template”: “Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.\n\nCurrent test results:\n!`npm test -- --coverage`”,

      “description”: “Run tests with coverage”,

      “agent”: “build”,

      “model”: “anthropic/claude-3-5-sonnet-20241022”

    }

  }

}

Sử dụng: Gõ /test trong TUI và xem magic happens!

Command Options: Full Control

OpenCode Commands cung cấp nhiều options để bạn kiểm soát chính xác cách command thực thi:

Template Option

template là phần bắt buộc - định nghĩa prompt sẽ gửi đến LLM:

{

  “command”: {

    “test”: {

      “template”: “Run tests and analyze failures:\n!`npm test`\n\nFocus on failing tests and suggest fixes.”

    }

  }

}

Description Option

description hiển thị trong TUI khi bạn gõ /:

{

  “command”: {

    “test”: {

      “description”: “Run tests with intelligent failure analysis”

    }

  }

}

Agent Option

Chỉ định agent nào sẽ thực thi command:

{

  “command”: {

    “review”: {

      “agent”: “reviewer”,

      “template”: “Review code changes for quality and security”

    },

    “plan”: {

      “agent”: “plan”,

      “template”: “Create implementation plan for new feature”

    }

  }

}

Model Option

Override model mặc định cho command cụ thể:

{

  “command”: {

    “analyze”: {

      “model”: “anthropic/claude-3-5-sonnet-20241022”,

      “template”: “Deep analyze code for performance issues”

    }

  }

}

Subtask Option

Force command chạy như subtask (không pollute primary context):

{

  “command”: {

    “quick-check”: {

      “subtask”: true,

      “template”: “Quick syntax check and basic validation”

    }

  }

}

Khi nào dùng subtask: true:

• Commands chạy thường xuyên (linting, formatting)

• Tasks không cần context chính

• Muốn giữ primary context clean

Complete Example với All Options

{

  “command”: {

    “comprehensive-review”: {

      “description”: “Full code review with security analysis”,

      “template”: “Review these changes comprehensively:\n\n!`git diff main...HEAD`\n\nCheck for:\n- Security vulnerabilities\n- Performance issues\n- Code quality\n- Test coverage\n\nProvide actionable feedback.”,

      “agent”: “reviewer”,

      “model”: “anthropic/claude-3-5-sonnet-20241022”,

      “subtask”: false

    }

  }

}

Advanced Command Techniques

1. Arguments Handling

Tạo command linh hoạt với parameters:

.opencode/command/component.md:

---

description: Create new React component with TypeScript

---

Create a new React component named $ARGUMENTS with TypeScript support.

Include proper typing and basic structure.

Place it in: src/components/$ARGUMENTS.tsx

Use this template:

```tsx

import React from “react”;

interface $ARGUMENTSProps {

  // Define props here

}

export const $ARGUMENTS: React.FC<$ARGUMENTSProps> = () => {

  return (

    <div>

      <h1>$ARGUMENTS Component</h1>

    </div>

  );

};

```

Usage: /component Button → Tạo Button component hoàn chỉnh

2. Positional Arguments

Truyền đối số cho các lệnh bằng cách sử dụng trình giữ chỗ $ARGUMENTS.

.opencode/command/create-file.md:

---

description: Create file with content in specific directory

---

Create a file named $1 in the directory $2 with the following content:

$3

Make sure the directory exists and use proper file extension.

Usage: /create-file config.json src “{ \”key\”: \”value\” }”

3. Shell Output Integration

Sử dụng !command để đưa đầu ra lệnh bash vào prompt của bạn.

.opencode/command/review-changes.md:

---

description: Review recent git changes

---

Review these recent changes and suggest improvements:

Recent commits:

!`git log --oneline -10`

Current changes:

!`git diff --name-only`

Diff details:

!`git diff`

Focus on:

- Code quality issues

- Potential bugs

- Performance concerns

- Security vulnerabilities

4. File References

.opencode/command/analyze-component.md:

---

description: Deep analyze component for performance issues

---

Analyze the component in @src/components/Button.tsx for:

- Performance bottlenecks

- Re-render optimization opportunities

- Bundle size impact

- Accessibility issues

Suggest specific improvements with code examples.

5. Override Built-in Commands

OpenCode cho phép bạn override built-in commands như /init, /undo, /redo, /share, /help.

Ví dụ: Custom /init command

.opencode/command/init.md:

---

description: Custom project initialization with team setup

---

Initialize project with team-specific settings:

1. Analyze project structure

2. Create team-standard AGENTS.md

3. Setup recommended commands

4. Configure project-specific tools

5. Generate onboarding checklist

Team standards:

- Use TypeScript strict mode

- ESLint + Prettier configuration

- Jest for testing

- Conventional commits

!`npm init -y` (if package.json doesn’t exist)

!`git init` (if not a git repo)

⚠️ Cẩn thận khi override built-in commands:

• Chỉ override khi bạn thực sự cần custom behavior

• Giữ lại core functionality của original command

• Document changes cho team

Ví dụ: Enhanced /help command

.opencode/command/help.md:

---

description: Custom help with team-specific commands

---

# OpenCode Help - Team Edition

## Built-in Commands

- `/init` - Initialize project (team version)

- `/undo` - Undo last change

- `/redo` - Redo undone change

- `/share` - Share conversation

## Team Custom Commands

- `/test` - Run tests with coverage analysis

- `/review` - Code review with team standards

- `/deploy` - Safe deployment workflow

- `/cleanup` - Project cleanup and optimization

## Getting Started

1. Run `/init` for project setup

2. Try `/test` to verify everything works

3. Use `/review` before committing changes

Need help? Ask in team Slack #opencode channel!

10 Commands hữu ích nhất cho daily work

1. Smart Test Runner

---

description: Run tests with intelligent failure analysis

---

!`npm test`

If any tests failed:

1. Analyze failure patterns

2. Identify root causes

3. Suggest specific fixes

4. Check if similar issues exist elsewhere

2. Code Review Assistant

---

description: Review PR changes like senior dev

---

Review these changes:

!`git diff main...HEAD`

Check for:

- Code quality and consistency

- Performance implications

- Security concerns

- Test coverage

- Documentation updates

Provide actionable feedback.

3. Dependency Updater

---

description: Check and update dependencies safely

---

Check for outdated packages:

!`npm outdated`

For each outdated dependency:

1. Check breaking changes

2. Update one by one

3. Run tests after each update

4. Rollback if tests fail

4. Performance Profiler

---

description: Analyze bundle size and performance

---

Current bundle analysis:

!`npm run analyze`

Identify:

- Largest dependencies

- Unused code

- Optimization opportunities

- Lazy loading candidates

5. Security Scanner

---

description: Scan for security vulnerabilities

---

Run security audit:

!`npm audit`

For each vulnerability:

1. Assess severity

2. Check exploitability

3. Suggest remediation

4. Provide patch examples

6. Database Migration Helper

---

description: Safe database migration workflow

---

Current migration status:

!`npm run migrate:status`

Pending migrations:

!`npm run migrate:pending`

Plan:

1. Backup current database

2. Review migration files

3. Run migrations in staging

4. Execute in production

5. Verify data integrity

7. API Documentation Generator

---

description: Generate API docs from code

---

Analyze API routes:

!`find . -name “*.ts” -path “*/api/*” -exec grep -l “export.*\(Handler\|Route\)” {} \;`

Generate documentation for:

- Endpoints and methods

- Request/response schemas

- Authentication requirements

- Rate limiting info

8. Environment Setup Validator

---

description: Validate development environment

---

Check environment setup:

!`node --version && npm --version && git --version`

Verify:

- Required tools are installed

- Environment variables are set

- Dependencies are properly installed

- Configuration files are valid

9. Cleanup Assistant

---

description: Clean up project and optimize storage

---

Analyze project for cleanup:

!`find . -name “node_modules” -type d`

!`find . -name “*.log” -type f`

!`find . -name “.DS_Store” -type f`

Suggest:

- Unused dependencies to remove

- Cache directories to clean

- Temporary files to delete

- Disk space recovery opportunities

10. Release Preparation

---

description: Prepare for production release

---

Release checklist:

!`npm run test`

!`npm run build`

!`npm run lint`

Version info:

!`git describe --tags`

!`git log --oneline $(git describe --tags --abbrev=0)..HEAD`

Verify:

- All tests pass

- Build succeeds

- No linting errors

- Changelog is updated

- Version is bumped

CLI Automation với OpenCode

OpenCode CLI cho phép bạn script và automate workflows:

Basic CLI Usage

# Quick question without TUI

opencode run “Explain how closures work in JavaScript”

# Use specific model

opencode run -m anthropic/claude-3-5-sonnet-20241022 “Review this code”

# Use specific agent

opencode run --agent reviewer “Check for security issues”

# Continue previous session

opencode run -c “Continue with the previous analysis”

Scripting Examples

• Automated Code Review Script:

#!/bin/bash

# review-pr.sh

echo “🔍 Analyzing PR changes...”

opencode run “

Review these changes for code quality:

$(git diff main...HEAD)

Focus on:

- Performance implications

- Security vulnerabilities

- Code consistency

- Test coverage

Provide specific, actionable feedback.

“

• Daily Health Check Script:

#!/bin/bash

# daily-check.sh

echo “🏥 Running daily health check...”

# Check dependencies

opencode run “

Check for security vulnerabilities:

$(npm audit)

Suggest immediate actions for any high-severity issues.

“

# Run tests

opencode run --agent build “

Run full test suite and analyze any failures:

$(npm test)

If tests fail, identify root causes and suggest fixes.

“

Batch Operations

• Multiple File Processing:

# Process all TypeScript files

for file in $(find src -name “*.ts”); do

    echo “Processing $file...”

    opencode run “Analyze $file for performance optimizations”

done

• Component Documentation:

# Generate docs for all components

for component in src/components/*; do

    name=$(basename “$component”)

    opencode run “

Generate documentation for $name component:

$(cat “$component”)

Include props, usage examples, and best practices.

“ > “docs/components/$name.md”

done

Best Practices cho Commands

1. Quy ước đặt tên

• Sử dụng descriptive names: test-with-coverage thay vì twc

• Các lệnh liên quan đến nhóm: test-*, deploy-*, review-*

• Sử dụng kebab-case cho các lệnh nhiều từ

2. Xử lý lỗi

---

description: Safe deployment with rollback

---

Try deployment:

!`npm run deploy`

If deployment fails:

1. Check error logs: !`kubectl logs deployment/app --tail=50`

2. Rollback to previous version: !`kubectl rollout undo deployment/app`

3. Verify rollback success: !`kubectl get pods`

4. Report specific failure reasons

3. Tối ưu hóa hiệu suất

• Sử dụng các agent cụ thể cho các task phù hợp

• Giới hạn đầu ra shell với thông tin liên quan

• Cache các hoạt động đắt tiền khi có thể

4. Cân nhắc về bảo mật

• Không bao giờ hardecode dữ liệu nhạy cảm trong lệnh

• Sử dụng biến môi trường cho giá trị bí mật

• Xác thực đầu vào trong các lệnh tùy chỉnh

Team Workflow với Commands

Kho lưu trữ lệnh chia sẻ

Tạo .opencode/command/ directory trong project root và commit vào Git:

.opencode/

├── command/

│   ├── test.md

│   ├── review.md

│   ├── deploy.md

│   └── cleanup.md

└── config.json

Giới thiệu thành viên nhóm mới

1. Setup Commands:

# Clone project

git clone <repo>

cd <repo>

# OpenCode sẽ tự động detect commands

opencode

/init

2. Available Commands:

Gõ / để see all available commands với descriptions

3. Team Standards:

Commands enforce consistent workflows across team

Mẫu lệnh cho các loại dự án khác nhau

• React Project Commands:

# component.md

Create React component with TypeScript and tests

# story.md

Generate Storybook story for component

# test.md

Run Jest tests with coverage

• Node.js API Commands:

# endpoint.md

Create new API endpoint with validation

# migrate.md

Run database migrations safely

# seed.md

Seed database with test data

• Python Project Commands:

# test.md

Run pytest with coverage

# lint.md

Run black, flake8, mypy

# requirements.md

Update requirements.txt safely

Khắc phục sự cố thường gặp

Lệnh không tìm thấy

# Check command files exist

ls -la .opencode/command/

# Verify syntax

opencode run “Check my command syntax”

Lệnh Shell không thành công

---

description: Debug shell command

---

Debug this command:

!`failing-command`

Check:

1. Command exists in PATH

2. Required permissions

3. Working directory

4. Environment variables

Đối số không hoạt động

---

description: Test argument handling

---

Testing arguments:

- All arguments: $ARGUMENTS

- First argument: $1

- Second argument: $2

Debug argument parsing issues.

Measuring ROI của Commands

Before Commands:

• Manual test running: 5 minutes × 10 times/day = 50 minutes

• Code review setup: 10 minutes × 5 PRs/day = 50 minutes

• Deployment process: 15 minutes × 3 deployments/day = 45 minutes

Total: 145 minutes/day

After Commands:

• /test: 30 seconds × 10 = 5 minutes

• /review: 2 minutes × 5 PRs = 10 minutes

• /deploy: 3 minutes × 3 = 9 minutes

Total: 24 minutes/day

Next Steps: Code Quality & Team Standards

Commands là foundation cho automation. Trong bài tiếp theo, chúng ta sẽ khám phá Code Quality: Formatters & Rules chuẩn team - cách đảm bảo code consistency across entire team.

Bạn sẽ học được:

• Auto-formatting với Prettier, ESLint

• Custom formatters cho specific needs

• Team rules và guidelines

• Git hooks integration

Exercise cho bạn

1. Tạo 3 commands cho project của bạn:

• Một command cho testing

• Một command cho code review

• Một command cho deployment

2. Share commands với team:

• Commit .opencode/command/ vào Git

• Document usage trong team wiki

3. Measure time saved:

• Track time trước và sau khi dùng commands

• Share results với team

Comment below: Commands bạn tạo và kết quả time saved! Cùng nhau học hỏi nhé! 💪

_Đây là bài 5 trong series “Hành Trình Lập Trình với Opencode”. Đọc các bài trước tại [series overview]._

Tôi đã chứng kiến hàng trăm developer Việt Nam dùng OpenCode với default terminal, và họ đang bỏ lỡ 90% sức mạnh.

Có developer hỏi tôi: “Sao anh dùng OpenCode nhanh thế? Em cũng dùng mà thấy chậm quá.”

Tôi hỏi lại: “Bạn đang dùng terminal gì?”

“Terminal mặc định của Mac ạ.”

**Vấn đề ở đây:** Không phải OpenCode chậm, mà terminal bạn đang dùng chưa được optimize.

Hôm nay, tôi sẽ dạy bạn biến terminal thường thành workstation chuyên nghiệp chỉ trong 15 phút. Không cần mua IDE đắt tiền, không cần học 50 shortcut phức tạp.

1. Hiểu đúng: TUI của OpenCode là gì?

A. TUI vs CLI - Khác biệt cơ bản

• CLI (Command Line Interface):

opencode run “What models are available”

• TUI (Terminal User Interface):

opencode  # Mở giao diện tương tác

Tại sao TUI quan trọng?

• Giao diện visual giúp bạn thấy rõ conversation flow

• Multi-pane layout cho debugging hiệu quả

• Real-time interaction với AI

• Context switching nhanh giữa các tasks

B. Built-in commands trong TUI (Theo docs chính thức)

OpenCode cung cấp hơn 20 commands trong TUI:

• Navigation commands:

  • /models - Xem danh sách models (Ctrl+X M)

  • /themes - Chọn theme (Ctrl+X T)

  • /sessions - Switch giữa sessions (Ctrl+X L)

• Session management:

  • /new - Bắt đầu session mới (Ctrl+X N)

  • /undo - Hoàn tác thay đổi (Ctrl+X U)

  • /redo - Làm lại (Ctrl+X R)

  • /export - Export conversation (Ctrl+X X)

• Development tools:

  • /editor - Mở external editor (Ctrl+X E)

  • /init - Update AGENTS.md (Ctrl+X I)

  • /details - Toggle tool details (Ctrl+X D)

2. Setup terminal chuẩn senior dev

A. Terminal requirements (Theo docs)

Truecolor support bắt buộc:

# Kiểm tra terminal bạn

echo $COLORTERM

# Kết quả: truecolor hoặc 24bit

Nếu không có truecolor:

# Thêm vào ~/.zshrc hoặc ~/.bashrc

export COLORTERM=truecolor

Recommended terminals:

• Mac: iTerm2, Alacritty, WezTerm

• Linux: Alacritty, Kitty, GNOME Terminal

• Windows: Windows Terminal, WezTerm

B. Tối ưu scroll speed (Theo docs)

OpenCode cho phép điều chỉnh scroll speed trong config:

{

  “$schema”: “https://opencode.ai/config.json”,

  “tui”: {

    “scroll_speed”: 3

  }

}

Giải thích:

• 1: Chậm, phù hợp debug chi tiết

• 2: Default, balanced

• 3: Nhanh, phù hợp code review

• 4: Rất nhanh, cho power users

3. Themes & Visual Customization

A. Built-in themes (Theo docs)

OpenCode có 15+ themes built-in:

Popular themes:

• opencode - Default theme của OpenCode

• tokyonight - Dark blue, phổ biến với dev Việt

• everforest - Green earthy tones

• catppuccin - Pastel colors, dễ nhìn

• gruvbox - Retro groove colors

• nord - Arctic blue tones

Special themes:

• system - Tự động adapt theo terminal

• matrix - Hacker style green-on-black

B. Chọn theme nhanh

# Trong OpenCode TUI

/themes

# Hoặc trong config

{

  “theme”: “tokyonight”

}

C. Custom themes (Advanced)

Tạo theme riêng trong ~/.config/opencode/themes/my-theme.json:

{

  “$schema”: “https://opencode.ai/theme.json”,

  “theme”: {

    “primary”: { “dark”: “#00ff00”, “light”: “#008800” },

    “background”: { “dark”: “#000000”, “light”: “#ffffff” },

    “text”: { “dark”: “#ffffff”, “light”: “#000000” }

  }

}

4. Keybinds Optimization

A. Leader key system (Theo docs)

OpenCode dùng leader key để tránh conflict:

• Default: `Ctrl+X`

• Sau đó nhấn phím chức năng

Ví dụ workflow:

1. Ctrl+X (leader)

2. M (models)

3. Chọn model từ list

B. Essential keybinds cho daily work

• Navigation nhanh:

  • Ctrl+X M - Models list

  • Ctrl+X T - Themes

  • Ctrl+X L - Sessions

• Session management:

  • Ctrl+X N - New session

  • Ctrl+X U - Undo changes

  • Ctrl+X R - Redo

  • Ctrl+X X - Export

• Development tools:

  • Ctrl+X E - External editor

  • Ctrl+X I - Init project

  • Ctrl+X D - Toggle details

C. Custom keybinds trong config

{

  “keybinds”: {

    “leader”: “ctrl+x”,

    “model_list”: “ctrl+x m”,

    “theme_list”: “ctrl+x t”,

    “session_new”: “ctrl+x n”

  }

}

5. Focus Mode cho Deep Work

Kích hoạt focus mode với theme phù hợp:

{

  “theme”: “matrix”, // Hacker theme

  “tui”: {

    “scroll_speed”: 1 // Slow, deliberate

  }

}

Workflow focus mode:

1. Chọn theme tối (matrix, tokyonight)

2. Giảm scroll speed xuống 1

3. Tắt notifications ngoài

4. Full screen terminal

5. Single task focus

6. Performance Optimization

A. Terminal performance tuning

• iTerm2:

# Preferences > Profiles > Terminal

- Unlimited scrollback

- Enable mouse reporting

- Use built-in powerline glyphs

• Alacritty :

# ~/.config/alacritty/alacritty.yml

scrolling:

  history: 100000

  multiplier: 3

font:

  size: 14.0

  normal:

    family: “Fira Code”

B. Memory và CPU optimization

• Large projects:

  • Dùng `/compact` để summarize sessions

  • Limit scrollback history

  • Disable animations nếu cần

• Multi-session workflow:

  • Switch sessions thay vì duplicate

  • Export old sessions để archive

  • Use `/new` cho clean state

7. Real-world Workflows

A. Daily development workflow

Morning setup (2 phút):

1. Mở terminal

2. opencode → vào project

3. /models → chọn model phù hợp

4. /themes → chọn theme theo mood

Coding session:

1. Ctrl+X E → mở external editor

2. Code với AI assistance

3. Ctrl+X U → undo nếu cần

4. Ctrl+X X → export khi xong

B. Code review workflow

Review mode:

1. /themes → chọn theme sáng (dễ đọc)

2. /details → bật tool details

3. Review code với AI

4. Export recommendations

C. Debugging workflow

Debug mode:

1. Focus mode với theme tối

2. Multi-pane layout

3. Step-through với AI

4. Document findings

8. Common TUI Mistakes

1. Terminal không hỗ trợ truecolor

Sai: Dùng default Terminal.app trên Mac cũ

2. Scroll speed quá nhanh

Sai: Để default speed cho mọi task

3. Không dùng keybinds

Sai: Chỉ dùng mouse và commands

4. Theme không phù hợp

Sai: Dùng theme mặc định cho mọi hoàn cảnh

9. Kết luận: Bạn đã có workstation chuyên nghiệp

Sau bài này, bạn có:

✅ Terminal optimized - Truecolor, performance, layout

✅ TUI mastery - Commands, keybinds, themes

✅ Workflow chuẩn - Daily, review, debug modes

✅ Focus mode - Deep work capability

✅ Productivity tăng - 3x faster interaction

Challenge: Setup TUI theo hướng dẫn, sau đó dùng 1 tuần. Note lại:

• Theme nào bạn thích nhất?

• Keybind nào tiết kiệm thời gian nhất?

• Focus mode có giúp bạn tập trung không?

Next step: Trong bài 5, tôi sẽ dạy bạn Commands & Automation - tự động hoá mọi thứ với custom commands. Bạn sẽ thấy cách biến 80% công việc lặp đi lặp lại thành 5 phút setup!

Homework: Thử 3 themes khác nhau trong 3 ngày, sau đó chọn theme phù hợp nhất. Test focus mode với scroll_speed = 1. Share screenshots để cùng discuss!

Có một sự thật đau lòng:

Tôi đã chứng kiến cảnh tượng này hàng trăm lần:

• Developer A: Mỗi lần đổi project, mất 30 phút setup lại từ đầu

• Developer B: Team 5 người, 5 cách config khác nhau, không ai hiểu ai

• Developer C: AI xoá nhầm file quan trọng vì permission không chặt

• Developer D: Mỗi tháng tốn thêm 500k vì dùng model đắt cho task nhẹ

Tất cả đều có chung một nguyên nhân: Không hiểu cách config đúng từ đầu.

Hôm nay, tôi sẽ dạy bạn config OpenCode như senior dev thực thụ. Không theory rườm rà, chỉ có 15 phút setup → dùng 1 năm không phải sửa.

1. Hiểu đúng: OpenCode config system hoạt động thế nào?

A. Cấu trúc cơ bản (Theo docs chính thức)

OpenCode hỗ trợ JSON và JSONC (JSON with Comments). Luôn bắt đầu với schema:

{

  “$schema”: “https://opencode.ai/config.json”

}

Tại sao cần schema?

• Editor tự động validate và gợi ý

• Tránh lỗi syntax phổ biến

• Luôn cập nhật với features mới nhất

B. Vị trí config files (Priority order chính xác)

Theo docs chính thức, OpenCode tìm config theo thứ tự:

1. Custom path (OPENCODE_CONFIG env var) - Cao nhất

2. Project config (./opencode.json) - Override global

3. Global config (~/.config/opencode/opencode.json) - Foundation

4. Custom directory (OPENCODE_CONFIG_DIR) - Extension

Thực tế: 90% thời gian bạn chỉ cần quan tâm đến Global + Project config.

2. Các khóa cấu hình thiết yếu (Copy-paste được ngay)

A. Model & Provider Configuration (Theo docs 2025)

Option 1: OpenCode Zen (Recommend cho người mới)

{

  “model”: “opencode/qwen3-coder-32b”,

  “provider”: {

    “opencode”: {

      “models”: {

        “qwen3-coder-32b”: {

          “name”: “Qwen 3 Coder (Recommended)”

        }

      }

    }

  }

}

```

Option 2: Claude Pro (Tốt nhất cho dev)

{

  “model”: “anthropic/claude-3-5-sonnet-20241022”,

  “small_model”: “anthropic/claude-3-5-haiku-20241022”,

  “provider”: {

    “anthropic”: {

      “models”: {

        “claude-3-5-sonnet-20241022”: {

          “name”: “Claude 3.5 Sonnet”

        },

        “claude-3-5-haiku-20241022”: {

          “name”: “Claude 3.5 Haiku (Fast & Cheap)”

        }

      }

    }

  }

}

Giải thích từng thành phần:

• model: AI chính cho tasks nặng (code generation, analysis)

• small_model: AI phụ cho tasks nhẹ (title generation, quick questions) - Tiết kiệm 70% chi phí

• provider: Cấu hình authentication và models

B. Security & Permission Settings (Không được bỏ qua)

• Permission levels theo docs: ”ask”, ”auto”, ”disabled”

• Config an toàn cho team:*

{

  “permission”: {

    “write”: “ask”,

    “edit”: “ask”,

    “bash”: “ask”,

    “delete”: “ask”

  }

}

• Disable tools nguy hiểm:

{

  “tools”: {

    “write”: true,

    “edit”: true,

    “bash”: false,

    “delete”: false

  }

}

C. TUI & User Experience Optimization

• Scroll speed (theo docs):

{

  “tui”: {

    “scroll_speed”: 2

  }

}

• Theme selection:

{

  “theme”: “opencode” // Options: “opencode”, “system”, “aura”, “ayu”, “catppuccin”, "tokyonight"

}

D. Advanced Features (Optional nhưng powerful)

• Custom agents (specialized AI assistants):

{

  “agent”: {

    “code-reviewer”: {

      “description”: “Reviews code for security and best practices”,

      “model”: “anthropic/claude-3-5-sonnet-20241022”,

      “prompt”: “You are a senior code reviewer. Focus on security vulnerabilities, performance issues, and maintainability. Be constructive.”,

      “tools”: {

        “write”: false,

        “edit”: false

      }

    }

  }

}

• Command templates (tự động hoá tasks):

{

  “command”: {

    “component”: {

      “template”: “Create React component named $ARGUMENTS with TypeScript, proper props typing, and basic tests”,

      “description”: “Create React component”

    }

  }

}

3. Environment Variables & Dynamic Config (Pro tip)

A. Env Variable Substitution

• Giữ API keys an toàn:

{

  “provider”: {

    “anthropic”: {

      “options”: {

        “apiKey”: “{env:ANTHROPIC_API_KEY}”

      }

    }

  }

}

• Setup:

# Thêm vào ~/.bashrc hoặc ~/.zshrc

export ANTHROPIC_API_KEY=”sk-ant-your-key-here”

B. File Include System

• Include instructions từ file:

{

  “instructions”: [

    “{file:CONTRIBUTING.md}”,

    “{file:docs/team-guidelines.md}”,

    “{file:~/.config/opencode/global-instructions.md}”

  ]

}

Best practice: Giữ secrets trong file riêng:

{

  “provider”: {

    “anthropic”: {

      “options”: {

        “apiKey”: “{file:~/.secrets/anthropic-key.txt}”

      }

    }

  }

}

4. Team & Collaboration Config (Enterprise-ready)

A. Sharing Configuration

• Manual sharing (recommended cho team):

{

  “share”: “manual” // Default: chỉ share khi dùng /share command

}

Options: ”manual” | ”auto” | ”disabled”

B. Disabled Providers Management

• Chặn providers không cần thiết:

{

  “disabled_providers”: [”openai”, “gemini”]

}

Lưu ý: disabled_providers chặn hoàn toàn, kể cả khi có credentials.

5. Hands-on Workshop: Tạo config cho project của bạn

Bước 1: Global foundation config

Tạo file `~/.config/opencode/opencode.json`:

{

  “$schema”: “https://opencode.ai/config.json”,

  “theme”: “opencode”,

  “autoupdate”: true,

  “share”: “manual”,

  “permission”: {

    “write”: “ask”,

    “edit”: “ask”,

    “bash”: “ask”,

    “delete”: “ask”

  }

}

Test: Khởi động OpenCode để xem có lỗi không:

opencode --version  # Kiểm tra version
opencode            # Mở TUI, nếu không báo lỗi config → OK

Bước 2: Project-specific config

Tạo file `./opencode.json` trong project:

{

  “$schema”: “https://opencode.ai/config.json”,

  “model”: “anthropic/claude-3-5-sonnet-20241022”,

  “small_model”: “anthropic/claude-3-5-haiku-20241022”,

  “provider”: {

    “anthropic”: {

      “options”: {

        “apiKey”: “{env:ANTHROPIC_API_KEY}”

      }

    }

  }

}

Bước 3: Test config hoàn chỉnh

# 1. Test trong project

cd your-project

opencode

# 2. Trong OpenCode, test các commands:

/models  # Xem danh sách models

/init    # Initialize project

# 3. Test với message:

opencode run “What models are available?”

# 4. Test agents (nếu đã config):

opencode agent list  # Xem danh sách agents

Validation: Nếu config có lỗi, OpenCode sẽ báo lỗi khi khởi động. Nếu không thấy lỗi → config OK! Bạn cũng có thể kiểm tra bằng cách xem models có hiển thị đúng không với lệnh /models.

6. Template Library (Copy-paste ngay)

A. Minimal Config Template

{

  “$schema”: “https://opencode.ai/config.json”,

  “model”: “anthropic/claude-3-5-sonnet-20241022”,

  “provider”: {

    “anthropic”: {

      “options”: {

        “apiKey”: “{env:ANTHROPIC_API_KEY}”

      }

    }

  },

  “permission”: {

    “edit”: “ask”,

    “bash”: “ask”

  }

}

B. Team Config Template

{

  “$schema”: “https://opencode.ai/config.json”,

  “model”: “anthropic/claude-3-5-sonnet-20241022”,

  “small_model”: “anthropic/claude-3-5-haiku-20241022”,

  “share”: “manual”,

  “permission”: {

    “write”: “ask”,

    “edit”: “ask”,

    “bash”: “ask”,

    “delete”: “ask”

  },

  “disabled_providers”: [”openai”],

  “instructions”: [”{file:./team-instructions.md}”]

}

C. Advanced Power User Config

{

  “$schema”: “https://opencode.ai/config.json”,

  “model”: “anthropic/claude-3-5-sonnet-20241022”,

  “small_model”: “anthropic/claude-3-5-haiku-20241022”,

  “autoupdate”: true,

  “tui”: {

    “scroll_speed”: 2

  },

  “tools”: {

    “write”: true,

    “bash”: true,

    “edit”: true

  },

  “agent”: {

    “security_reviewer”: {

      “description”: “Security-focused code reviewer”,

      “model”: “anthropic/claude-3-5-sonnet-20241022”,

      “prompt”: “Focus on security vulnerabilities and best practices”,

      “tools”: {

        “write”: false,

        “edit”: false

      }

    }

  },

  “command”: {

    “component”: {

      “template”: “Create React component with TypeScript and tests”,

      “description”: “Create component”

    }

  }

}

7. Common Config Mistakes (Tôi đã mắc hết)

1. Syntax JSON sai

Sai: Thiếu dấu phẩy, ngoặc

2. Model ID không chính xác

Sai: ”model”: “claude-3” (ghi sai tên model ID)

Lưu ý": Bạn có thể tìm kiếm full ID đúng chuẩn trong opencode system từ đây.

3. Provider chưa authenticate

Sai: Config xong không chạy opencode auth login

4. Permission quá strict

Sai: Disable hết mọi thứ → AI không làm được gì

5. Không test config sau khi viết

Sai: Viết xong không test → lỗi không biết

8. Best Practices & Performance Tips

A. Cost Optimization

• Dùng small_model cho tasks nhẹ (tiết kiệm 70%)

• Disable providers không dùng

• Test với model rẻ trước, sau đó scale up

B. Team Collaboration

• Commit opencode.json vào Git

• Dùng environment variables cho secrets

• Tạo team guidelines trong instructions

C. Security First

• Không hardcode API keys

• Review permissions cho team members

• Dùng disabled_providers thay vì xóa credentials

9. Kết luận: Bạn đã có config vững chắc

Config đúng giúp bạn:

• Tiết kiệm 30 phút mỗi ngày → 150 giờ/năm

• Team đồng bộ → Không còn “sao máy anh chạy được?”

• Security chuẩn → Tránh AI làm hỏng hệ thống

• Cost optimization → Không tốn tiền vô ích

Challenge: Hãy setup config cho project của bạn. Sau đó share:

• Bạn dùng template nào?

• Có lỗi gì khi setup?

• Config nào hữu ích nhất?

Test kết quả:

cd your-project

opencode

# Trong OpenCode, gõ: /models để xem config có hoạt động không

Next step: Trong bài 4, tôi sẽ dạy bạn master TUI - giao diện terminal hoàn hảo để làm việc như senior dev. Bạn sẽ thấy cách tối ưu layout, themes, và keybinds cho productivity tối đa.

Homework: Sau khi có config chuẩn, hãy thử làm việc với TUI 1 tuần. Note lại những gì bạn muốn cải thiện về layout, themes, hoặc keybinds. Trong bài 4, tôi sẽ dạy bạn optimize tất cả!

Thú thật, lần đầu nghe đến “AI coding agent”, tôi tưởng phải cài đặt gì siêu phức tạp. Loại tool này chắc cần server riêng, database, và cả đội ngũ DevOps để maintain chứ nhỉ?

Hoá ra không phải vậy.

OpenCode cài đơn giản như cài... Facebook vậy. Chỉ cần vài câu lệnh, vài cú click, xong. Không cần bạn phải biết Linux, không cần setup server, không cần học 50 câu lệnh terminal.

Hôm nay tôi sẽ chỉ bạn cách cài OpenCode trong 15 phút thực sự. Không ảo tưởng, không quảng cáo vớ vẩn.

Chuẩn bị: Kiểm tra “sức khoẻ” máy tính

Trước khi cài, kiểm tra máy bạn có đủ “sức” không:

1. Terminal emulator

OpenCode chạy trong terminal, nhưng không phải terminal mặc định của Windows đâu. Bạn cần 1 trong những thằng này:

Mac/Linux:

• iTerm2 (Mac) - miễn phí, đẹp

• Terminal mặc định cũng được

• WezTerm nếu bạn thích “hàng xịn”

Windows:

• Windows Terminal (cài từ Microsoft Store)

• WezTerm (cross-platform)

• Hoặc dùng WSL2 nếu bạn thích Linux

Kiểm tra: Mở terminal lên, gõ:

echo “Tôi đang dùng $(echo $SHELL)”

Nếu thấy hiện ra dòng chữ, tức là terminal bạn OK rồi đó.

2. Node.js version

OpenCode cần Node.js từ version 18 trở lên. Kiểm tra nhanh:

node --version

Nếu có lỗi “command not found”: Chưa cài Node.js, nhảy xuống phần “Cài đặt thiếu sót”.

Nếu version < 18: Cần upgrade. Ví dụ bạn thấy `v16.15.0`, thì phải lên 18+.

Nếu version >= 18: Perfect! Bỏ qua phần cài Node.js.

3. Git

git --version

Không có Git thì cài thôi. Có rồi thì thôi.

Cài đặt thiếu sót (nếu cần)

Cài Node.js đúng cách

• Mac (dùng Homebrew):

brew install node

• Ubuntu/Debian

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

• Window

1. Vào nodejs.org

2. Tải bản LTS (màu xanh)

3. Next → Next → Install

4. Khởi động lại terminal

Cài Git

• Mac

brew install git

• Ubuntu

sudo apt update && sudo apt install git

• Window

Tải từ git-scm.com, cài như bình thường.

Cài OpenCode (5 phút thực sự)

Có 3 cách cài. Tôi recommend cách 1, đơn giản nhất:

Cách 1: Script tự động (Recommended)

curl -fsSL https://opencode.ai/install | bash

Chờ 30 giây, xong. Script sẽ:

• Tự detect OS của bạn

• Cài đúng version

• Setup PATH

• Verify installation

Nếu gặp lỗi: Thử cách 2.

Cách 2: NPM (luôn đúng)

npm install -g opencode-ai

Chờ 1-2 phút tùy mạng. NPM sẽ tải về và cài global.

Verify:

opencode --version

Thấy hiện version (ví dụ: `v2.1.0`) = thành công!

Cách 3: Homebrew (Mac/Linux)

brew install sst/tap/opencode

Cách này cũng OK, nhưng đôi khi version chậm hơn 1-2 bản.

Kết nối với AI: Lấy API key

OpenCode cần AI để hoạt động. Có 2 cách:

Cách dễ nhất: OpenCode Zen (Recommend cho người mới)

1. Chạy:

opencode auth login

2. Chọn “opencode” từ menu

3. Nó sẽ hiện link: https://opencode.ai/auth

4. Click vào link, đăng ký, lấy API key

5. Paste vào terminal

Ưu điểm: Không cần setup gì thêm, dùng model đã test sẵn.

Cách pro: Dùng provider tùy chỉnh (OpenAI-compatible)

Nếu bạn có API key của Claude, OpenAI, hoặc bất kỳ provider nào khác, thêm qua `opencode auth login`:

1. Chạy lệnh:

opencode auth login

2.Chọn “Other” từ danh sách providers

3. Nhập provider ID (ví dụ: “anthropic”, “openai”, “custom-ai”)

4. Nhập API key của bạn

5. Tạo config trong opencode.json:

{

  “$schema”: “https://opencode.ai/config.json”,

  “provider”: {

    “anthropic”: {

      “npm”: “@ai-sdk/anthropic”,

      “name”: “Anthropic Claude”,

      “models”: {

        “claude-3-5-sonnet-20241022”: {

          “name”: “Claude 3.5 Sonnet”

        }

      }

    }

  }

}

Hoặc cho OpenAI-compatible providers:

{

  “$schema”: “https://opencode.ai/config.json”,

  “provider”: {

    “myprovider”: {

      “npm”: “@ai-sdk/openai-compatible”,

      “name”: “My AI Provider”,

      “options”: {

        “baseURL”: “https://api.myprovider.com/v1”

      },

      “models”: {

        “my-model”: {

          “name”: “My Model”

        }

      }

    }

  }

}

Test thử: Mở OpenCode lần đầu

1. Vào 1 project bất kỳ (hoặc tạo mới):

mkdir test-project && cd test-project
git init  # OpenCode cần git repo

2. Chạy:

opencode

3. Trong OpenCode, gõ:

/init

• Kết quả đúng: Thấy OpenCode analyze project, tạo file `AGENTS.md`.

• Kết quả sai: Hiện lỗi đỏ. Đọc tiếp phần “Fix lỗi thường gặp”.

Fix lỗi thường gặp (không ai tránh được)

Lỗi 1: “opencode: command not found”

Nguyên nhân: PATH chưa update.

Fix:

• Mac/Linux

export PATH=”$PATH:/usr/local/bin”

• Windows (trong Git Bash)

export PATH=”$PATH:/c/Users/$(whoami)/AppData/Roaming/npm”

Permanent fix: Khởi động lại terminal, hoặc reboot máy.

Lỗi 2: “Permission denied”

Nguyên nhân: NPM permissions lỗi.

Fix nhanh:

sudo npm install -g opencode-ai

Fix đúng: Fix NPM permissions (xem npmjs.com)

Lỗi 3: “Model not available”

Nguyên nhân: API key sai hoặc hết tiền.

Fix:

• Kiểm tra key có đúng không

• Vào dashboard provider xem còn credits không

• Thử model khác: `opencode config set model gpt-4`

Lỗi 4: “Not a git repository”

Nguyên nhân: Chạy OpenCode ngoài git repo.

Fix:

git init  # trong thư mục project

Script tự động kiểm tra (bonus)

Tôi viết script giúp bạn check mọi thứ tự động:

#!/bin/bash

echo “🔍 Kiểm tra OpenCode installation...”

# Check Node.js

if command -v node &> /dev/null; then

    NODE_VERSION=$(node --version)

    echo “✅ Node.js: $NODE_VERSION”

else

    echo “❌ Node.js chưa cài”

    exit 1

fi

# Check OpenCode

if command -v opencode &> /dev/null; then

    echo “✅ OpenCode: $(opencode --version)”

else

    echo “❌ OpenCode chưa cài”

    exit 1

fi

# Test functionality

echo “🧪 Testing basic functionality...”

cd /tmp

mkdir opencode-test-$$ && cd opencode-test-$$

git init --quiet

if opencode status &> /dev/null; then

    echo “✅ OpenCode hoạt động bình thường”

else

    echo “❌ OpenCode gặp lỗi”

fi

# Cleanup

cd ..

rm -rf opencode-test-$$

echo “🎉 Installation hoàn tất!”

Save file là `check-opencode.sh`, chạy:

chmod +x check-opencode.sh

./check-opencode.sh

Kết luận: Bạn đã có xe, nhưng chưa biết lái

Cài OpenCode xong, tôi nghĩ: “Xong! Giờ thì dùng thôi.”

Sai bét.

Giống như mới mua xe máy vậy - bạn có xe rồi, nhưng nếu không biết lái thì chỉ để ngắm thôi.

Tôi đã mất 3 tháng để hiểu điều này. 3 tháng đầu với OpenCode của tôi như thế này:

• Mỗi lần đổi project: mất 30 phút setup lại

• Team member hỏi: “Sao máy anh chạy được, máy em không được?”

• Lỗi “Model not available” hoài, không hiểu tại sao

• Cứ phải gõ lại cùng câu lệnh, cùng cấu hình

Nguyên nhân: Tôi không biết config đúng cách.

Điều gì sẽ xảy ra nếu bạn config sai?

• Dùng model sai → Tốn tiền vô ích

• Permission không đúng → AI xoá nhầm file quan trọng

• Không có custom commands → Mất 10 phút cho việc chỉ cần 30 giây

• Team không chung config → Hỗn loạn, mỗi người một kiểu

Tin vui: Bạn không cần mất 3 tháng như tôi

Trong bài tiếp theo, tôi sẽ dạy bạn config OpenCode đúng chuẩn senior dev:

✅ 15 phút setup - dùng cả năm không phải sửa

✅ Config chuẩn - validated với official schema

✅ Tùy chỉnh thông minh - theme, keybinds, permissions

✅ Custom commands - tự động hoá tasks lặp đi lặp lại

✅ Team-friendly - share config, đồng bộ workflow

Đặc biệt: Tôi sẽ cho bạn 3 templates config cho 3 loại project phổ biến:

• Web App (React/Next.js)

• Mobile (React Native)

• Backend (Node.js/Express)

Copy-paste → dùng ngay → không cần nghĩ.

Challenge: Test config hiện tại của bạn

Trước khi học config mới, kiểm tra cài đặt của bạn:

# 1. Kiểm tra cài đặt

opencode --version

# 2. Test với project thật

cd your-project

git status  # đảm bảo là git repo

opencode    # mở OpenCode lên

Trong OpenCode, thử gõ:

/init

Nếu thấy OpenCode analyze project và tạo file `AGENTS.md` → Cài đặt OK, chỉ thiếu config

Nếu gặp lỗi → Comment lỗi, tôi sẽ giúp fix

Homework nhẹ: Chụp screenshot kết quả `/init` và share trong comments. Tôi sẽ check xem bạn đang dùng model nào, có cần optimize không.

Next stop: Bài 3 - “Config OpenCode như senior: 15 phút setup để dùng 1 năm không phải sửa”

Subscribe now

Tháng 3/2022, tôi nộp đơn xin nghỉ việc. Không có job mới. Không có kế hoạch. Chỉ có quyết tâm: “Phải thoát khỏi ngành này.”

3 tháng đầu tiên: Học Google UX Design trên Coursera + Figma. Tôi nghĩ:

Tháng 6/2022: Bắt đầu học code thực sự. HTML/CSS/JavaScript/SQL. Rồi React. Rồi sao chép tutorial trên YouTube. Rơi vào tutorial hell đúng nghĩa.

Mỗi ngày 6-8 tiếng:

• Sáng: 8h-11h học JavaScript/SQL

• Chiều: 14h-17h làm project nhỏ

• Tối: 20h-22h xem tutorial

• Cuối tuần: 4 tiếng học React

Kết quả: Code hoạt động nhưng không hiểu tại sao. Copy-paste 70%, hiểu 30%.

Tháng 3/2023: Cú sốc đầu tiên

Tôi nộp đơn xin việc. Hơn 50 công ty, khoảng 1/2 đa số các công ty từ chối đều lý do:

Kiểm tra thực tế: Tutorial hell 9 tháng ≠ làm việc thực tế 9 tháng.

Tháng 6/2023: Breakthrough - Job remote đầu tiên

Công ty agency giáo dục ở London

Họ cần người vừa làm dev vừa làm design cho website giáo dục. Tôi nói:

• Lương: $600/tháng.

• Công việc: Fix bug, thêm feature, design giao diện.

• Tech stack: WordPress, Java, Figma.

Công việc thực tế:

- Sáng: Code Java backend cho hệ thống CMS nội bộ

- Chiều: Design giao diện cho landing page

- Tối: Fix bug WordPress của khách

1 năm đầu: Vẫn không dùng AI

Tôi tiếp tục làm thủ công:

• Đọc documentation Java từng dòng

• Debug WordPress bằng var_dump

• Google mỗi lỗi Java nhỏ

• Stack Overflow vẫn là người bạn thân nhất

Kết quả: Hiểu rõ từng dòng code. Bug ít. Nhưng... chậm như rùa.

Tháng 7/2025: Cú hit thực tế - Tôi đang tụt lại phía sau

Video của “người anh” trên YouTube

Anh ấy show workflow với AI. Code 1 feature trong 30 phút. Tôi mất 3 tiếng.

Tôi nhận ra: Mình đang làm việc như 2022 trong năm 2025.

FOMO bắt đầu

Tôi lao vào học:

• GitHub Copilot

• ChatGPT

• Cursor

• Vài tool khác

Kết quả: Rối loạn. Không biết dùng cái nào. Code rối hơn. Deadline vẫn đến.

Tháng 8/2025: Khám phá - OpenCode

Tại sao OpenCode khác biệt?

Không phải AI viết code thay tôi. AI giúp tôi:

• Hiểu codebase cũ nhanh hơn

• Tìm bug chính xác hơn

• Viết spec rõ ràng hơn

• Tự tin refactor hơn

3 tháng thực chiến: Chỉ số thực tế

Trước OpenCode:

• Hiểu feature mới: 2-3 ngày

• Fix bug phức tạp: 4-6 tiếng

• Viết tài liệu: 1-2 ngày

• Vòng code review: Mất tự tin

Sau OpenCode:

• Hiểu feature mới: 1/2 ngày

• Fix bug phức tạp: 1-2 tiếng

• Viết tài liệu: 2-3 tiếng

• Vòng code review: Confident hơn 80%

Sai lầm #1: Tự học không có định hướng

9 tháng học JavaScript nhưng không biết nên học gì tiếp theo. Mất 3 tháng học những thứ không dùng đến.

Đúng: Cần roadmap. Cần mentor. Cần feedback loop

Sai lầm #2: Không tận dụng AI làm đòn bẩy khi có cơ hội

1 năm đầu làm remote, tôi vẫn làm mọi thứ thủ công. Sợ “dùng AI sẽ không học được gì”.

Đúng: AI giúp học nhanh hơn, không phải học thay bạn.

Sai lầm #3: Không theo dõi tiến độ

Tôi không biết mình tiến bộ bao nhiêu. Không có những chỉ số. Không có điểm chuẩn.

Đúng: Phải đo lường để cải thiện.

Cách sử dụng OpenCode thực tế - Những gì bạn thực sự cần

Kiểm tra thực tế: OpenCode mặc định cho phép AI tự động edit file và chạy bash commands. Bạn phải config để an toàn.

Setup bắt buộc trước khi dùng

Tạo file `opencode.json` tại root project:

{
  “$schema”: “https://opencode.ai/config.json”,
  “permission”: {
    “edit”: “ask”,
    “bash”: “ask”
  },
  “model”: “anthropic/claude-sonnet-4-20250514”,
  “small_model”: “anthropic/claude-3-5-haiku-20241022”
}

Tại sao:

• permission.ask = bạn phải duyệt mọi thay đổi file/lệnh shell trước khi chạy

• small_model = tiết kiệm tiền cho tasks nhẹ (title, summaries)

• File này nên commit vào Git để cả team dùng chung config

Khi cần hiểu codebase

Mở TUI, hỏi trực tiếp với tham chiếu file (@path):

Không cần custom commands (phần này nâng cao, mình sẽ chia sẻ qua bài viết sau). Hỏi thẳng là đủ.

Khi cần refactor hoặc làm feature lớn

• Bước 1: Bật chế độ Plan-only bằng Tab key trong TUI (indicator góc dưới phải)

• Bước 2: Hỏi plan trước:

• Bước 3: Review plan → Tab lại để Build mode → cho AI code

Thay thế: Nếu muốn bắt buộc plan-only bằng config (ít dùng):

{

  “tools”: {

    “write”: false,

    “edit”: false

  }

}

Khi cần AI tuân theo các tiêu coding

Thêm vào config:

{

  “instructions”: [”CONTRIBUTING.md”, “docs/guidelines.md”]

}

AI sẽ đọc và follow rules trong những files này.

Khi AI code sai

• Dùng `/undo` để revert ngay

• Không cần hoảng loạn, không mất code

• Review prompt lại: có đủ context không? Có rõ ràng không?

Chỉ số thực tế để đo

• ✅ Số lần reject AI suggestions - cao = prompts chưa rõ hoặc config chưa đúng

• ✅ Thời gian review code AI generate - giảm dần = bạn và AI sync được

• ✅ Bug từ AI code - phải = 0 nếu bạn review trước khi merge

Những gì bạn KHÔNG cần

• ❌ Custom commands cho basic workflow

• ❌ Edit config liên tục giữa Plan/Build (dùng Tab)

• ❌ Hoàn hảo hóa setup trước khi dùng

Điểm mạnh thực tế của OpenCode

1. Tăng tốc độ thực sự

• Hiểu rõ codebase: Từ 3 ngày xuống 30 phút (nhanh hơn 90%)

• Tìm bug: Từ 4 tiếng xuống 30 phút (nhanh hơn 87% )

• Lập kế hoạch feature: Từ 2 tiếng xuống 20 phút (nhanh hơn 83% )

2. Tự tin hơn khi code

• Không còn “mệt mỏi, nhức đầu toàn tập vì phân tích quá nhiều”

• Biết chính xác phải làm gì

• Code review ít lỗi hơn

• Deploy không còn lo lắng

3. Học nhanh hơn

• Hiểu kiến trúc hệ thống nhanh hơn

• Phát hiện pattern trong code

• Học từ codebase lớn mà không bị choáng ngợp

4. Quản trị bằng cấu hình

• permission.ask: mọi thay đổi đều có con người quyết định

• instructions: ép theo tiêu chuẩn nội bộ, giảm vòng review

• công tắc tools: bật tắt write/edit để chuyển giữa chế độ chỉ lập kế hoạch (Plan-only) và chế độ xây dựng (Build) nhanh

Điểm yếu phải biết

1. Không phải viên đạn ma thuật

• Không viết code thay bạn: Bạn vẫn phải hiểu logic

• Không tự động fix bug: Chỉ giúp tìm nhanh hơn

• Không thay thế tư duy: Vẫn cần quyết định thiết kế

2. Đường cong học tập

• Mất 1-2 tuần: Để thành thạo commands cơ bản

• Phải đọc docs: Không tự nhiên như ChatGPT

• Cần cấu hình: Phải cấu hình nguyên tắc file AGENTS.md cho từng project

3. Giới hạn thực tế

• Logic nghiệp vụ phức tạp: Vẫn cần senior dev giải thích

• Codebase cũ quá lỗi thời: Đôi khi AI suggest không khả thi

• Kiến thức chuyên môn: Phải học business rules của domain

Chỉ số thực tế sau 3 tháng

Trước vs sau OpenCode:

• Hiểu feature mới: 2-3 ngày → 1/2 ngày (nhanh hơn 75%)

• Fix bug phức tạp: 4-6 tiếng → 1-2 tiếng (nhanh hơn 70%)

• Vòng code review: 2-3 rounds → 1 vòng (giảm 50%)

• Mức độ tự tin: 40% → 85% (tăng 112%)

Cải thiện chất lượng:

• Tỉ lệ bug: Giảm 60% nhờ lập kế hoạch tốt hơn

• Chất lượng code: Tăng 40% nhờ pattern nhất quán

• Viết tài liệu: Nhanh hơn 3 lần

• Làm việc nhóm: Hiểu nhau nhanh hơn

Điều quan trọng nhất tôi học được

• OpenCode khuếch đại kỹ năng bạn đã có

• Nếu bạn yếu về nền tảng, nó chỉ giúp bạn viết code yếu nhanh hơn

• Nếu bạn hiểu logic nghiệp vụ, nó giúp bạn triển khai nhanh hơn 10 lần

Kết luận thực tế:

• Developer giỏi + OpenCode = Siêu developer

• Developer yếu + OpenCode = Developer yếu nhanh hơn

• Developer trung bình + OpenCode = Developer giỏi nhanh hơn

Bài học lớn nhất:

Kết luận: Im lặng học, đừng im lặng chết

Tôi mất 2 năm để hiểu:

Bạn có 2 lựa chọn:

1. Tiếp tục làm thủ công, tiếp tục tụt lại phía sau, tiếp tục tự hào “tôi không dùng AI”

2. Học 1 tool thực tế, bắt đầu tận dụng AI, và tiến xa hơn đồng nghiệp

Bài tiếp theo: “Cài OpenCode trong 15 phút - Không cần làm Linux expert” - Tôi sẽ trình bày step-by-step cách setup, với screenshots và các bẫy phổ biến để bạn không mất 2 năm như tôi.

Câu hỏi thực tế: Bạn đang ở đâu trong hành trình này? Còn đang học thủ công hay đã sẵn sàng tận dụng AI? Comment xuống dưới, tôi muốn nghe câu chuyện thật từ cộng đồng dev Việt.

Subscribe để không miss bài tiếp theo. Tin tôi, bạn không cần mất 2 năm như tôi để đạt productivity tăng 3x.