AGENTS.md — Vue 3 Frontend Development

AGENTS.md --- Vue 3 Frontend Development

进行前端功能开发时候请遵守以下规范，严禁自由发挥

1. Project Overview

Framework: Vue 3 (Composition API preferred)
Build Tool: Vite
Language: TypeScript (strict mode)
State Management: Pinia
Routing: Vue Router (history mode)
HTTP Client: Axios (with interceptors)
UI Library: $Specify if any, e.g., Element Plus, Vuetify, or Tailwind CSS$
Testing: Vitest + Vue Test Utils
Linting/Formatting: ESLint + Prettier

2. Directory Structure

复制代码

src/
├── assets/          # Static assets (images, fonts, global styles)
├── components/      # Reusable Vue components (dumb/presentational)
│   └── common/      # Very generic components (buttons, inputs)
├── composables/     # Vue Composition API reusable functions (useXxx)
├── layouts/         # Layout components (default, auth, etc.)
├── pages/           # Route-level page components
├── router/          # Vue Router configuration and route modules
├── stores/          # Pinia stores (split by domain)
├── types/           # TypeScript type definitions (interfaces, enums)
├── utils/           # Pure utility/helper functions
├── services/        # API service modules (calls to backend)
├── plugins/         # Vue plugins (e.g., global component registration)
├── App.vue          # Root component
└── main.ts          # Application entry point

3. Coding Standards

3.1. General

Use TypeScript for all .vue, .ts, and .js files.
Use ES modules (import/export).
Use 2-space indentation.
Use single quotes for strings unless escaping.
Add trailing commas in multi-line objects/arrays.
Filenames: kebab-case for all files (e.g., user-profile.vue, use-auth.ts).
Component names: PascalCase in JS/TS and kebab-case in templates.

3.2. Vue Components

Prefer Composition API with <script setup> syntax.
Use defineProps and defineEmits with TypeScript types.
Keep components single‑responsibility; split into smaller components when needed.
Use scoped styles or CSS modules; avoid global styles unless necessary.
Order within <script setup>:
1. Props & Emits
2. Reactive state (ref, reactive)
3. Computed properties
4. Watchers
5. Lifecycle hooks
6. Methods/functions
7. Exposed bindings (defineExpose)

Example:

vue 复制代码

<script setup lang="ts">
// Props
const props = defineProps<{ userId: string }>()

// Emits
const emit = defineEmits<{ (e: 'update', id: string): void }>()

// Reactive
const user = ref<User | null>(null)

// Computed
const displayName = computed(() => user.value?.name ?? 'Anonymous')

// Lifecycle
onMounted(async () => {
  user.value = await fetchUser(props.userId)
})

// Methods
async function fetchUser(id: string): Promise<User> { /* ... */ }
</script>

3.3. State Management (Pinia)

Define stores using the Options Store or Setup Store pattern (Setup preferred for complex logic).
Name stores with use prefix and Store suffix, e.g., useUserStore.
Keep stores flat ; use store.$patch for batch updates.
Use actions for async operations and complex mutations.
Use getters for derived state.

3.4. Routing

Define routes in router/index.ts with lazy-loading (() => import('...')).
Use route guards (e.g., beforeEach) for authentication/permissions.
Prefer named routes over hardcoded paths.
Use route params typed via defineProps in page components.

4. Environment Variables

Use .env files (.env.development, .env.production) with VITE_ prefix for Vite.
Access via import.meta.env.VITE_*.
Example:
- VITE_API_BASE_URL=https://api.example.com
- VITE_APP_TITLE=My App

5. API Communication

Centralise HTTP calls in services/ modules.
Use Axios with interceptors for:
- Adding auth tokens
- Global error handling
- Request/response logging (dev only)
Define typed request/response interfaces in types/.

Example service:

typescript 复制代码

// services/userService.ts
import api from './api'
import type { User } from '@/types/user'

export const userService = {
  async getProfile(id: string): Promise<User> {
    const { data } = await api.get(`/users/${id}`)
    return data
  }
}

6. Styling

Global styles : placed in src/assets/styles/ (e.g., reset.css, variables.css).
Component styles : use <style scoped> with CSS variables for theming.
If using a utility-first framework (e.g., Tailwind), configure it in tailwind.config.js.
Use CSS Modules if needed: <style module>.

7. Testing

Write unit tests with Vitest alongside source files (or in __tests__ folders).
Use Vue Test Utils for component testing.
Test file naming: *.spec.ts or *.test.ts.
Example test:

typescript 复制代码

import { mount } from '@vue/test-utils'
import MyComponent from './MyComponent.vue'

describe('MyComponent', () => {
  it('renders correctly', () => {
    const wrapper = mount(MyComponent, { props: { msg: 'Hello' } })
    expect(wrapper.text()).toContain('Hello')
  })
})

8. Common Commands

Command	Description
`pnpm install` (or npm)	Install dependencies
`pnpm dev`	Start development server
`pnpm build`	Build for production
`pnpm preview`	Preview production build locally
`pnpm test`	Run unit tests
`pnpm test:watch`	Run tests in watch mode
`pnpm lint`	Run ESLint
`pnpm format`	Run Prettier

9. Git Workflow

Branch naming: feature/xxx, fix/xxx, chore/xxx.
Commit messages: follow Conventional Commits.
Pull requests require at least one approval before merging.

10. Deployment

Build output is generated in the dist/ folder.
Deploy to static hosting (e.g., Vercel, Netlify, or an S3 bucket).
For SSR, use Nuxt 3 (if applicable) -- but this project uses Vite SPA.

11. Additional Conventions

Internationalization : if needed, use vue-i18n and store locale in Pinia.
Error boundaries : use error handling with Vue's onErrorCaptured.
Performance : use v-once for static content, v-memo for large lists.
Accessibility: use semantic HTML, ARIA attributes, and ensure keyboard navigation.

12. AI‑Specific Instructions

When generating or modifying code, please:

Always include TypeScript types.
Use Composition API with <script setup> unless explicitly instructed otherwise.
Prefer functional composition over classes.
Keep components under 300 lines; refactor when larger.
Write self‑documenting code; add JSDoc comments for complex logic.
Follow the existing import grouping: external libraries first, then internal modules.
When adding new dependencies, confirm they are compatible with Vue 3.

最后，再次说明进行前端功能开发时候请遵守以上规范，严禁自由发挥