One plugin standard, shared across seven tools.

Fig: Open Plugins — install once, works across seven tools

AI coding tools are multiplying: Cursor, Claude Code, Codex, Grok Build — each with its own plugin format. Then came Open Plugins.

It's an open standard maintained by Vercel Labs. Install one plugin, it runs across seven tools.

The Problem: AI Coding Tools in a "Plugin Warring States" Era​

Let's start with the problem.

Fig: Every tool speaks its own language — they don't integrate

Imagine you have a great set of AI coding assistants:

• A code review skill that automatically reviews changes before each commit
• An MCP server connecting to your company's API documentation
• A hook script that auto-formats files on save

You configure it once in Claude Code. Then you switch to Cursor and have to reconfigure everything. Switch to Codex and the format is different. It's like JavaScript before npm — every library had its own module format, and reusing anything meant manual work.

Open Plugins aims to end this fragmentation: define one standard, share across all tools.

npx plugins: How to Install​

One command:

# Install a plugin from GitHub (short format)
npx plugins add vercel/vercel-plugin

# Full HTTPS URL
npx plugins add https://github.com/vercel/vercel-plugin

# Install from local directory
npx plugins add ./my-plugin

# Preview components without installing
npx plugins discover owner/repo

# List locally detected tools
npx plugins targets

The plugins package (v1.3.4) is the Open Plugins ecosystem's "installer". Everything goes into .agents/plugins/ after installation.

Its workflow can be thought of as an assembly line:

Three installation scopes:

npx plugins add repo --scope user     # User-level (~/.agents/plugins/)
npx plugins add repo --scope project  # Project-level (./.agents/plugins/)
npx plugins add repo --scope local    # Local dev testing only

You can also target a specific tool:

npx plugins add owner/repo -t grok     # Install to Grok Build only
npx plugins add owner/repo -t vscode   # Install to VS Code only

Seven Supported AI Coding Tools​

npx plugins targets detects which tools you have installed and installs to all of them automatically.

Here are the supported tools and their component type compatibility:

Fig: Seven AI coding tools, one plugin standard

Full compatibility matrix:

Key differences:

• Cursor doesn't support Agents but supports LSP — ideal for deep in-editor usage
• Claude Code and Codex support Agents but not LSP — they follow the agent-oriented path
• Grok Build is provided through xAI's CLI, compatible with Claude Code's Skills and Agents formats
• GitHub Copilot CLI is the most versatile, supporting all component types
• VS Code currently has Agent Plugins in Preview — requires chat.plugins.enabled

Protocol Breakdown​

A plugin is essentially a directory with files organized by convention.

Standard Directory Structure​

Storage paths after installation:

~/.agents/plugins/          # User-level
<project>/.agents/plugins/  # Project-level

plugin.json Manifest​

The manifest is optional. If omitted, the plugin name is derived from the directory name and components are discovered in default locations only.

If provided, name is the only required field:

{
  "name": "my-plugin",
  "version": "1.2.0",
  "description": "Plugin description",
  "author": {
    "name": "Author",
    "email": "author@example.com"
  },
  "homepage": "https://example.com",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["code-review", "automation"]
}

name constraints: 1-64 characters, lowercase alphanumeric/hyphens/dots, must start and end with alphanumeric, no -- or ... ✅ deployment-tools, code-reviewer, prompts.chat ❌ My-Plugin, -tools, my--plugin

Component Discovery Algorithm​

This is the core of the protocol. The full process a tool uses to scan a plugin:

The plugin's four-stage lifecycle — from installation to activation:

Fig: Plugin installation, discovery, namespacing, and activation flow

${PLUGIN_ROOT} Path Expansion​

Any configuration file within a plugin can use ${PLUGIN_ROOT}, which the tool automatically replaces with the plugin root directory's absolute path. This makes plugins self-contained — all path references are relative to itself, working from any installation location.

{
  "mcpServers": {
    "db-server": {
      "command": "${PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${PLUGIN_ROOT}/data"
      }
    }
  }
}

Expansion rules: recursive expansion (nested references are replaced); escape checking ensures paths don't leave the plugin directory.

In Practice: Migrating CloudBase MCP to Open Plugins​

Enough theory — let's get real.

We've been maintaining an open-source project called CloudBase MCP that provides cloud access for AI coding tools — AI model invocation, NoSQL/PostgreSQL databases, cloud functions, CloudRun, cloud storage, WeChat Mini Program integration, and more. Previously we manually configured .claude-plugin/, .codex-plugin/, .mcp.json — one config per tool, a maintenance headache. Open Plugins came at the perfect time for a migration.

Full migration PR: TencentCloudBase/CloudBase-MCP#808 (+818 / -34)

Fig: PR #808 before/after — from vendor-specific formats to a universal plugin standard

Before vs After​

plugin.json​

Following the Open Plugins spec v1.0.0 closed schema, only retaining permitted metadata fields:

{
  "$schema": "https://open-plugins.com/schemas/1.0.0/plugin.schema.json",
  "name": "cloudbase",
  "version": "0.2.0",
  "description": "Tencent CloudBase — AI models, authentication, NoSQL/PostgreSQL databases, cloud functions, cloud storage, CloudRun backend services, and WeChat Mini Program integration.",
  "author": {
    "name": "Tencent CloudBase",
    "url": "https://cloudbase.net"
  },
  "homepage": "https://github.com/TencentCloudBase/cloudbase-mcp",
  "license": "MIT",
  "keywords": [
    "cloudbase", "tencent-cloud", "baas",
    "ai-model", "database", "cloud-function",
    "authentication", "storage", "cloudrun"
  ]
}

mcp.json​

MCP server config moved from .mcp.json to the spec path mcp.json:

{
  "mcpServers": {
    "cloudbase-mcp": {
      "command": "npx",
      "args": ["-y", "@cloudbase/cloudbase-mcp@latest"],
      "env": {}
    }
  }
}

Automated Build​

Wrote a build-open-plugin-spec.mjs build script that auto-generates artifacts from .claude-plugin/plugin.json. Added a --check mode for CI — every PR auto-validates to prevent source updates without regenerating artifacts.

# Generate artifacts
node scripts/build-open-plugin-spec.mjs

# CI mode: check only, no writes
node scripts/build-open-plugin-spec.mjs --check

GitHub Actions workflow (.github/workflows/open-plugin-spec-check.yml) runs checks on every PR automatically.

Validation Results​

The biggest win: installing to every tool with one command:

npx plugins add TencentCloudBase/cloudbase-plugin

And because we already had 4 Skills under skills/, npx plugins discover automatically registered them as namespaced commands:

No extra config needed — just place directories by convention.

First Pitfall: marketplace.json Conflict​

After PR #808 was merged, I excitedly ran npx plugins add TencentCloudBase/CloudBase-MCP and got:

No plugins found. 2 remote plugin(s) not shown.

The plugin was in the repo, but the CLI couldn't find it.

After digging: the main repo root has a marketplace.json — an index file for Claude Code and Codex marketplace add. The npx plugins CLI detected it and identified the entire repo as a marketplace (multi-plugin collection), refusing to install subdirectory plugins.

Solution: Create dedicated plugin repos

Following Vercel (vercel/vercel-plugin) and Supabase (supabase-community/supabase-plugin) — create dedicated plugin repos whose root contains only .plugin/plugin.json, no marketplace.json, so the CLI identifies them as single plugins.

Created two repos:

Content auto-synced from the main repo's plugin/cloudbase/ and plugin/cloudbase-sites/, excluding marketplace.json during sync — that's the key.

Automated sync mechanism

New files added:

All validations passed:

npx plugins discover TencentCloudBase/cloudbase-plugin --remote
# → ✅ Found 1 local plugin(s), 28 skills, 5 cmds, 2 agents, hooks

npx plugins add TencentCloudBase/cloudbase-plugin --target cursor --scope local
# → ✅ Installed

npx plugins discover TencentCloudBase/cloudbase-sites-plugin --remote
# → ✅ Found 1 local plugin(s), 1 skill, hooks

Install commands now point to the dedicated repos:

# Main plugin
npx plugins add TencentCloudBase/cloudbase-plugin

# Sites plugin
npx plugins add TencentCloudBase/cloudbase-sites-plugin

The core lesson: Open Plugins treats a repo with marketplace.json at its root as a plugin collection, not a single plugin. If your repo has multiple artifacts (like CloudBase-MCP with both an MCP server and plugins), you need dedicated plugin repos. Vercel and Supabase do the same.

The Hook System​

When I read the spec, the Hook system was the most striking part — it can hook into every lifecycle point of an agent workflow. But heads up: Hooks aren't in Spec v1, support is entirely up to the host tool. Claude Code and Copilot CLI have the fullest support, VS Code and Kimi Code don't recognize them (silently ignored, no error).

Fig: The Hook system — complete event chain from SessionStart to SessionEnd

Event Overview​

Three Action Types​

command — Execute an external script, event context passed via stdin JSON:

{ "type": "command", "command": "${PLUGIN_ROOT}/scripts/lint.sh" }

prompt — Send a prompt to the LLM, $ARGUMENTS replaced with event context:

{ "type": "prompt", "prompt": "Review the change: $ARGUMENTS" }

agent — Similar to prompt but with tool access, enabling multi-step verification:

{ "type": "agent", "prompt": "Verify style guide compliance: $ARGUMENTS" }

Execution Model​

• Multiple rules can match the same event — all execute
• Hooks within the same rule run sequentially in array order
• Implementations should set timeouts
• Failures must not crash the host tool

Adding Open Plugins Support to Your Tool​

If you're building an AI coding tool and want plugin ecosystem compatibility, five things to implement:

Five Core Capabilities​

Integration by Tool​

Each tool has a different existing plugin mechanism. npx plugins does a translation layer during installation — converting the universal .plugin/ format into each tool's native format:

Security Protection Model​

Closing Thoughts​

Open Plugins reminds me of when npm was just gaining traction ten years ago. JavaScript package management was a mess: AMD, CommonJS, UMD, IIFE… every project had its own system. Then npm + ES Modules unified the standard, and the entire ecosystem took off. The AI coding tool plugin ecosystem is in that "pre-npm" era right now.

Migrating CloudBase MCP was a fascinating process. From npx plugins discover identifying the plugin, to installing it across every tool with one command — that feeling of "write once, use everywhere" is exactly what this standard aims to deliver.

Fig: npx plugins add TencentCloudBase/cloudbase-plugin — one command to install everywhere

If you build extensions for AI coding tools, I recommend checking out the Open Plugins spec. The good news is you don't need anything complex — just add a .plugin/plugin.json to your project and it becomes discoverable by 7 tools. Our migration was about 400 lines of code, finished in under two days.

The CloudBase-MCP plugins are at these repos, for reference:

npx plugins add TencentCloudBase/cloudbase-plugin
npx plugins add TencentCloudBase/cloudbase-sites-plugin

Open Plugins isn't "mature" yet, but the direction is right. Getting the same plugin to work across different tools is a problem worth solving. The rest depends on how the community grows.

References​

• Open Plugins Official Site
• plugins npm package — the npx plugins add installer
• Agent Skills Specification
• Model Context Protocol
• CloudBase Plugin — Open Plugins standard plugin repo
• CloudBase Sites Plugin — Sites plugin repo
• CloudBase MCP — Tencent Cloud MCP plugin
• PR #808: CloudBase MCP Open Plugin Spec Integration

You ask it to replace all fetch calls with axios, grab a coffee, come back — and it's done three files and stopped waiting for approval. Repeat seven or eight times, and your coffee is cold.

Or you ran /loop overnight to watch a PR, wake up to find it got stuck on a git merge conflict at 2 AM. The window has been open all night.

Or you launched three sub-agents to research independently — and ended up with three contradictory conclusions because none of them saw what the others were doing.

The root cause isn't that AI isn't smart enough. Claude Code is turn-based — each turn does one thing, then waits for you to decide the next step. To make it run continuously, decide autonomously, and work in parallel, you need orchestration mechanisms to bridge the gap.

Claude Code gives you five: /goal, /loop, sub-agent, Agent Teams, and Workflows.

Pick wrong, and you're not just wasting tokens — you're making things more complicated.

Pain point 1: I'm waiting for it, it's waiting for me​

You give AI a clear goal. It's capable of completing it. But after every turn it stops and waits for your approval. This is what /goal solves.

/goal — conditional autonomous polling​

/goal Complete data-editor test generalization into a cross-module standard test framework in three steps:
  Step 1: Create shared test-utils.sh
  Step 2: Create verify-*.sh for each module
  Step 3: Update acceptance criteria

Under the hood it's a lightweight Stop Hook: registering a type: 'prompt' hook into sessionHooksRegistry, triggered after each turn for evaluation.

The evaluator receives three things:

1. Goal condition — your /goal description
2. Conversation transcript — everything since the goal was set
3. Metadata — session ID, timestamp, permission mode, etc.

Output is structured JSON:

{"ok": false, "reason": "Step 1 complete, test-utils.sh created, but Step 2 hasn't started"}

ok: true → stop. ok: false → continue with reason.

Key design: the working model and the evaluating model are separate. The main model doesn't grade itself. The evaluator only reads transcripts, not executing, so it can judge objectively.

Limitations:

• Serial — one turn at a time, just saves you from pressing Enter manually
• Evaluator is opaque — no logs telling you why it passed or failed
• Transcript grows — longer conversations mean higher evaluation cost each turn
• Evaluation latency — Haiku is faster, Sonnet is more accurate

When to use​

Good for: tasks with a clear terminal state, potentially spanning multiple turns, where you don't want to sit and supervise.

Not for: continuous monitoring scenarios (use /loop), or open-ended exploratory tasks.

One detail: you can swap the evaluator model. Use Sonnet for complex goals and a smaller model for simpler ones to save cost.

Requires v2.1.139+

Pain point 2: projects go stale when left alone​

Many scenarios have no end state — PRs need ongoing attention, CI failures need handling, dependencies need upgrading. You can't watch the terminal 24/7. But if you don't, it might get stuck all night.

/loop — adaptive scheduler​

/goal cares about "is it done." /loop cares about "what needs to be done now."

Without arguments, it runs a three-stage pipeline:

1. Finish incomplete work
2. Check current PR comments, CI status, merge conflicts
3. Run lint, type checking, formatting

Interval adjusts dynamically: 1 minute when active, gradually extending to 1 hour when idle.

/loop          # adaptive mode (recommended for daily use)
/loop 15m      # fixed 15-minute interval
/loop 2h       # fixed 2-hour interval

The three stages aren't hardcoded logic — they're built-in prompt templates. Claude decides which step to execute. Adaptive intervals also depend on Claude's perception of "what just happened," not external metrics (CI status, CPU, logs).

This limitation explains why adaptive mode is unavailable on Bedrock, Vertex AI, and Azure Foundry — it falls back to a fixed 10-minute interval. Those platform APIs don't support "model decides interval" communication patterns.

Cost: /loop runs in the same session. Turn 10's context is much heavier than turn 1's — it carries artifacts from the previous 9 turns. Overhead increases, attention dilutes. The issue isn't /loop itself being expensive — it's session aging.

Pain point 3: main context gets polluted with junk​

When a session runs long, the context fills up with intermediate artifacts — docs you read, approaches you tried, paths you corrected. You're spending more tokens while the model gets "dumber." But your auxiliary work (reading API docs, researching libraries, validating hypotheses) shouldn't pollute the main thread.

Sub-Agent — context-isolated workers​

Sub-agents solve the "main context is precious" problem. Each sub-agent starts with a fresh context window — it can't see your conversation history. It only returns a summary when done, never polluting the main session. Nesting is limited to 5 levels, hardcoded and not configurable.

Isolation mechanism (source code from forkedAgent.ts):

• Independent AbortController: parent session cancellation doesn't affect sub-agents, and vice versa
• No-op state propagation: parent session doesn't pass any internal state. The sub-agent doesn't even know which tools the parent used. To share context, you must explicitly pass it via prompt

The 5-level limit is practical: each nesting level opens a new LLM session. Depth 5 means maintaining 5 sessions' token overhead simultaneously. Sub-agents beyond the depth limit won't receive Agent tools — effectively silently rejected.

Three ways to create​

# Method 1: one-shot
/agent Go research this function's call chain

# Method 2: config file (persistent)
# .claude/agents/researcher.yaml
name: researcher
description: Agent specialized in technical research, good at reading source code and docs
prompt: You focus on research...
model: claude-sonnet-4-20260514
disallowedTools: [Write, Edit]

# Method 3: SDK
const agent = claude.subAgent({ prompt: "..." });

The description field in config files has a special role — Claude automatically decides when to delegate tasks based on descriptions.

When to use​

Sub-agents in teams​

In multi-person collaboration, project-level .claude/agents/ directories can be git-shared. Team members push their configured agents, others pull them down and use them. This makes agent configuration an engineering asset — part of the project, like .claude/rules/.

Pain point 4: ten tasks crammed together​

/goal runs one task. Sub-agent handles one sub-task. But you have ten things to do — fix bugs, refactor modules, write docs, prepare demos. You can't do them one by one, and you can't let them step on each other.

Agent Teams — observable parallelism​

Introduced in Claude Code v2.1.166+. Core idea: each task runs in an independent session, no interference. The main session creates tasks with an agenda (like a job description). The Teams layer handles scheduling.

Key behavior:

Task → sub-Agent session (independent, invisible)
       ↕
Task → sub-Agent session (independent, invisible)
       ↕
Main session ← observable ← Agent reporting

Compared to sub-agents, Teams adds three layers:

1. Observability — main session sees each Agent's real-time progress
2. Parallel execution — each Agent runs in its own session, truly parallel
3. Passive scheduling — no need to explicitly specify when to do what; the system decides automatically

Task assignment rules​

The main session decomposes tasks and distributes them. The decomposition isn't fixed prompt engineering — it's the model's own judgment. Give it an agenda like "refactor the user module" and it decides how to split.

The granularity of decomposition tells you how well it understood: coarse means it didn't really get it; fine-grained means it understood the dependency chain.

Debugging challenges​

Independent sessions mean independent token consumption. When things work, fine. When they break, you have no idea which Agent, at which step, for what reason. There's no global log — each session's input/output can only be examined individually.

The official UI shows them in the same TUI, but the data from independent sessions can only be inspected indirectly through the main session. There's no centralized debug view. This is the natural cost of parallelism.

Pain point 5: complex tasks can't be driven by pure conversation​

Some tasks aren't "just do it" — they're multi-step with tight coupling between phases: research first, then design, then code, then test. One wrong step derails everything. Without a framework to constrain the process, relying purely on the model's free-form reasoning means "works the first time, fails the second."

Workflows — deterministic process​

Workflows is Claude Code's newer mechanism, using declarative YAML to define multi-agent collaboration topology. The difference from Teams isn't about which is more powerful — it's about different orchestration philosophy:

Workflow phase definition:

name: "feature-dev"
agents:
  design:
    model: claude-sonnet-4-20260514
    prompt: "You handle technical design..."
  implement:
    model: claude-sonnet-4-20260514
    prompt: "You handle implementation..."
  review:
    model: claude-sonnet-4-20260514
    prompt: "You handle code review..."

steps:
  - agent: design
    output: DESIGN
  - agent: implement
    input: DESIGN
    output: CODE
  - agent: review
    input: CODE
    output: REVIEW

Each step's output is the previous step's output path; input is the current step's input. The chain is clear — when something breaks, you know which step.

Workflow task types​

Three built-in types:

• feature — serial step-by-step
• swe — software engineering multi-turn loop (design → code → test → fix → review)
• research — exploratory research (not multi-step, lets the agent explore freely)

Decision guide: which mechanism for which scenario?​

                   What's your pain point?
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   Turn-by-turn approval   Can't watch      Task too complex
   /goal                   /loop            Workflows
          │                │
          ▼                ▼
   Main context bloated   Ten tasks at once
   sub-agent              Agent Teams

Specifically:

• Single clear goal, potentially multi-turn process → /goal (serial autonomous, lightest weight)
• No end state, needs ongoing attention → /loop (adaptive, but watch for session aging)
• Auxiliary work shouldn't pollute main context → sub-agent (best isolation)
• Multiple independent tasks simultaneously → Agent Teams (true parallelism)
• Quality stability required, tightly coupled steps → Workflows (most deterministic)

Final thoughts​

The common source of these pain points isn't Claude Code's feature gaps — it's that we're asking AI to do things its design isn't optimized for: running continuously, deciding autonomously, collaborating in parallel. /goal disguises turn-based interaction as continuous execution. /loop packages waiting as adaptive scheduling. Sub-agents fight context bloat with isolation. Every mechanism compensates for the turn-based model's limitations.

From a patchwork perspective, they're indeed hooks and session-level wrappers. But look at it differently: Claude Code didn't reinvent the runtime. It built a spectrum of orchestration capabilities on top of the turn-based model — from simple to complex, from serial to parallel — using the lightest-weight approaches possible (hooks, new sessions, JS sandbox).

Turn-based isn't a flaw — it's a constraint. Each turn handing control back means interruptible, auditable, and intervenable. Systems that run continuously are hard to stop when something goes wrong. Turn-based gives you a natural safety boundary.

Orchestration is the art of trade-offs. Want predictability? Use Workflows, lose flexibility. Want isolation? Use sub-agents, accept context sync costs. No perfect mechanism — only trade-offs.

The most expensive thing isn't tokens — it's your attention. Saving the time you spend staring at the terminal is worth far more than saving a few tokens. Freeing cognitive bandwidth is the real value of these mechanisms.

🥚 Easter egg: a ready-to-use agent config pack​

The most useful thing I can do is give you pre-configured agents. Here's my current .claude/agents/ setup — three configured Agents, each focused on one thing:

1. researcher — research only, no code changes

# .claude/agents/researcher.yaml
name: researcher
description: Agent specialized in technical research, good at reading source code, docs, and validating hypotheses
prompt: |
  You are a technical research assistant.
  Your tool permissions are read-only: you can Read, Grep, Glob, but not Edit, Write, or Bash (except non-destructive commands).
  Your task format:
    ## Research Goal
    [Question to investigate]
    
    ## Context
    [Relevant code/documentation location]
  Output:
    - Key findings (3-5 items)
    - Evidence sources (file path + line number)
    - Recommended approach or next steps
model: claude-sonnet-4-20260514
disallowedTools: [Write, Edit, Bash]

2. reviewer — code review, no code changes

# .claude/agents/reviewer.yaml
name: reviewer
description: Code review focused on security, performance, maintainability
prompt: |
  You are a code review assistant.
  Read-only. Given a PR diff or code block, review against:
  1. Security (SQL injection, XSS, credential leaks)
  2. Performance (N+1 queries, unnecessary loops, memory leaks)
  3. Maintainability (code duplication, naming, complexity)
  4. Test coverage (what's missing, how to add)
  Each issue gets a severity label: P0(must fix) / P1(should fix) / P2(nice to fix)
model: claude-sonnet-4-20260514
disallowedTools: [Write, Edit]

3. refactorer — focused on refactoring, full permissions

# .claude/agents/refactorer.yaml
name: refactorer  
description: Code refactoring agent for well-scoped refactoring tasks
prompt: |
  You are a refactoring assistant.
  You receive a specific module path + refactoring goal.
  Rules:
  - Before refactoring, run tests once to confirm baseline passes
  - After each change, run related tests; roll back on failure
  - Don't modify files outside the module boundary
  - Output a change summary after refactoring
allowedTools: [Read, Write, Edit, Bash, Glob, Grep]

Usage: Drop these files in your project's .claude/agents/ directory, then call /agent researcher or /agent reviewer from Claude Code. Push to the repo and the whole team can use them.

What scenarios are you using these mechanisms for? What pitfalls have you hit? Drop a comment!

Based on real Claude Code usage + source code analysis (forkedAgent.ts / sessionHooksRegistry / DynamicWorkflow testing), regularly updated.

This article covers four things: ① What Codex is and what it can do → ② Five-minute hands-on: build a playable game → ③ Core usage and features → ④ Connect low-cost Chinese open-source models and deploy your app so others can access it.

Short on time? Codex now supports DeepSeek, GLM, and other affordable models. Want to save money + one-click deploy? Jump to Step 4 and copy one config. Want the full picture? Read on.

Step 1 · Meet Codex​

Codex is OpenAI's AI coding desktop tool. In the first half of 2026, its weekly active users grew from 600K to 5 million. The growth was so notable that in April, Sam Altman posted on X: "Resetting all user limits — I'll reset again for every million more." Most interesting stat: about 20% of users don't write code at all — they're product managers, operators, investors.

What matters to you: on June 18, OpenAI opened up third-party models. DeepSeek, GLM, Kimi — all pluggable now. Run cheap Chinese models and dramatically cut your costs.

How is it different from ChatGPT?​

Most people's first reaction: "Isn't this just ChatGPT that can write code?" Not even close.

ChatGPT is conversational — you ask, it answers, it gives advice, but you still have to do the work yourself. Codex works directly on your file system. You tell it "write a Snake game" — it creates files, installs dependencies, runs and debugs.

Example: ask ChatGPT to write Snake, it gives you code. You have to create the file, paste it, install libraries, run it, debug it. Ask Codex to write Snake — it creates a project folder, generates code, installs dependencies, runs the game. If it errors, it reads the error, fixes the code, and retries until it works.

ChatGPT is an advisor. Codex is the one who gets things done.

Step 2 · Five minutes to a playable game​

Install it: Download · Login · Meet the UI​

Go to codex.com, download the desktop app, log in with your OpenAI account.

The interface is simple — three parts:

• Left: project file list
• Center: conversation window + code editor
• Bottom right: terminal (see what it's doing)

First task: one sentence, build Snake​

Open Codex, type in the chat:

Write a Snake game in Python using pygame, make it runnable

It starts working immediately. Watch the center panel — it creates files, writes code, then auto-runs.

It might error on the first try (e.g., pygame not installed). It detects the problem, installs the dependency, and retries. Eventually a window pops up and Snake is running.

From opening Codex to playing the game — five minutes if you're quick.

Step 3 · Before you dive in, understand these​

① Three permission levels: what Codex can touch​

Codex has three permission levels:

• Clipboard Only: read-only clipboard access. Safe but useless.
• Read & Write Files: can read and write files. The sweet spot for daily work.
• Admin: can install software, change system settings.

Default is Read & Write — good enough for building games, writing code, and deploying.

② Plugin · Skill · MCP: three easily confused terms​

They're not the same thing:

• Plugin: external APIs Codex can call — like connecting a database, sending messages, checking weather. Codex ships with dozens built in.
• Skill: a set of instructions that teach Codex how to do something. Write a Skill once, and next time just say the word.
• MCP Server: a universal interface that lets Codex talk to external tools.

③ The killer feature: Skills — teach it once, reuse with one sentence​

Example: you want Codex to always run tests, check types, and format code after writing. Write a Skill:

## Code Quality Rules

After completing any code changes:
1. Run `npm test` to ensure all tests pass
2. Run `npx tsc --noEmit` to ensure no type errors
3. Run `npx prettier --write .` to format code

Save it as a Skill. Next time say "run my quality rules" — it follows the full process.

Interlude · It's way more than just writing code​

⏰ Scheduled automation​

Codex supports scheduled tasks: run tests every morning at 9 AM, update dependencies every Monday. It does the grunt work while you sleep.

🚀 One-click website deployment​

Finished a web page? Tell Codex and it deploys. With MCP plugins, it can connect directly to cloud services.

📱 Remote control from your phone​

Codex has a mobile app — check task progress and send new commands on the go. See a bug during your commute? Tell it to fix it from your phone.

📄 Generate docs and images too​

Architecture diagrams, changelogs, illustrations — it can do all of those.

Step 4 · Use cheap Chinese models and deploy your game​

First, the problem: saving money with Chinese models hits a wall​

Codex defaults to OpenAI's own models — fine for daily development. But if you're running lots of automated tasks or team collaboration, token consumption adds up fast.

On June 18, Codex opened up third-party model support. But there's a catch: you need to handle API keys, model configuration, and deployment environment yourself.

The solution: CloudBase (configure models + install plugins)​

CloudBase is Tencent Cloud's Serverless platform, and its AI Toolkit solves this exact problem.

Configure models (5 minutes)​

CloudBase supports both OpenAI and Anthropic protocols. DeepSeek, GLM, Kimi — all accessible with one API key. Once configured, select Chinese models directly in Codex. Token costs drop to a fraction of the original.

Install plugins (one-click deployment)​

With the CloudBase MCP plugin installed, Codex can deploy apps directly from the conversation. No need to manually log into a cloud console, configure domains, or upload files. Just say "deploy it" and it handles everything.

Final thoughts​

What Codex has proven in the last six months: AI tools are no longer about "can they answer questions" — it's about "can they finish the job and deliver the goods."

For someone like me, the real barrier isn't "are there cheap models" — it's the hassle of integration and having nowhere to deploy. The protocols need to match, and you need a place to land what you built. After going through the whole cycle, my answer is CloudBase: all three protocols compatible, Chinese models accessible with one key, and one-click deploy from the same window.

Other token plans just give you tokens. CloudBase gives you a place to ship.

Have you used Codex? For coding or something else? Drop a comment — I read them all.

• No browser (remote server, no GUI)
• No sudo (can only install to my ~/bin)
• Needed gh to authenticate and create PRs
• Critical: couldn't send a Token through the IM chat (IM servers, chat history, agent context — every layer sees it)

Traditional OAuth requires browser redirects. Not an option here.

First instinct: generate a Personal Access Token manually, pipe it in with gh auth login --with-token. It works, but it's painful — open GitHub settings, find the token page, select permissions, copy, paste in terminal. Months later when the token expires, repeat everything.

I dug through GitHub CLI's docs and found it uses a different path by default: Device Flow (device authorization grant). Running gh auth login --web prints a verification code. You open github.com/login/device on another device, enter the code, and the terminal auto-completes auth.

The whole process takes under two minutes. I thought — this is clever. Worth taking apart to see how it works under the hood.

Installing the CLI without sudo​

First, the environment. This server is a typical setup:

# No sudo, manual gh install
mkdir -p ~/bin
cd /tmp
curl -fsSL https://github.com/cli/cli/releases/download/v2.62.0/gh_2.62.0_linux_amd64.tar.gz -o gh.tar.gz
tar -xzf gh.tar.gz
cp gh_2.62.0_linux_amd64/bin/gh ~/bin/
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/bin:$PATH"
gh --version

Then authentication:

gh auth login --web --hostname github.com --git-protocol https

Terminal output:

! First copy your one-time code: BFEE-895F
Open this URL to continue in your web browser: https://github.com/login/device

I opened the link on my laptop, entered the code, clicked Authorize. Back in the terminal, hit Enter—

✓ Authentication complete.
✓ Logged in as binggg

Done. No SSH keys, no manual token entry, no sudo.

But one detail caught my eye: the terminal just printed a code and started polling — how did it know I completed authorization on my browser? The communication happened entirely between the CLI and GitHub's servers. The browser never talked to the terminal.

That's what makes Device Flow interesting.

Device authorization: decoupling "login" from the device​

Device Flow's core idea is simple.

Traditional OAuth authorization code flow assumes the user has a browser — the app can redirect to an auth page and back. But smart TVs, CLI tools, IoT devices — these don't have a browser, or typing a URL is painfully impractical.

The solution: let the user authorize on a different device, while the device polls for the result.

I later read the RFC 8628 spec and found the whole flow breaks down into four steps:

Step 1: Device requests a verification code​

The CLI sends a POST to the authorization server:

POST https://github.com/login/device/code
client_id=xxx&scope=repo,gist

The server responds:

{
  "device_code": "3584d83530557fdd1f46af8289938c8ef79f9dc5",
  "user_code": "BFEE-895F",
  "verification_uri": "https://github.com/login/device",
  "expires_in": 900,
  "interval": 5
}

Three key fields:

• user_code (BFEE-895F) — the code you type manually, 8 characters, human-friendly
• device_code (40 chars) — used internally by the client, never shown to the user
• interval (5 seconds) — suggested polling interval from the server

Step 2: You work in the browser​

The terminal prints the verification code. You open github.com/login/device on your phone, enter it. At this point the browser and GitHub's server complete the full OAuth authorization — you log in, review permissions, click Authorize.

Note: This step has zero direct communication with the terminal. Your phone's browser doesn't know the terminal exists, and the terminal doesn't know what you did on your phone.

Step 3: Device polls continuously​

This is the cleverest part. The terminal doesn't know when you'll finish authorizing, so it asks the server every 5 seconds: "Did they click yet?"

POST /login/oauth/access_token
device_code=xxx&grant_type=urn:ietf:params:oauth:grant-type:device_code

Not yet:

{"error": "authorization_pending"}

Authorized:

{"access_token": "gho_16C7e42F292c6912E7710c838347Ae178B4a", "scope": "repo,gist"}

The polling isn't infinite. The device_code expires in 15 minutes. If it times out, the client must stop and error. On expired_token, the client should tell the user to restart.

Step 4: Use the token​

Once you have the token, it's standard OAuth:

curl -H "Authorization: Bearer gho_xxx" https://api.github.com/user

Polling strategy: how important is client "politeness"?​

When actually writing polling code, there are subtleties around interval and error handling that I didn't expect.

RFC 8628 defines 5 error codes, each with different client behavior:

slow_down is the most thoughtful design decision — many protocols just 429 and disconnect. Device Flow has a dedicated error code telling the client "I'm not saying don't ask, just ask more slowly." When you receive this, add 5 seconds to your current interval.

A correct polling implementation looks like:

import time, requests

def poll_for_token(device_code, client_id, interval=5):
    timeout = 900
    elapsed = 0
    
    while elapsed < timeout:
        r = requests.post(
            "https://github.com/login/oauth/access_token",
            data={
                "client_id": client_id,
                "device_code": device_code,
                "grant_type": "urn:ietf:params:oauth:grant-type:device_code"
            },
            headers={"Accept": "application/json"}
        )
        data = r.json()
        
        if "access_token" in data:
            return data["access_token"]
        
        err = data.get("error")
        if err == "authorization_pending":
            time.sleep(interval)
            elapsed += interval
        elif err == "slow_down":
            interval += 5  # permanent increase
            time.sleep(interval)
            elapsed += interval
        elif err in ("expired_token", "access_denied"):
            raise Exception(f"Authorization failed: {err}")
        else:
            raise Exception(f"Unknown error: {err}")
    
    raise Exception("Authorization timeout")

Two easy-to-miss points:

1. On slow_down, the 5-second increase is permanent. You don't revert to the original interval. RFC 8628 requires this.
2. You can show progress feedback during polling. gh auth login just waits silently — a spinner or countdown would tell the user the program is still running.

Device Flow vs traditional OAuth: not a replacement, a complement​

After reading RFC 8628, I put together this comparison:

GitHub CLI's choice of Device Flow makes practical sense: CLI might run in Docker containers, CI environments, or jump boxes — none of which have browsers, and configuring callback URLs is painful. Device Flow doesn't need a registered callback URL, doesn't need client_secret (which a CLI binary couldn't keep secret anyway). It's the simplest approach for CLI tools.

Security: is an 8-character code enough?​

My first reaction was that 8 characters is too short. Reading RFC 8628's design rationale helped me understand the trade-off.

8 characters from a 20-character alphabet (uppercase with ambiguous characters removed) gives 20⁸ ≈ 2³⁴·⁵ bits of entropy. Not high on its own, but combined with several constraints it's sufficient:

1. 15-minute expiry — short time window
2. Rate limiting — max 50 code attempts per hour
3. One-time device_code — one device code, one token, consumed immediately

The real security risk isn't code length — it's remote phishing. An attacker could fake a page asking for the code and then authorize with their own account. GitHub mitigates this by showing device type, IP address, and permission scope on the authorization page, giving the user information to make a judgment.

Token storage is another easy-to-miss issue. gh stores tokens in ~/.config/gh/hosts.yml with chmod 600. If you're writing your own Device Flow tooling, don't leak tokens to shell history or store them in plain text. macOS users can use Keychain, Linux users can use Secret Service:

# macOS
security add-generic-password -a "$USER" -s "github_token" -w "gho_xxx"

# Linux
secret-tool store --label="GitHub Token" service github user "$USER"

Why Device Flow is the best auth method for AI Agents​

I was actually solving another problem when I wrote this article: an AI agent runs on a remote server, I talk to it via phone IM. The agent needs GitHub API access to manage repos, create PRs, handle issues — but how do you give it credentials securely?

The most intuitive approach is sending the Token through the IM chat. It's also the most dangerous one.

IM Token path:
  You → [ IM Server ] → [ Chat History ] → [ Agent Context ]
                                                ↓
                                          Every layer sees your Token

Once the Token enters the chat, the IM server has it, your local chat history has it, and the agent's message context has it. And Tokens don't expire on their own — obtain it once, use it forever.

Device Flow solves this differently: your machine never touches the Token.

1. The agent prints a verification code (BFEE-895F) in the chat
2. You open github.com/login/device — GitHub's official auth page, not a link the agent gave you
3. Enter the code and authorize on GitHub's page
4. The Token goes directly from GitHub's server to the agent (server-to-server)

Device Flow path:
  Agent prints code → you see it
        ↓
  You open github.com/login/device → enter code → complete OAuth
        ↓
  Token goes from GitHub to agent (server-to-server, no middle layers)

Your IM only ever sees an 8-character verification code (15-minute validity, single-use). The Token never passes through your chat history.

Looking back, if your agent needs remote auth — Device Flow is about the only way to keep secrets out of your chat logs.

🥚 Easter egg​

If you frequently set up GitHub auth on remote servers, here's a script that does the whole thing in one command — download gh + authenticate + configure git user:

# remote-gh-setup.sh
# Run on the remote server: curl -fsSL https://gist.github.com/binggg/xxx/remote-gh-setup.sh | bash
# Then open https://github.com/login/device on your own machine and enter the code

set -e

# 1. Install gh to ~/bin
mkdir -p ~/bin
curl -fsSL https://github.com/cli/cli/releases/latest/download/gh_*_linux_amd64.tar.gz \
  | tar -xz -C /tmp
cp /tmp/gh_*/bin/gh ~/bin/
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/bin:$PATH"

# 2. Start Device Flow auth
gh auth login --web --git-protocol https

# 3. Configure git user
gh api user --jq '.login' | xargs -I{} git config --global user.name "{}"
gh api user --jq '.email // .login + "@users.noreply.github.com"' | xargs -I{} git config --global user.email "{}"

echo "✅ Done! Logged in as $(gh api user --jq '.login')"

This script covers the whole pipeline from my previous article. If you've run into environmental constraints I haven't encountered, drop a comment.

How does your remote agent handle auth? DIY Token setup or Device Flow? Comments below 👇

Based on GitHub CLI v2.62.0, RFC 8628 (published August 2019), and one real deployment verification.

This article covers two things:

1. Making AI-generated code actually deployable — AI writes demo-quality code, full of security holes. The root cause: AI doesn't understand production environments.
2. Fixing "AI has Skills but won't use them" — activation rates can be as low as 20%. Here's how we pushed that to 84%.

Vibe Coding's "Localhost Comfort Zone"​

Everyone's enjoying Vibe Coding. AI whips up a beautiful UI on localhost in minutes. But the magic dies the moment you try to deploy.

AI's code logic is reasonable, but it can't sense the real production environment. The result: code that looks right but can't survive outside your laptop.

The longest distance in software is from localhost to production. AI fills the code gap, but not the infrastructure gap.

What Are Agent Skills?​

Skills were introduced by Anthropic in October 2025 for Claude Code. They're a packaging format for instructions, scripts, and resources — domain expertise bundled as skill packs.

my-skill/
├── SKILL.md          # Core: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: reference docs
└── assets/           # Optional: templates, resources

Think of AI as a brilliant intern. Skills are the standard operating procedure manual. They don't change the AI's intelligence, but they inject procedural knowledge — how things are actually done in your specific environment.

Agent Skills became an open standard in December 2025. Claude, Cursor, VS Code, GitHub Copilot, and OpenCode all support it.

Progressive Loading​

Skills use progressive disclosure for context efficiency:

1. Discovery: Agent loads only name + description of each Skill
2. Activation: When a task matches, the full SKILL.md is loaded
3. Execution: Agent follows instructions, loading scripts on demand

Teams are already pushing this forward. Vercel released react-best-practices Skills to fix AI's React code quality. Remotion shipped video production Skills. All solving the same problem: give AI domain-specific engineering intuition.

The Hard Truth: Why AI Ignores Skills​

You configured Skills. AI ignores them. This was the most frustrating part, and it comes down to two deep architectural issues:

Attention Dilution: In the Transformer architecture, every token competes for attention weight. The deeper your conversation goes, the more weight your business requirements get — and the Skill instructions in the background get drowned out.

Inference Laziness: Calling a Skill is a tool-use operation. The model does a cost-benefit analysis: if it thinks its training data can produce "reasonably correct" code, it will skip the external tool to save inference resources.

The result: Without intervention, AI's active Skill invocation rate hovers around 20%. It would rather "blindly guess" than read the manual.

3 Solutions That Actually Work​

1. First-Line Injection (Crude but Effective)​

Start every prompt with this mantra:

You MUST read the guideline skill FIRST when working with this project.

Principle: Primacy effect. The model naturally pays more attention to the beginning of the input sequence. This forced injection reliably raises activation rates.

2. Project-Level Rules (CLAUDE.md)​

Create CLAUDE.md or AGENT.md with binding rules:

# Project Workflow

0. You MUST read the guideline skill FIRST when working with this project.
1. Evaluate: Before writing code, list available Skills.
2. Commit: State which Skill you need and why.
3. Execute: Never skip rules to write code directly.

This saves you from adding the mantra every time. But it's not bulletproof — as conversation context grows, AI may still ignore the rules.

3. Forced Eval Hook (The Heavy Lifter)​

If the first two are "asking nicely," this is physical enforcement.

Scott Spence discovered the most effective method: use your editor's hook mechanism. Configure .claude/settings.json to intercept every query and force the AI to write an evaluation report before any code:

• What Skills are available?
• Does this task need them? Why?

Here's the trick: once the AI has committed in writing to using a tool, it follows through. The hook eliminates the "I'll just wing it" shortcut.

Result: Skill activation jumps from 20% to 84%.

Architecture Lesson: 1 Guideline + N Independent Skills​

The biggest problem I encountered: AI can't distinguish environments. It confuses Web, Mini Program, and Node.js APIs.

The fix: instead of one monolithic "super skill," use 1 guideline + N environment-specific skills.

Solving Semantic Contamination​

Web, Mini Program, and Node.js SDKs have nearly identical method names. Put everything in one Skill, and AI will use the wrong syntax for the wrong platform.

Solution: split by platform. A guideline Skill routes AI to the right sub-skill based on project detection. Search space shrinks by 90%, reasoning accuracy jumps.

Enabling Targeted Intervention​

A massive skill pack dilutes attention. When you need AI to focus on one specific problem (e.g., "handle authentication"), the full manual becomes noise.

Independent plugins mean you can say: "Check the auth skill for phone number login." This is a direct intervention path — when AI is confused, pull up the right sub-skill and snap it back on track.

Closing Thoughts​

After months of wrestling with Skills, my biggest takeaway: AI programming productivity isn't about how brilliant the generated code is — it's about how much engineering constraint you can apply.

The core: turn tacit knowledge into procedural knowledge. Today's agents are brilliant interns with zero respect for production reality. Skills give them engineered muscle memory — years of hard-won experience encoded as precondition checks.

The shift: agents need environment awareness. The next frontier isn't better reasoning — it's infrastructure perception. Skills guard the floor, platforms enable the ceiling.

Determinism is the only metric that matters. Don't expect AI to become "perfect" automatically. Use engineering to make it "predictable." AI provides the logical ceiling. Engineering constraints guard the delivery floor.

If you're working with Skills, the most valuable thing you can do: measure whether your AI is actually using them. A 20% baseline is not shameful — but not knowing that number is.

I spent months experimenting with prompts, stripping back parameters, testing different style combinations. After a lot of trial and error, I found the core principle: less is more, add texture, flatten, desaturate.

These three style recipes are the ones that worked best in practice. Just append the prompt suffix to your base prompt and you're good to go.

Why Do AI Images Look "Oily"?​

You've probably noticed it too: AI-generated images that look technically "perfect" but have an uncanny "plastic" quality.

This "AI sheen" typically comes from:

• Overdone lighting and shadows — too dramatic, too deliberate
• Perfection in every pixel — lacking the imperfections of real art
• High-saturation colors — unnaturally vibrant
• 3D render vibes — looks like a game engine output, not human-made art

A Common Example​

Say you need an illustration for a "reading" theme. Default AI prompts might give you something like this:

What's wrong:

• Lighting is overly dramatic (movie poster style)
• Too much detail in every corner
• Strong 3D render feel
• Looks "fake" — no human touch

The fix is simple: subtract detail, add texture, flatten, desaturate.

Below are 3 ready-to-use style recipes using the same "reading" theme:

Style 1: Minimal Vector Flat​

Best for: Tech blogs, professional content, product introductions

The safest, most modern choice. Removes all unnecessary dimensionality — clean, simple, professional.

Looks like: Notion illustrations, Apple website graphics, corporate UI design.

Prompt Suffix:

flat vector illustration, minimal style, corporate memphis, simple shapes, 2D, white background, wide margins, clean lines, matte finish, low saturation, soft pastel colors, no shading, Behance style --ar 16:9

Example — same "reading" theme with flat style:

Compared to oily version: No 3D render feel, no dramatic lighting, clean and professional.

Style 2: Hand-drawn Crayon / Watercolor​

Best for: Lifestyle content, book notes, personal stories

Simulates real art materials (crayons, pencils, watercolors) to introduce intentional "imperfections" — textures that eliminate the AI plastic smoothness.

Looks like: Children's book illustrations — rough edges, warm tones, not-quite-perfect but incredibly approachable.

Prompt Suffix:

hand-drawn sketch, crayon texture, watercolor style, children's book illustration, rough edges, textured paper, visible brush strokes, warm tones, cozy atmosphere, simple composition, cute and friendly --ar 16:9

Example:

Compared to oily version: Real textures and brush strokes, warm tones, looks genuinely hand-drawn.

Style 3: Risograph (Screen Print)​

Best for: Opinion pieces, creative writing, artistic content

The ultimate anti-AI weapon. Risograph style forces limited color palettes and grain, making images look like vintage print — sophisticated and zero AI sheen.

Looks like: Indie magazine illustrations, art posters — grainy, 2-3 color separation, slightly misaligned layers.

Prompt Suffix:

Risograph style, grain and noise, screen print texture, limited color palette (blue and orange), halftone pattern, abstract minimalism, vintage aesthetic, matte paper texture, high contrast, flat illustration --ar 16:9

Example:

Compared to oily version: Grain and print texture, limited color palette feels more artistic, zero 3D render plastic feel.

Quick Reference: Anti-AI Magic Words​

Must-have texture words​

• Matte (removes reflections)
• Grainy / Noise (adds realism)
• Textured paper (physical feel)

Lighting control​

• Flat lighting (avoid dramatic shadows)
• Soft shadows (gentle transitions)
• Natural light (real-world feel)

Negative prompts (tell AI what NOT to do)​

photorealistic, 3d render, octane render, unreal engine, shiny, glossy, reflection, hyper detailed, neon lights, cyberpunk, plastic looking, oily skin, complex background

Simply put: tell AI "don't make it look too real, too 3D, too shiny, or too complex."

Summary: 5 Anti-Oily Principles​

Making AI images look human-made is simple — make them look like they were drawn, not rendered.

1. ✅ Add texture — paper grain, canvas, noise
2. ✅ Subtract detail — leave some "imperfections"
3. ✅ Desaturate — muted colors are more friendly
4. ✅ Flatten — 2D beats 3D for authenticity
5. ✅ Matte finish — remove highlights and reflections

Remember: imperfection is realism, and realism is the most friendly.

This is the pain point for many non-technical people using AI to code:

• Debug hell: page shows something wrong, but no idea which layer is the issue (frontend? backend? deployment?)
• Can't ask the right question: don't know how to describe the problem so AI understands and gives accurate answers
• Unclear learning path: know you need some basics, but don't know where to start or what's enough

Today I'll share a systematic approach — from foundational concepts to debugging techniques to backend solutions — to take you from "able to generate apps" to "able to build real, usable apps."

The real problem: why is debugging so hard?​

The issue you're facing is really two sides of the same coin: can't debug, don't know what to ask.

Because:

1. Don't know which layer failed: frontend? backend? deployment?
2. Don't know how to describe the problem: in a way AI can understand your situation
3. Don't know how to learn: maybe you know some debugging methods, but not systematically

Core issue: lack of systematic foundational concepts makes it impossible to accurately diagnose and describe problems.

Solution 1: Learn the fundamentals systematically​

This is the most critical step. Many people jump straight into AI coding without understanding the basics, then when something breaks, they don't even know what to ask.

Why learn fundamentals?​

You don't need to become an expert, but you need to understand:

1. Frontend vs Backend: what users see vs what processes data
2. Request vs Response: your browser asks a server for data, the server sends it back
3. Local vs Production: running on your machine vs running on a server

Without these concepts, you can't even describe what went wrong.

What to do​

1. Open the Frontend Roadmap​

Visit developer-roadmap — not to learn everything, but to see the big picture.

• Scan through it. Don't try to understand everything.
• Ask AI to explain concepts you don't get.
• Focus on: HTML/CSS/JavaScript/how browsers work

2. Use AI to understand concepts​

Don't understand what an HTTP request is? Ask AI:

"Explain what an HTTP request is in the simplest terms, using a restaurant analogy"

AI will connect it to your experience and give you the clearest explanation.

3. Learn by doing​

• Don't wait until you've learned everything
• Look things up when you hit a problem
• Let projects drive your learning

Core concepts (frontend stage)​

1. HTML Structure: page skeleton, tag semantics
2. CSS Styling: colors, layout, responsive design
3. JavaScript Behavior: interaction, data requests
4. Browser DevTools: your best debugging friend, shows errors and network requests
5. Console Errors: understanding error messages
6. Network Requests: how frontend talks to backend

Why this works​

Once you understand these fundamentals, you can:

• Describe problems accurately: "My frontend sends a request and the backend returns a 500 error"
• Understand AI's solutions: "AI says to add CORS config on the backend — I understand this is a cross-origin issue"
• Judge which solution fits: instead of letting AI give you N options and guessing which is right

Solution 2: Master debugging systematically​

With the fundamentals down, next is debugging.

The debugging system​

1. Check the console​

Press F12 or right-click → Inspect → Console

The console shows red error messages. This is your primary debugging entry point.

Common errors:

• Uncaught ReferenceError: xxx is not defined — a variable wasn't declared
• Cannot read properties of undefined — trying to access a property of undefined
• NetworkError — network request failed

2. Screenshot feedback​

When you hit a problem, send a screenshot + the console error together to AI.

Good question:

"My page doesn't respond after clicking the login button. Console shows 'Uncaught TypeError: Cannot read properties of null (reading 'addEventListener')'. What's wrong?"

Bad question:

"My page is broken. Help."

3. Systematic debug flow​

1. Observe: what happened? Screenshot + describe
2. Check console: press F12, look for red errors in Console
3. Copy the error: paste the console error message
4. Provide context: tell AI what you were doing, what you expected, what actually happened
5. Fix iteratively: follow AI's suggestions, one step at a time

Solution 3: Backend — the easy way​

Frontend done? Next is the backend.

The backend wall​

Many people nail the frontend but hit a wall with backend:

• Don't know MySQL/MongoDB
• Don't know how to write APIs
• Don't know how to deploy a server

The easier path: BaaS (Backend as a Service)​

What is BaaS?

BaaS wraps backend capabilities into simple APIs:

Most of the backend features you need are already built. Just use them.

Going further: AI-powered backend​

If BaaS isn't enough, there's a newer option: the MCP protocol.

MCP (Model Context Protocol) lets AI call cloud services directly. Just tell AI what you need, and it handles everything automatically.

Bonus: Designer-to-developer fast track​

If you're a designer looking to build real apps with AI, your path is different from a complete beginner's.

Design thinking vs programming thinking​

Your advantages:

• Understand user experience — you know what makes a good interface
• Have design standards — you won't produce "AI-looking" interfaces
• Understand interaction logic — you know user flows

What to add:

• How designs translate to code
• How data flows through an app
• How to debug and troubleshoot

Fast-track approach​

1. Leverage your design strengths​

• Feed your design specs directly to AI
• Take screenshots of your designs and ask AI to generate the corresponding code
• Your user perspective is a massive advantage

2. Focus on programming logic​

• Conditionals: if/else
• Loops: for/forEach
• Event handling: click, input, submit
• Data requests: fetch/axios

These are the keys to understanding AI-generated code.

3. Project-driven learning​

Suggested project path:

1. Personal portfolio site: showcase your design work
2. Interactive prototype: turn designs into clickable pages
3. Small utility app: a tool that solves a real problem

Summary​

Vibe Coding isn't a myth — but you need the right approach:

1. Learn fundamentals systematically — use developer-roadmap + AI to understand frontend basics
2. Master debugging systematically — screenshot feedback, console errors, full context
3. Backend the easy way — BaaS reduces the backend barrier

Most importantly: don't rush. Get the frontend fundamentals solid first. Learn concepts systematically, master debugging methods, then level up.

For designers transitioning to code: leverage your design strengths, focus on programming logic, learn through real projects, and build debugging habits.

Glossary​

The code runs. The features are there. But somehow... it's not usable.

Not a technical issue. Something else.

A typical scenario​

A friend excitedly sends me a link: "Look what I built with AI — three hours!"

I open it:

• There's a page: rounded cards, gradient buttons, purple color scheme — that unmistakable AI look
• The login button does nothing
• The data is all hardcoded placeholder values
• Only runs on his machine

I ask: "How do users access this?"

He pauses: "...I hadn't thought that far."

This isn't an isolated case. Most AI-built projects I've seen hit the same wall: the gap between demo and product.

The five pitfalls of vibe coding​

Looking closely at these projects, the problems boil down to five:

1. Requirements are a mystery​

"Build me a task management app" — that's what most people tell AI.

The problem: AI doesn't know:

• Should tasks have priorities?
• Multi-user or single-user?
• Local storage or cloud?
• Should it have notifications?

AI can only guess. If it guesses right, lucky. If wrong, you rework.

Root cause: no Spec mindset. Fuzzy requirements, and even the smartest AI can't fix that.

2. UI looks fake​

Why does AI-generated UI always have that unmistakable "AI look"?

• Too many rounded corners, too large
• Gradients everywhere
• Purple + blue color scheme on repeat
• Cookie-cutter layouts

It's not that AI can't design — you didn't tell it what good design looks like.

Root cause: no design specs. AI is just imitating the "average" it's seen.

3. The backend is empty​

However pretty the frontend page, clicking the login button does nothing.

Because:

• No user system
• No database
• No API endpoints
• No server

Many people think AI coding means making frontend pages. But for a usable product, backend is the bigger part.

Root cause: don't understand architecture choices. Don't know what tech stack to use, so just skip it.

4. Deployment is a black art​

Code is written. Now what?

• How to buy a domain?
• How to set up HTTPS?
• Which server to choose?
• How to deploy the database?

For someone without ops experience, every single one of these is a roadblock.

Root cause: don't understand deployment. Running code locally and shipping a product are two different things.

5. One line change breaks everything​

You finally got it running. Want to add a small feature.

Change one line. Everything breaks.

AI-generated code is often "disposable" — it runs, but can't be modified. Because:

• No modularity
• No type checking
• No tests
• Hardcoded values everywhere

Root cause: no engineering mindset. Code is written for machines to execute, not for humans to maintain.

How to break through?​

With the problems analyzed, the path forward is clear. Here are five concrete methods:

Method 1: Spec first, code second​

I wrote about the Kiro Spec workflow before. The core idea:

Vibe coding's biggest problem: it turns development into "gambling" instead of "controlled engineering."

The solution: before asking AI to write code, have it clarify requirements. Specifically, generate three files:

1. requirements.md — spec document (user stories + acceptance criteria using EARS syntax)
2. design.md — technical design (architecture, flow, caveats)
3. tasks.md — task list (for tracking)

This mirrors big tech's development process and agile breakdown — but Kiro integrates it deeply with AI IDEs, making it dramatically more practical.

What is EARS requirements syntax?

EARS (Easy Approach to Requirements Syntax) was originally used for jet engine control systems before being widely adopted in software engineering. It uses simple sentence patterns to constrain requirements and eliminate ambiguity:

Clear requirements = precise AI output.

How to use this with other AI IDEs?

Even without Kiro, you can replicate this workflow:

• Claude Code: create CLAUDE.md with Spec workflow rules
• Cursor: use .cursor/rules/project.mdc
• Augment: use .augment-guidelines

With this flow, AI stops being a "black box" that generates code, and becomes a partner — confirming at each step, progressing together.

Method 2: Use Skills to constrain AI's design output​

Don't let AI go wild. Give it a design system.

Introducing: Skills.

A Skill is a reusable prompt template that encapsulates domain-specific knowledge. For example, Anthropic's open-source frontend-design Skill specifically addresses the "AI look" problem:

With this Skill, AI-generated UI stops looking like "AI UI."

Method 3: Choose BaaS, don't build from scratch​

Backend is the biggest blocker for most people. But you don't need to build it yourself.

What is BaaS?

BaaS (Backend as a Service) wraps backend capabilities into APIs. Developers just call the SDK:

This is 10x simpler than building from scratch with Express/Nest.js.

Popular BaaS platforms:

• International: Supabase, Firebase
• China: CloudBase (Tencent Cloud)

The core BaaS philosophy: batteries included. When you create a project, database, auth, and storage are ready to go. No infrastructure to manage.

Method 4: Use platform hosting, skip the server​

Deployment doesn't need manual effort either.

Many platforms handle it for you:

If you're using a BaaS platform (like CloudBase), deployment is even simpler — static hosting for frontend, cloud functions for backend, and database, all in one platform. No need for multiple accounts.

Push your code. The platform handles the rest.

Method 5: Engineering mindset​

When asking AI to generate code, require:

This produces code you can actually maintain and iterate on.

My practice​

After all this theory, how do I actually do it?

After some experimentation, I've settled on a system that combines all five methods:

1. Spec workflow — Every new project starts with AI generating requirements.md → design.md → tasks.md. Clear requirements make everything downstream smoother.

2. Skill system — A curated set of design specs packaged as Skills. Call them whenever generating UI — no more AI look.

3. BaaS architecture — Backend on a cloud platform, no servers touched. Database, cloud functions, auth, file storage — all ready out of the box.

4. MCP protocol — MCP lets AI call cloud services directly. Creating databases, deploying functions, configuring domains — no manual operations needed.

This system is packaged as CloudBase AI Toolkit, open source on GitHub.

Final thoughts​

Vibe coding works — but only for demos.

Going from demo to product doesn't require a stronger AI. It requires engineering thinking:

• Clear requirements (Spec workflow)
• Design standards (Skill system)
• Sound architecture (BaaS)
• Intelligent development (MCP)
• Maintainable code (engineering)

AI is a tool. But tools need the right technique.

Just like owning a power drill doesn't make you a carpenter. The key is knowing how and where to use it.

Remember: AI doesn't replace humans. It makes humans more capable.

Have your own AI coding experiences? I'd love to hear about them.

Honestly, I'd been thinking about this too. Then I read Gojko Adzic's Specification by Example: How Successful Teams Deliver the Right Software, and it all clicked.

It turns out Kiro's Spec workflow is a perfect implementation of SBE (Specification by Example) methodology. Let me unpack this framework and fix your AI coding rework problem once and for all.

Why does your AI code always need rework?​

Sound familiar?

• You ask AI to build a login feature, it generates a registration page
• You request data export, AI gives you data import
• You want a simple API, AI builds a complex microservice architecture

What's the root cause?

It's not that AI isn't smart enough — it's that our requirements are too vague. It's like talking to a foreign friend: if you say "I want food," they might interpret it as "I want rice," "I want to go to a restaurant," or "I want to order delivery."

With AI coding, this ambiguity is amplified. AI can only guess what you want based on your description. When it guesses right, great. When it guesses wrong, you rework.

The traditional requirements dilemma​

Classic software engineering identified these problems long ago:

1. Ambiguous requirements: same spec, different interpretations
2. Late rework: discover misunderstandings after development
3. Stale documentation: specs can't keep up with changes
4. Communication overhead: endless requirement clarification

These problems are magnified in AI coding. When requirements are fuzzy, AI is fumbling in the dark, relying on "luck" to generate the right code.

Traditional software engineering had the answer all along​

Gojko Adzic's Specification by Example — SBE methodology — was built specifically to solve these problems.

SBE core principles​

1. Example-driven requirements​

Replace abstract descriptions with concrete, real examples:

❌ Abstract: The login feature must be secure and reliable ✅ Example-driven:

• Given the user enters the correct username and password
• When they click the login button
• Then the system shows the welcome page

2. Collaborative requirement clarification​

Emphasize cross-role collaboration by discussing examples together, avoiding "requirement silos." In AI coding, this is the human-AI collaboration process.

3. From requirements to executable tests​

Turn examples into automated test cases — "requirements as tests." This is the theoretical foundation of Spec mode's test generation from requirements.

4. Living documentation​

Example-driven requirements produce a dynamically updated documentation system that stays in sync as requirements change. This is exactly the continuously updated requirements.md and design.md in Spec mode.

SBE meets Spec: a perfect mapping​

Requirement clarification → requirements.md iteration​

SBE principle: Use concrete examples to clarify requirements, ensuring shared understanding.

Spec practice:

### Requirement 1 - User Login

**User Story:** As a user, I want to log in securely so I can access my personal data.

#### Acceptance Criteria
1. When the user enters correct credentials, the system shall display the welcome page
2. When the user enters an incorrect password, the system shall show an error message
3. When the user enters wrong credentials 3 times, the system shall lock the account for 30 minutes

Technical design → design.md collaboration​

SBE principle: Avoid technical pitfalls by focusing on business functionality.

Spec practice:

## Technical Design

### Architecture
- Frontend: React + TypeScript
- Backend: Node.js + Express
- Database: MongoDB
- Auth: JWT Token

Test-driven → requirements-based test generation​

SBE principle: Requirements are tests. Ensure implementation meets expectations.

Spec practice:

// Auto-generated test cases from requirements.md
describe('User Login', () => {
  test('successful login with correct password', async () => {
    const response = await login('user@example.com', 'correctPassword');
    expect(response.status).toBe(200);
    expect(response.data.message).toBe('Welcome page');
  });
});

Hands-on: SBE in AI coding​

What I learned from practice​

After applying this across multiple projects, I found SBE methodology genuinely effective in AI coding:

1. Requirement iteration is the most important thing​

Key finding: Continuously iterating and clarifying requirements.md and design.md is the heart of the process.

Real case:

• In the CloudBase-AI-ToolKit project, every new feature uses the Spec approach
• After iterative refinement of requirements.md, requirement clarity improved by 80%
• Rework rate dropped from 60% to 15%

2. Generate test cases from requirements​

Key finding: Test cases generated from requirements.md make AI coding verifiable.

3. Apply to existing projects too​

Key finding: Spec mode isn't just for greenfield projects — it works just as well on existing codebases.

Granularity best practices​

On the question of how to split: here's my experience:

Split by feature module​

specs/
├── user-management/
│   ├── requirements.md
│   ├── design.md
│   └── tasks.md
├── file-upload/
│   ├── requirements.md
│   ├── design.md
│   └── tasks.md
└── data-export/
    ├── requirements.md
    ├── design.md
    └── tasks.md

Split by iteration​

specs/
├── v1.0-basic-features/
├── v1.1-advanced-features/
└── v1.2-optimization/

Split by complexity​

• Simple features: single spec file
• Medium features: dedicated spec folder
• Complex features: multiple related spec folders

How good is SBE methodology, really?​

At this point you might ask: "Is this methodology really that effective? Isn't it too complex?"

Honestly, I had the same concern at first. But practice proved SBE methodology delivers:

Why is SBE so effective?​

1. Clear requirements: concrete examples beat abstract descriptions every time
2. Less rework: clear specs produce higher quality code
3. Better collaboration: shared understanding reduces communication overhead
4. Living docs: stays fresh as requirements evolve

When to use it​

Good fit:

• ✅ Complex, multi-module projects
• ✅ Team collaboration needing unified standards
• ✅ High quality requirements with traceability

Less suitable:

• ❌ Quick prototypes to validate ideas
• ❌ Personal projects with simple features
• ❌ Extremely time-constrained projects

Summary: From "hope it works" to "engineered certainty"​

SBE methodology provides a battle-tested theoretical foundation and practical framework for AI coding. Through example-driven requirements, collaborative clarification, test-driven development, and living documentation, we can make AI coding more controllable, efficient, and reliable.

Remember: AI doesn't replace humans — it frees humans to focus on decisions and direction, leaving the tedious details to AI.

That way, your AI coding stops being a "hope it works" gamble and becomes true engineered certainty.

Let's talk:

1. What development approach are you using?
2. Do you think Spec mode would work for your projects?
3. Share your AI coding experiences below!

Slot-machine vibe coding — is it really reliable?​

Ever had this experience? You type a vague requirement into an AI IDE, hit "generate," and wait expectantly for AI to produce a perfect program? The result feels like pulling the lever on a slot machine — sometimes you hit a small jackpot, but most of the time you get nothing.

Vibe coding is like a slot machine:

Slot machine: buy tokens, pull the lever, occasionally win big. More often it's "try again." The house always wins in the end.

Vibe coding: buy Tokens, write vague prompts, hit "generate." Sometimes you get perfect code, sometimes a mess. AI encourages you to "try again." You console yourself with "this time I'll fix the bug." But the model vendor always wins in the end. Occasionally you feel like you came out ahead — only to realize later you spent more time than it was worth.

Vibe coding's biggest problem: it turns development into "gambling" instead of "controlled engineering."

Typical vibe coding flow​

Yellow = human operation, Blue = AI output, Red = undesirable result.

Is there a better way? — How traditional development works​

Traditional software engineering emphasizes requirement clarification, technical design, task breakdown, and traceability. This approach may seem "slow," but it keeps projects moving steadily, enables review, and supports collaboration.

Kiro AI IDE has packaged this process into a Spec workflow — making AI coding as reliable as an engineer.

Traditional development flow​

This flow emphasizes requirement review and iterative feedback — the closed-loop continuous improvement of traditional software engineering.

What makes Kiro's Spec workflow so good?​

Kiro is AWS's AI IDE. Beyond free access to Claude 4, its biggest highlight is the Spec workflow:

• Every project has 3 core files:
  1. requirements.md — spec document (user stories + acceptance criteria with EARS syntax)
  2. design.md — technical design (architecture, flow, caveats)
  3. tasks.md — task list (trackable todo list)

What is EARS syntax?​

EARS (Easy Approach to Requirements Syntax) was originally developed for jet engine control systems before being widely adopted in software engineering. It uses simple sentence patterns to constrain requirements and eliminate ambiguity.

Example: When the user clicks "mute," the system shall suppress all audio output.

References: EARS Syntax Guide | v0.dev Cheat Sheet

You can run Spec workflow with Claude Code too! (with a worked example)​

Even without Kiro, you can replicate this workflow with any AI IDE. Using Claude Code as an example, the process is remarkably smooth:

1. Create a CLAUDE.md in your project Write the following prompt template into CLAUDE.md as your AI collaboration "job description":

# CLAUDE.md

You are a professional AI programming assistant. Follow the Spec workflow strictly:
1. Clarify requirements and output requirements.md using EARS syntax.
2. Design technical solution and output design.md (architecture, tech choices, APIs, testing strategy).
3. Break down tasks and output tasks.md as an actionable todo list.
4. Help write and test code according to the task list, saving artifacts to output/.
5. Critical: confirm each step with me before proceeding to the next.

2. Launch Claude Code, enter your raw requirements Just type your idea or user story into the chat. Claude reads CLAUDE.md and starts clarifying requirements with you.

3. After confirmation, Claude outputs requirements.md Claude uses EARS syntax to structure requirements and generates a standards-compliant requirements.md. You can add or modify at any point — Claude stays aligned with you.

4. Technical design After requirements are confirmed, Claude automatically moves to the design.md phase. Includes architecture, tech choices, APIs, testing strategy, etc.

5. Task breakdown Claude generates tasks.md from design.md, breaking the solution into executable items.

6. Step-by-step implementation and review Claude helps implement code and tests according to tasks.md, saving all artifacts to an output/ directory. You only participate in key review checkpoints: requirements, design, acceptance.

Recommended CLAUDE.md prompt: "You are a professional AI programming assistant. Follow the Spec workflow strictly, confirming each step with me before proceeding."

This way, even without Kiro, you can replicate the Spec workflow with Claude Code — making AI coding efficient, controllable, and reviewable.

Vibe coding vs Spec workflow comparison​

Yellow = human review, Blue = AI output, Red = bad outcome, Green = good outcome, Gray = group.

Claude Code Spec workflow — conversation example​

**User**: I want to build a tool that "automatically organizes meeting minutes." Can you help plan it?

**Claude** (reads CLAUDE.md and responds automatically):
Of course! We'll follow the standard Spec workflow. First, I'll help clarify requirements and output requirements.md. What input methods do you need? For example: voice, text, file upload?

**User**: Mainly uploading audio recordings — preferably supporting multiple audio formats.

**Claude**:
Got it. Any requirements for output format? Plain text, Markdown, Word documents?

**User**: Markdown and Word export would be ideal.

**Claude**:
Confirmed. Here's the requirements.md draft using EARS syntax:

---

# requirements.md

## User Story
As a frequent meeting attendee, I want to upload meeting recordings and get structured meeting minutes automatically, with export to Markdown or Word, to save organization time.

## Acceptance Criteria
1. When the user uploads an audio file, the system shall support common audio formats (mp3, wav, m4a).
2. When audio upload completes, the system shall automatically transcribe the audio and extract key points.
3. When the user clicks export, the system shall support Markdown and Word document export.

---

Please confirm the requirements. After confirmation, I'll move to the technical design phase.

**User**: Confirmed.

**Claude**:
Proceeding to design.md:

---

# design.md

## Architecture Overview
- Frontend: file upload, progress display, export button
- Backend: audio-to-text (ASR service), key point extraction (LLM), format conversion
- Storage: temporary file storage

## Tech Stack
- Frontend: React
- Backend: Node.js + OpenAI/Claude API
- ASR: Whisper API
- Document export: jsdocx, markdown-it

## Flow
1. User uploads audio
2. Backend transcribes to text
3. LLM extracts key points
4. Frontend displays and supports export

## Security
- Files stored temporarily, auto-deleted after processing

---

Please confirm the design. After confirmation, I'll break down the task list.

**User**: Confirmed.

**Claude**:
Here's tasks.md:

---

# tasks.md

- [ ] Build frontend upload page
- [ ] Implement audio file upload API
- [ ] Integrate ASR service for audio transcription
- [ ] Call LLM for key point extraction
- [ ] Implement Markdown/Word export
- [ ] Integration testing
- [ ] Documentation and acceptance

---

Please confirm the task list. After confirmation, I'll help implement each task step by step.

CloudBase AI Toolkit: one-stop Spec workflow replication​

If you want a more turnkey experience, try CloudBase AI Toolkit:

• Supports multiple AI IDEs
• Built-in Spec workflow templates
• One-click generation, deployment, and hosting — no ops needed

Human-AI collaboration is the real answer​

In the Spec workflow, AI handles:

• Vague requirements → clarified specs
• Technical design docs
• Task breakdown
• Code implementation
• Acceptance testing

Humans only need to:

• Input requirements
• Review requirements / design / schedule / tests

This gives you the best of both worlds: AI's efficiency and human engineering quality.

Standard software engineering flow​

Yellow = human review, Blue = engineering activity (AI + human), Green = high-quality result.

Summary: faster, more reliable, more trustworthy AI coding​

The Spec workflow transforms AI coding from "gambling" into "a repeatable process." The experience and judgment of human engineers, combined with AI's efficient execution — that's how you truly accelerate development, improve quality, and keep things reviewable.

Remember: AI doesn't replace humans. It makes humans more capable.