$Wynn5a 技术博客 - AI编程与软件工程实践
~/blog/cursor-example
研发流程#AI#开发#Agentic-coding

使用 Cursor 进行遗留系统改造实例

背景#

你维护一个“类淘宝商城”的微服务系统：user-service、catalog-service、order-service、payment-service、auth-service 等。auth-service 已运行多年，存在典型遗留问题：

  • 认证逻辑混杂（历史自研 token / session / 旧 SSO 适配散落），难以加新登录流程；缺少统一的协议抽象与清晰边界
  • 缺少“全链路验证信号”：本地测试不稳定、CI 只跑少量检查、上线主要靠人工观察
  • 工程规范与知识主要靠口口相传：新同事难以在 1–2 天内跑通本地环境；同类改造反复踩坑
  • 可观测性薄弱：缺少统一 trace/metrics 的信号闭环，回归问题定位慢

业务提出新需求：支持新的单点登录（SSO），例如基于 OAuth 2.0 / OIDC 的 Authorization Code Flow，并补齐安全与性能风险。OAuth 2.0 与 OIDC 的核心语义分别在 RFC 6749 与 OIDC Core 中定义。

目标与非目标#

目标（可验收）：

  • auth-service 支持 OIDC 登录与 token 交换/校验：
    • Web/APP 用户侧：OIDC Authorization Code Flow（带 PKCE，若适用）
    • 服务间调用：统一的内部 token（短 TTL + refresh 或者 mTLS + opaque token）
  • 工程化改造后，任何改动都能通过“一键信号”验证：
    • lint / typecheck/ test / integrationTest / contractTest / dockerBuild / k8sDeployDryRun
  • CI/CD 支持：构建、测试、镜像发布、部署到 staging、灰度到 prod、失败可回滚
  • 可观测性：至少包含 request 日志（结构化 + traceId）、关键业务/HTTP 指标、分布式追踪(Prometheus 以 pull 方式抓取 metrics、文本 exposition format）。

非目标（本例不展开，但预留扩展点）：

  • 全业务域重构（本例聚焦 auth-service）
  • 全量服务网格化（如 Istio）
  • 组织级身份治理（RBAC/ABAC/SCIM/审计）细节

目标架构概览与登录流程#

架构（示意）#

rendering diagram…

以上架构需额外强调两点：

  1. OIDC 是“对外身份认证”，内部服务间最好统一为可控的内部 token/信任体系；
  2. 观测信号（traces/metrics/logs）必须成为上线与回滚的依据

OIDC 核心流程（序列图）#

rendering diagram…

该流程在 OIDC Core 中被规范化（认证建立在 OAuth 2.0 之上）

用 Cursor 把“工程化改造”做成可复制流水线#

下面把 Cursor 的能力落到仓库结构、规则/命令/钩子/工具，让团队的改造不靠“每个人会用 AI”，而靠工程化资产

推荐仓库结构（monorepo 示意）#

plain
repo/ .cursor/ rules/ 00-project.mdc 10-auth-service.mdc 20-ci-cd.mdc 30-security.mdc commands/ design-doc-auth.md plan-migration.md run-auth-tests.md cut-canary-release.md rollback-prod.md hooks.json hooks/ format.sh verify.sh grind.ts mcp.json sandbox.json BUGBOT.md docs/ design/ adr/ runbooks/ services/ auth-service-node/ # Node/TS auth-service-java/ # Java/Spring k8s/ base/ auth-service/ deployment.yaml service.yaml hpa.yaml configmap.yaml rollouts/ # 选项B：Argo Rollouts auth-service-rollout.yaml .github/workflows/ # GitHub Actions

Cursor 规则体系（Rules）：把“项目常识”写进规则不会忘记#

Rules 是持久上下文，应用后会被注入模型上下文开头，Project 范围的 rules 存放在 .cursor/rules/ 且需进入版本管理系统

示例：.cursor/rules/00-project.mdc（基础、短、可维护）

markdown
--- description: "Project-wide engineering rules: commands, repo layout, definition of done" alwaysApply: true --- # Repo overview - This is a microservices repo. Services live under `services/*`. - Prefer small, reviewable commits. Never mix refactors + behavior changes in one commit. # Build & verify signals (must be runnable locally) - Node services: `pnpm -C services/<svc> lint && pnpm -C services/<svc> test` - Java services: `./mvnw -pl services/<svc> test` - Docker build: `docker build -f services/<svc>/Dockerfile .` - Kubernetes dry-run: `kubectl apply -k k8s/base/auth-service --dry-run=server` # Definition of done (DoD) for changes - Tests added/updated. - Observability: structured logs + trace correlation for new endpoints. - Rollout plan + rollback command documented in `docs/runbooks/`. # AI collaboration - For non-trivial changes, start with Plan Mode. Save plans to `.cursor/plans/`. - Always propose file-by-file diff and verification commands.

auth-service 专属规则可以用 globs 限定生效范围：

markdown
--- description: "Auth-service rules: OIDC, token boundary, security invariants" globs: "services/auth-service-*/**/*" alwaysApply: false --- # Security invariants - Never log raw tokens (id_token, access_token, refresh_token). - Validate issuer/audience per OIDC config. - Treat upstream OIDC outages as 5xx with retry/backoff; never fail open. # API conventions - Public endpoints: - GET /login, GET /callback, POST /token/exchange, GET /healthz, GET /readyz, GET /metrics - All responses include `x-request-id` (or trace id) for correlation. # Storage - Config must be injectable via env vars (no hardcoded secrets).

实操提示：建议“规则要精简”，只写关键命令/模式/约束；发现 Agent 反复犯同类错再加规则，避免过度配置。

Commands：把“重复流程”固化到命令中一键调用#

Commands 是可复用任务模板，存在 .cursor/commands，输入 / 即可触发；也支持团队在 Dashboard 分发 Team commands，十分适合大型团队多个项目的情况

示例：.cursor/commands/plan-migration.md（让每次改造都按同一节奏）

markdown
# Goal Create a migration plan for refactoring auth-service to OIDC with engineering hardening. # Steps 1) Inspect current auth flow and list entrypoints. 2) Ask up to 3 clarifying questions. 3) Produce a plan with: - file paths - incremental commits (max 5) - verification signals per commit - rollout & rollback strategy 4) Save the plan to `docs/design/auth-oidc-migration.md`.

示例：.cursor/commands/run-auth-tests.md（统一验证信号）

markdown
# Run auth-service verification signals - For Node: `pnpm -C services/auth-service-node lint && pnpm -C services/auth-service-node test` - For Java: `./mvnw -pl services/auth-service-java test` If tests fail: - Summarize the failure - Propose a minimal fix - Re-run the smallest failing test first

Plan Mode：对中大型改动强制“先计划后执行”#

Plan Mode 会先研究代码库、提问澄清、生成带文件路径与引用的实施计划，你确认后才开始写代码，并且可“保存到 workspace”做团队文档

建议的 Plan Prompt（可直接用 Cursor 的 Plan 模式）：

为 auth-service 引入 OIDC 登录与 token 交换，并完成工程化改造（CI、测试、可观测性、灰度与回滚）。先阅读代码库现状并提出最多 3 个澄清问题，然后输出分阶段计划：每个阶段给出变更文件、提交拆分、验证命令、回滚方式。计划保存到 .cursor/plans/auth-oidc.md 并在 docs/design/ 输出一份相同任务步骤且更详细可执行的设计文档”

Hooks：把“验证闭环”变成自动机制#

Hooks 允许你在 agent loop 的阶段前后运行脚本（JSON over stdio），可以观察、阻断或修改行为

目标：让 Agent 不止“写完代码就结束”，而是“写完 → 跑信号 → 不通过就迭代（最多 N 次）

示例直接采用官方 cookbook 的 “Run until tests pass” 模式：.cursor/hooks.json 配合脚本返回 followup_message 驱动下一轮

json
{ "version": 1, "hooks": { "stop": [ { "command": "bun run .cursor/hooks/grind.ts" } ] } }

对遗留系统改造，这类闭环能显著降低“看起来对、实际没跑过”的风险；同时把迭代上限限制住，防止 agent 无限循环

Terminal sandbox 与 sandbox.json：安全地让 Agent 跑命令#

Cursor 的 terminal 执行带 sandbox 能力：网络默认受限，可通过 .cursor/sandbox.json 配置允许域名与读写路径；并存在强保护路径（例如 .cursor/*.json、.git/config 等仍受保护）

这对“遗留系统改造”非常关键，因为你可能希望 Agent 能跑测试/拉依赖/构建镜像，但不希望它误删文件、访问敏感路径或乱连内网，构建一个 terminal 的沙盒环境就等于是加了一层防火墙

MCP：把 Jira/GitHub/数据库/观测系统接进来#

Cursor 支持通过 mcp.json 连接外部工具；手动安装时可在项目级 .cursor/mcp.json 或全局 ~/.cursor/mcp.json 配置，两者会合并（同名 server 项目级优先）

示例：**.cursor/mcp.json（最小可用）

json
{ "mcpServers": { "github": { "command": "docker", "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "SECRET" } }, "jira": { "command": "npx", "args": ["-y", "@acme/jira-mcp-server@latest"], "env": { "JIRA_TOKEN": "SECRET,TOO", "JIRA_BASE_URL": "https://jira.example.com" } } } }

CI/CD 与质量门禁#

本节给出 GitHub Actions 与两套运行时（Node/Java）组合，你可按现状选择；关键是 CI 里的信号要和本地一致，并把 Cursor 的能力纳入 Code Review/环境修复/文档更新等非编码环节

统一的“构建与验证命令”约定#

建议在仓库根部提供一个最薄的 Makefile 或 taskfile 来统一入口（示例用 Makefile）：

makefile
# repo/Makefile .PHONY: auth-node auth-java docker-auth-node docker-auth-java auth-node: pnpm -C services/auth-service-node lint pnpm -C services/auth-service-node test auth-java: ./mvnw -pl services/auth-service-java test docker-auth-node: docker build -f services/auth-service-node/Dockerfile services/auth-service-node docker-auth-java: docker build -f services/auth-service-java/Dockerfile services/auth-service-java

把这些命令写入 .cursor/rules/00-project.mdc，能让 Agent 每次改动后自动选择正确命令验证（Rules 会注入上下文开头）

GitHub Actions（含镜像构建与可选 Cursor CLI Review）#

GitHub Actions 的 workflow 语法由 GitHub 官方文档定义

镜像构建缓存细节可参考 Docker 官方 GitHub Actions cache management

示例：.github/workflows/auth-ci.yml

yaml
name: auth-service CI on: pull_request: paths: - "services/auth-service-*/**" - ".cursor/**" - ".github/workflows/**" push: branches: [main] jobs: test-node: runs-on: ubuntu-latest if: ${{ hashFiles('services/auth-service-node/package.json') != '' }} steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v4 with: { version: 9 } - uses: actions/setup-node@v4 with: node-version: "20" cache: "pnpm" - run: pnpm -C services/auth-service-node install --frozen-lockfile - run: pnpm -C services/auth-service-node lint - run: pnpm -C services/auth-service-node test test-java: runs-on: ubuntu-latest if: ${{ hashFiles('services/auth-service-java/pom.xml') != '' }} steps: - uses: actions/checkout@v4 - uses: actions/setup-java@v4 with: distribution: "temurin" java-version: "21" cache: "maven" - run: ./mvnw -pl services/auth-service-java test docker-build: runs-on: ubuntu-latest needs: [test-node, test-java] steps: - uses: actions/checkout@v4 - uses: docker/setup-buildx-action@v3 - name: Build auth-service images (no push on PR) run: | if [ -d services/auth-service-node ]; then docker buildx build -f services/auth-service-node/Dockerfile services/auth-service-node --load fi if [ -d services/auth-service-java ]; then docker buildx build -f services/auth-service-java/Dockerfile services/auth-service-java --load fi cursor-review: runs-on: ubuntu-latest if: ${{ github.event_name == 'pull_request' }} permissions: contents: read pull-requests: write steps: - uses: actions/checkout@v4 with: fetch-depth: 0 ref: ${{ github.event.pull_request.head.sha }} - name: Install Cursor CLI run: | curl https://cursor.com/install -fsS | bash echo "$HOME/.cursor/bin" >> $GITHUB_PATH - name: Run Cursor CLI code review env: CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }} run: | agent -p --output-format text "Review this PR. Focus on auth security, OIDC correctness, and rollback safety. Suggest minimal fixes."
  • Cursor 官方提供“Cursor CLI 集成 GitHub Actions”与“Code Review cookbook”，包含 secret 配置与安装 CLI 的推荐步骤
  • CLI 支持非交互模式 p/--print 便于在 CI 中运行，但文档也提醒：非交互模式下 Agent 具备写权限，应配合 permissions/审批策略控制，权限的控制需要你特别注意

PR Review：Bugbot + .cursor/BUGBOT.md（强烈建议）#

Bugbot 支持用 .cursor/BUGBOT.md 提供项目级 Review 规则；Bugbot 会包含仓库根部的规则文件，并根据变更文件路径向上查找相关 .cursor/BUGBOT.md 作为上下文

示例：.cursor/BUGBOT.md

markdown
# Bugbot review guidelines for auth-service changes ## OIDC / OAuth correctness - Never accept tokens without validating issuer/audience. - Ensure state/nonce verification exists for auth code flow. - No token leakage in logs or error responses. ## Rollout safety - Any change to auth endpoints must include: - readiness/liveness impact analysis - rollback command in docs/runbooks/ - metrics / alerts touched ## DB migrations - Migrations must be backward compatible for at least one release. - No long-running locks without online strategy.

迁移清单、工作量评估与风险缓解#

分阶段迁移路线图（Mermaid Gantt）#

时间假设：小团队 2–4 人；若遗留复杂（强耦合、缺测试、频繁发版），工期会显著增加

rendering diagram…

迁移检查清单（含工作量与风险）#

下表按“能交付价值的最小闭环”排序：先让项目可以稳定验证与回滚，再谈更深的架构优化

步骤交付物预估工作量主要风险缓解策略
建立 Plan-first 流程.cursor/plans/auth-oidc.md + docs/design/...低计划空泛、不可执行强制写“文件路径+命令信号+回滚”并用 Plan Mode 生成可编辑计划；不符合就退回重写
建立 .cursor/rules 与 .cursor/commandsrules/commands 目录进 git低规则过长导致噪声遵循官方建议：只写关键命令/约束，避免堆砌长文档
配置 Hooks 验证闭环.cursor/hooks.json + scripts中循环不收敛/误触发限制最大迭代次数，明确“DONE”退出条件，必要时先在 staging 仓库试运行
配置 sandbox 与权限.cursor/sandbox.json；CLI permissions中过宽权限造成安全事故使用最小允许域名白名单；CLI permissions deny 危险命令；利用 Cursor 的安全控制与 hooks 作为硬边界
接入 MCP（Jira/GitHub/DB/观测）.cursor/mcp.json中凭证泄露/工具过多占上下文只配必要 server；敏感值用 env/secret；项目级优先生效；定期审计 mcp.json
引入 Bugbot 规则.cursor/BUGBOT.md低规则不准导致噪声先写 5–10 条关键检查；逐步迭代；关注迁移/安全/回滚类高价值规则
OIDC 功能实现新 endpoints + 配置 + token 策略高认证漏洞/回归影响全站以 RFC/Spec 为准（issuer/aud/state/nonce）；灰度发布；回滚演练；加强审计与可观测性
CI/CD 完整流水线Actions 或 GitLab CI 模板中CI 与本地不一致统一 Makefile/脚本入口；CI 仅调用这些入口；缓存与镜像构建遵循官方最佳实践
灰度与回滚机制K8s RollingUpdate 或 Argo Rollouts中低流量服务灰度信号不可靠RollingUpdate 作为保底；Argo canary 配 pause + 指标阈值 + 手动 promote/abort；回滚命令写入 runbook
可观测性落地OTel traces + Prometheus metrics + 日志中指标不对/无告警阈值遵循 OTel/Prometheus 规范与最佳实践：至少 http 请求量/错误率/延迟；以 rollout 指标作为晋级门槛

上线/回滚策略模板（两种部署选项）#

选项 A：Kubernetes Deployment + 原生回滚

  • Deployment 的 RollingUpdate 行为与“可回滚到旧 revision”的能力由 Kubernetes 文档定义
  • 回滚命令示例（写入 runbook）：
    • kubectl rollout status deployment/auth-service
    • kubectl rollout undo deployment/auth-service

选项 B：Argo Rollouts Canary（更适合高风险认证改造）

  • Canary steps 的 setWeight 与 pause 是 Argo Rollouts 的核心机制
  • 操作命令：
    • 观察：kubectl argo rollouts get rollout auth-service --watch
    • 推进：kubectl argo rollouts promote auth-service --full
    • 中止回滚：kubectl argo rollouts abort auth-service（会停止推进并恢复旧 RS 为 active；但 spec.template 仍指向新版本，需把 template 改回旧版本完成彻底回滚）