diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9e6ef7d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,187 @@
+# Agent Instructions for Trace Frontend
+
+## Build & Development Commands
+
+### Development
+```bash
+pnpm dev                # Start dev server at http://localhost:5173
+```
+
+### Build
+```bash
+pnpm build              # Build for production (outputs to dist/)
+pnpm preview            # Preview production build
+```
+
+### Testing & Linting
+No test or lint commands are currently configured. When adding tests, use Vitest or Jest.
+
+## Project Overview
+
+This is a React 19 + TypeScript frontend for the Zhejiang Beifan Trace Management Platform (溯源管理平台). It provides:
+- Public query interface for serial number verification
+- Admin dashboard for QR code generation and company management
+- User authentication and profile management
+
+**Tech Stack**: React 19, TypeScript, Vite 7, Ant Design 6, React Router v7, Axios
+
+## Code Style Guidelines
+
+### File Organization
+```
+src/
+├── components/        # Reusable UI components (AdminLayout, etc.)
+├── pages/            # Page components (Login, Dashboard, etc.)
+├── services/         # API service layer (api.ts with domain-specific APIs)
+├── types/            # TypeScript type definitions (index.ts)
+├── hooks/            # Custom React hooks
+├── utils/            # Utility functions
+├── styles/           # Global CSS files
+├── assets/           # Static assets (images, etc.)
+├── App.tsx           # Main app with routes
+└── main.tsx          # Application entry point
+```
+
+### Imports
+- Use `@/` alias for src directory (configured in vite.config.ts and tsconfig.json)
+- Group imports: React/hooks first, then third-party libraries, then internal imports
+- Example:
+  ```tsx
+  import { useState } from 'react';
+  import { Form, Input, Button } from 'antd';
+  import { UserOutlined } from '@ant-design/icons';
+  import { useNavigate } from 'react-router-dom';
+  import { authApi } from '@/services/api';
+  import type { User } from '@/types';
+  ```
+
+### Naming Conventions
+- **Components**: PascalCase (e.g., `LoginPage`, `AdminLayout`)
+- **Functions/Methods**: camelCase (e.g., `handleLogin`, `loadStats`)
+- **Constants**: UPPER_SNAKE_CASE (e.g., `API_BASE_URL`)
+- **Types/Interfaces**: PascalCase (e.g., `User`, `Company`, `ApiResponse<T>`)
+- **Files**: PascalCase for components/pages, lowercase for services/utils
+
+### TypeScript
+- All new code must be TypeScript
+- Use `interface` for object shapes, `type` for unions/aliases
+- Explicit return types for API functions and handlers
+- Use `any` only as last resort - prefer `unknown` with type guards
+- Strict mode enabled: no unused locals, no unused parameters
+
+### Component Patterns
+- Use functional components with hooks
+- For pages: use `function PageName()` (not arrow functions)
+- For layout/reusable components: use `function ComponentName()`
+- Export with `export default ComponentName;`
+- Use Ant Design components via destructuring: `const { Button, Form } = antd;`
+
+### Error Handling
+- Use try-catch blocks for async operations
+- Display errors with Ant Design `message.error()`
+- API services throw errors with descriptive messages
+- Global axios interceptor handles 401 (auth) and 404 (not found) automatically
+
+### API Services
+- API calls organized by domain in `src/services/api.ts`:
+  - `authApi` - Authentication (login, logout, profile)
+  - `serialApi` - Serial number management
+  - `companyApi` - Company management
+  - `dashboardApi` - Dashboard statistics
+- Auth token automatically added via axios interceptor
+- All API calls return typed responses based on `src/types/index.ts`
+
+### Routing
+- Use React Router v7 with `<Routes>` and `<Route>` components
+- Protected routes wrapped with `<PrivateRoute>` component
+- Admin pages wrapped with `<AdminRoutes>` layout component
+- Use `useNavigate()` for programmatic navigation
+- Use `useLocation()` to get current path
+
+### State Management
+- Use React hooks (`useState`, `useEffect`) for local component state
+- Authentication state persisted in localStorage via authApi
+- No global state management library currently used
+
+### Styling
+- Global styles in `src/styles/global.css`
+- Component-specific CSS in co-located styles directory (e.g., `pages/styles/Login.css`)
+- Import component styles with relative path: `import './styles/PageName.css';`
+- Use Ant Design components for primary UI, custom CSS for layout specifics
+
+### Locale & Internationalization
+- Chinese (zh_CN) locale configured globally via `ConfigProvider` in main.tsx
+- All UI text should be in Chinese
+- Ant Design components automatically use Chinese locale
+
+## Key Patterns & Conventions
+
+### Page Component Structure
+```tsx
+function PageName() {
+  const [loading, setLoading] = useState(false);
+  const [data, setData] = useState<DataType | null>(null);
+
+  useEffect(() => {
+    loadData();
+  }, []);
+
+  const loadData = async () => {
+    setLoading(true);
+    try {
+      const result = await apiMethod();
+      setData(result);
+    } catch (error: any) {
+      message.error(error.message || '加载数据失败');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  if (loading) {
+    return <Spin size="large" />;
+  }
+
+  return <div>{/* JSX content */}</div>;
+}
+
+export default PageName;
+```
+
+### Route Guards
+- `<PrivateRoute />` - Redirects to /login if not authenticated
+- `<PublicRoute children={...} />` - Redirects to /admin/dashboard if authenticated
+- Use `<Outlet />` for nested routes
+
+### Environment Variables
+- Use Vite's `import.meta.env.VITE_*` pattern
+- Example: `const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || '/api';`
+- Define in `.env` file (not committed to git)
+
+## Notes for Agents
+
+1. **No tests configured**: When adding test frameworks, update AGENTS.md accordingly
+2. **No linter configured**: Consider adding ESLint and Prettier
+3. **Authentication flow**: Tokens stored in localStorage, added to requests via interceptor
+4. **API proxy**: /api requests proxied to http://localhost:3000 during dev (see vite.config.ts)
+5. **QR Code generation**: Uses `qrcode` library for generating QR codes for serial numbers
+6. **Admin Layout**: Uses Ant Design Layout with Sider navigation and Header
+7. **Type safety**: Always add types for new props, state, and API responses
+
+## Common Tasks
+
+### Add a new API endpoint
+1. Add interface to `src/types/index.ts`
+2. Add method to appropriate API object in `src/services/api.ts`
+3. Handle errors appropriately with descriptive messages
+
+### Add a new page
+1. Create component in `src/pages/PageName.tsx`
+2. Add CSS file in `src/pages/styles/PageName.css`
+3. Add route in `src/App.tsx`
+4. If admin page, wrap in `<AdminRoutes />` and add menu item in `AdminLayout.tsx`
+
+### Add a new component
+1. Create in `src/components/ComponentName.tsx`
+2. Add styles in `src/components/styles/ComponentName.css` if needed
+3. Import using `@/components/ComponentName`
\ No newline at end of file