AI 协同开发实践：使用 OpenCode + OpenSpec 构建 Go 短域名服务

1
2

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

1

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

1
2
3
4
5
6
7
8

npm (适用于所有平台，需先安装Node.js)：
npm install -g opencode-ai

Homebrew (macOS/Linux)：
brew install sst/tap/opencode

Go (适用于Go开发者)：
go install github.com/sst/opencode@latest

1

opencode --version

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

your-project/
├── openspec/
│ ├── specs/ # 【真相来源】所有已完成的、当前系统的规范
│ │ └── [功能模块]/
│ │ └── spec.md
│ ├── changes/ # 【变更区】所有进行中的功能提案
│ │ └── [变更名称]/ # 例如 add-url-shorten
│ │ ├── proposal.md # 提案：为什么要做，做什么
│ │ ├── tasks.md # 任务：AI实施的详细清单
│ │ └── specs/ # 规范增量：本次变更要修改的规范文件
│ │ └── [功能模块]/
│ │ └── spec.md
│ ├── project.md # 项目上下文（技术栈、架构、规则等）
│ └── AGENTS.md # 指导AI如何与OpenSpec协同工作的指令

1

npm install -g @fission-ai/openspec@latest

1
2

cd your-go-project
openspec init

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

#创建项目目录
mkdir url-shortener
cd url-shortener

# 初始化Go模块
go mod init github.com/yourname/url-shortener

# 初始化OpenSpec (假设已全局安装)
openspec init
根据提示，选择你的AI助手，比如 'opencode'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

# URL Shortener Server

## Overview
This project provides a URL shortener backend service. It accepts long URLs, generates short codes, and redirects clients from short URLs to their original destinations.

## Goals
- Simple HTTP API for creating short URLs and resolving them.
- Reliable, low-latency redirects.
- Safe handling of invalid or expired short codes.

## Core Behavior
- Create a short code for a given URL.
- Resolve a short code to its original URL.
- Redirect clients to the original URL using standard HTTP redirects.

## Data Model (High Level)
- Short code
- Original URL
- Creation timestamp
- Optional expiration timestamp
- Optional metadata (e.g., creator, tags)

## API Surface (High Level)
- `POST /shorten` to create a short URL.
- `GET /{code}` to resolve and redirect.
- `GET /healthz` for health checks.

## Storage
- Persistent store for code-to-URL mappings.
- Unique index on short codes.

## Non-Goals
- User authentication and billing.
- Analytics dashboards.
- Custom domains (unless added later).

## Engineering Conventions
- Keep handlers small and focused.
- Validate inputs and normalize URLs.
- Prefer explicit error responses and status codes.
- Implementation uses Go with the Gin framework.
- Use in-memory storage for code-to-URL mappings.
- Add unit tests for important functions.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

/opsx:propose Create a URL Shortener Service in Golang.
Details:
- Endpoints: POST /shorten {url: string} → {short_url: string}
- GET /{short} → 301 redirect to original
- Storage: Redis if env REDIS_URL set, else in-memory sync.Map
- Short code: Base62 encoded (6-8 chars, unique)
- Validation: URL must be valid HTTP(S)
- Rate limit: Basic (optional, 10/min per IP)
- Errors: JSON {error: msg}
- Tests: Cover shorten/resolve/HTTP
Generate tasks.md with 8-12 steps: setup deps, core logic, handlers, tests, Docker.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

➜  changes tree -L 4
.
├── archive
└── url-shortener-service
    ├── design.md
    ├── proposal.md
    ├── specs
    │   ├── shorten-create
    │   │   └── spec.md
    │   ├── shorten-rate-limit
    │   │   └── spec.md
    │   ├── shorten-resolve
    │   │   └── spec.md
    │   ├── shorten-storage
    │   │   └── spec.md
    │   └── shorten-testing
    │       └── spec.md
    └── tasks.md

1

/opsx:apply url-shortener-service all tasks

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

➜  url-shortener tree -L 4
.
├── Dockerfile
├── README.md
├── cmd
│   └── server
│       └── main.go
├── docker-compose.yml
├── go.mod
├── go.sum
├── internal
│   ├── config
│   │   └── config.go
│   ├── httpapi
│   │   ├── handlers.go
│   │   ├── handlers_test.go
│   │   └── middleware.go
│   ├── ratelimit
│   │   └── ratelimit.go
│   ├── shortener
│   │   ├── shortener.go
│   │   └── shortener_test.go
│   └── storage
│       ├── memory.go
│       ├── memory_test.go
│       ├── redis.go
│       └── storage.go

1

write a README.md, give some curl shell command to show how to use it. And write how to go test

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 运行服务
go run cmd/server/main.go
# 在另一个终端测试API
curl -X POST "http://localhost:8080/shorten" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://kubernetes.io/docs/concepts/overview/"}'
{"short_url":"http://localhost:8080/kaQax2J"}%

curl -v "http://localhost:8080/kaQax2J"
> GET /kaQax2J HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.88.1
> Accept: */*
>
< HTTP/1.1 301 Moved Permanently
< Content-Type: text/html; charset=utf-8
< Location: https://kubernetes.io/docs/concepts/overview/
< Date: Wed, 04 Mar 2026 06:32:42 GMT
< Content-Length: 80
<
<a href="https://kubernetes.io/docs/concepts/overview/">Moved Permanently</a>.

* Connection #0 to host localhost left intact

1
2
3
4
5
6
7

➜  url-shortener go test ./...
?       url-shortener/cmd/server        [no test files]
?       url-shortener/internal/config   [no test files]
ok      url-shortener/internal/httpapi  0.011s
?       url-shortener/internal/ratelimit        [no test files]
ok      url-shortener/internal/shortener        0.006s
ok      url-shortener/internal/storage  0.006s

1

/opsx:archive url-shortener-service

1
2
3
4
5
6
7
8
9

Delta specs exist for this change, but there are no corresponding main specs in `openspec/specs/`. I can sync these new specs into main now, or archive without syncing.
1.
Sync now (Recommended)
Create main specs from the delta specs before archiving.
2.
Archive without syncing
Archive now and leave main specs unchanged.
3.
Type your own answer

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

➜  url-shortener tree -L 4
.
├── Dockerfile
├── README.md
├── cmd
│   └── server
│       └── main.go
├── docker-compose.yml
├── go.mod
├── go.sum
├── internal
│   ├── config
│   │   └── config.go
│   ├── httpapi
│   │   ├── handlers.go
│   │   ├── handlers_test.go
│   │   └── middleware.go
│   ├── ratelimit
│   │   └── ratelimit.go
│   ├── shortener
│   │   ├── shortener.go
│   │   └── shortener_test.go
│   └── storage
│       ├── memory.go
│       ├── memory_test.go
│       ├── redis.go
│       └── storage.go
└── openspec
    ├── changes
    │   └── archive
    │       └── 2026-03-04-url-shortener-service
    ├── config.yaml
    ├── project.md
    └── specs
        ├── shorten-create
        │   └── spec.md
        ├── shorten-rate-limit
        │   └── spec.md
        ├── shorten-resolve
        │   └── spec.md
        ├── shorten-storage
        │   └── spec.md
        └── shorten-testing
            └── spec.md