项目：<产品名>¶

本文件是 Claude Code 的项目级约定，每次会话自动加载。保持精简（建议 ≤ 250 行），详细内容链接到 docs/。

一句话¶

<用一句话描述产品：为谁解决什么问题。>

当前阶段¶

<需求 / 设计 / 开发 / 测试 / 部署 / 线上验证>

技术栈¶

前端：Vue 3 + TypeScript + Vite + Pinia + Vue Router
后端：Go 1.23 + chi + pgx + sqlc
数据库：PostgreSQL 16
测试：go test / Vitest / Chrome MCP
部署：Docker + AWS ECS Fargate + RDS + S3/CloudFront

目录¶

backend/                 Go API
frontend/                Vue SPA
docs/00-discovery/       需求、用户故事、排期
docs/01-design/          技术设计、OpenAPI、schema、ADR
docs/02-ui/              UI 规格、设计 token、截图
docs/03-dev/reports/     每个功能一份实现报告
docs/04-qa/              E2E manifest、截图、Word 报告
docs/05-release/         发布记录
infra/                   IaC、部署配置
scripts/                 状态更新、报告生成、环境检查

常用命令¶

make dev            # 启动本地依赖（数据库等）
make dev-api        # 启动后端
make dev-web        # 启动前端
make test           # 单元 + 集成测试
make lint           # 格式 + 静态检查
make e2e            # 启动 Chrome 调试端点，按提示跑 E2E
make report STORY=US-004 ENV=dev   # 生成 Word 报告
make migrate-up     # 执行数据库迁移
make build          # 构建产物

如果命令不存在，先看 Makefile；不要猜。

核心契约（先读再写代码）¶

API：docs/01-design/api/openapi.yaml
数据库：docs/01-design/db/schema.sql
实现细节：docs/01-design/feature-implementation.md
文件所有权：docs/01-design/file-ownership.md
测试策略：docs/01-design/test-strategy.md

编码约定¶

通用¶

先读契约，再写实现；契约不一致时停止并提 CR。
不修改未授权文件。
所有新代码必须有测试。
不删除/跳过测试来让 CI 变绿。
不在日志/响应中输出密码、令牌、密钥、个人信息。
所有时间用 UTC 存储，前端按用户时区展示。
所有权限在后端校验。
所有错误使用统一错误码。
提交信息遵循 Conventional Commits，包含 Refs: US-xxx。

后端¶

分层：adapter → usecase → domain；domain 不依赖框架。
依赖启动时注入，禁止包级可变状态。
每请求独立 context + 超时。
每写请求一个事务。
SQL 用参数化查询（pgx/sqlc）。
错误用 domain.AppError，handler 集中映射。
日志用结构化字段：request_id, user_id, tenant_id。

前端¶

颜色/间距只用 CSS 变量，禁止魔法值。
页面必须处理 loading/empty/error/no-permission。
API 类型从 OpenAPI 生成，不手写重复类型。
统一使用 src/api/client.ts，不直接 fetch/axios。
组件分层：views → business components → ui。
关键元素加 data-testid。

禁止¶

不要改 migrations/ 中已上线的文件。
不要改共享文件（router.go、main.go、openapi.yaml、package.json 等），除非任务书授权。
不要绕过类型检查（any、@ts-ignore）。
不要在生产环境执行写操作。
不要提交 .env、密钥、Chrome profile。
不要用 git push --force 到共享分支。
不要自动解决合并冲突（先报告）。

完成定义（DoD）¶

一个用户故事完成，需要：

状态更新¶

python3 scripts/update_story_status.py \
  --file docs/00-discovery/user-story.csv \
  --story <US-xxx> \
  --status <status>

项目：<产品名>¶

一句话¶

当前阶段¶

技术栈¶

目录¶

常用命令¶

核心契约（先读再写代码）¶

编码约定¶

通用¶

后端¶

前端¶

禁止¶

完成定义（DoD）¶

状态更新¶

相关文档¶