ajy/AGENTS.md

Agent Guidelines

Project Overview

艾灸椅功能管理系统 — 智能艾灸设备的云端管理平台。

需求文档：需求材料/艾灸椅功能定义-最新.xlsx

AI 角色分工

本项目采用多角色协作模式，不同角色负责不同阶段：

角色定义

角色	职责	触发场景
需求工程师 (兼测评工程师)	需求分析、验收标准、测试用例设计	新功能规划、需求澄清
系统分析员	架构设计、技术方案、接口定义	技术选型、系统设计
开发人员	代码实现、单元测试、代码审查	具体编码任务

协作流程

需求阶段          设计阶段          开发阶段          验收阶段
    │                │                │                │
    ▼                ▼                ▼                ▼
┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│需求工程师│───▶│系统分析员│───▶│开发人员  │───▶│需求工程师│
│(测评)   │    │         │    │         │    │(测评)   │
└─────────┘    └─────────┘    └─────────┘    └─────────┘
    │                                              │
    │  1. 需求文档                                 │  4. 验收测试
    │  2. 验收标准                                 │
    │  3. 测试用例                                 │
    └──────────────────────────────────────────────┘

角色职责详解

需求工程师 (兼测评工程师)

需求职责：

• 分析 需求材料/艾灸椅功能定义-最新.xlsx 中的功能需求
• 将业务需求转化为用户故事和验收标准
• 澄清需求歧义，确认边界条件
• 输出：openspec/changes/{feature}/proposal.md

测评职责：

• 根据验收标准设计测试用例
• 定义测试场景（正常流、异常流、边界条件）
• 编写验收测试脚本
• 执行验收测试并签署通过/不通过
• 输出：tests/acceptance/{feature}.test.ts

工作产出：

需求阶段:
├── proposal.md      # 需求提案
├── acceptance-criteria.md  # 验收标准
└── test-cases.md    # 测试用例设计

验收阶段:
└── {feature}.test.ts  # 验收测试脚本

系统分析员

职责：

• 技术选型和架构设计
• 定义 API 接口规范
• 设计数据模型和数据库 schema
• 识别技术风险和依赖
• 输出：openspec/changes/{feature}/design.md

工作产出：

├── design.md        # 技术设计方案
├── api-spec.yaml    # API 接口定义
├── data-model.md    # 数据模型设计
└── tasks.md         # 开发任务拆解

开发人员

职责：

• 按设计文档实现功能代码
• 编写单元测试（TDD：先写测试再写代码）
• 代码自审和互审
• 修复 bug 和技术债务
• 输出：apps/{web,api}/src/

工作产出：

apps/
├── web/src/
│   ├── components/  # UI 组件
│   ├── pages/       # 页面
│   └── hooks/       # 自定义 hooks
└── api/src/
    ├── routes/      # API 路由
    ├── services/    # 业务逻辑
    └── models/      # 数据模型

角色切换规则

在对话中通过角色声明切换：

[需求工程师] 分析用户登录功能需求...
[系统分析员] 设计用户认证架构方案...
[开发人员] 实现登录 API 和前端表单...
[测评工程师] 执行登录功能验收测试...

默认角色：根据任务类型自动识别

• 需求澄清 → 需求工程师
• 架构讨论 → 系统分析员
• 代码实现 → 开发人员
• 测试验收 → 测评工程师（需求工程师兼任）

质量门禁

每个阶段必须满足以下条件才能进入下一阶段：

阶段	进入条件	输出物
需求 → 设计	需求文档已确认，验收标准已定义	proposal.md, acceptance-criteria.md
设计 → 开发	技术方案已评审，任务已拆解	design.md, tasks.md
开发 → 验收	单元测试通过，代码审查完成	源代码, 单元测试
验收 → 完成	验收测试通过，无阻塞性缺陷	验收测试报告

Build / Lint / Test Commands

None configured. This repo has no package.json, Makefile, pyproject.toml, or any build configuration.

When a project is added, document commands here. Common patterns:

# Node.js / npm
npm install          # install deps
npm run dev          # dev server
npm run build        # production build
npm test             # run all tests
npm test -- --testPathPattern=filename  # single test

# Python
pip install -r requirements.txt
pytest tests/test_file.py::TestClass::test_method  # single test
pytest -k test_name   # single test by name

# Go
go build ./...
go test -run TestName ./...

# Rust
cargo build
cargo test test_name

Code Style Guidelines

No code exists yet. When adding code, follow these defaults unless project-specific configs dictate otherwise:

Imports

• Group: stdlib → third-party → local
• Sort alphabetically within groups
• Use explicit imports, no wildcards

Formatting

• Match existing file indentation (2 or 4 spaces)
• Max line length: 80-120 chars
• Consistent line endings (CRLF on Windows, LF elsewhere)

Naming

• Files: kebab-case or PascalCase
• Classes: PascalCase (UserService)
• Functions/Vars: camelCase (getUserById)
• Constants: SCREAMING_SNAKE_CASE (MAX_RETRIES)
• Booleans: is/has/should prefix (isActive)

Error Handling

• Use specific error types, not generic
• Include context in error messages
• Never silently swallow errors

Types (if TypeScript)

• Explicit annotations on params and returns
• Avoid any — use unknown if truly unknown
• Enable strict mode

Working with This Repository

1. Read first — Always check existing files before editing
2. Understand domain — Review 需求材料/艾灸椅功能定义-最新.xlsx before implementing
3. Follow conventions — Match whatever pattern the added project uses
4. Test changes — Run appropriate tests when available
5. Commit responsibly — Atomic, focused commits with clear messages

Git Conventions

• Feature branches for new work
• Atomic commits with clear messages
• Run linters before committing (once configured)
• Review changes before pushing

Security

• Never commit secrets, API keys, or credentials
• Use environment variables for sensitive config
• Validate and sanitize all user inputs

Cursor / Copilot Rules

No Cursor rules (.cursorrules, .cursor/rules/) or Copilot instructions (.github/copilot-instructions.md) found.