zhaoguiyang.site/AGENTS.md

AGENTS.md

This file provides guidelines for AI agents operating in this repository.

Project Overview

This is a bilingual personal portfolio site built with Astro 5, React 19, and Tailwind CSS 4.

Current project capabilities from codebase:

• EN/ZH localized site with Astro i18n routing (en default, zh under /zh)
• Portfolio pages: home, projects, services, now, hire, about
• Blog system with posts, tag pages, and category pages in both locales
• React interactive islands for header/theme switch, typewriter effect, back-to-top, comments, and animations
• Waline comment integration (@waline/client) and Umami analytics script in production
• SEO/sitemap integration via @astrojs/sitemap

Package Manager Rule (Mandatory)

Use pnpm only for dependency and script commands.

• Always use pnpm commands in documentation, scripts, and instructions
• Do not use npm, yarn, or bun commands in this repo
• If existing text shows npm run ..., replace with pnpm ...

Examples:

pnpm install
pnpm dev
pnpm build
pnpm preview

Build Commands

# Install dependencies
pnpm install

# Development server
pnpm dev

# Build for production
pnpm build

# Preview production build locally
pnpm preview

No lint or test commands are configured. Run pnpm build to verify changes.

Code Style Guidelines

General Principles

• Write concise, self-documenting code
• Avoid unnecessary comments (only explain complex logic)
• Follow existing patterns in the codebase
• Prioritize readability over cleverness

Imports

• Use @/ alias for src imports (configured in tsconfig.json)
• Order imports: React → libraries → components → utilities
• Use named exports for components and utilities

// Good
import * as React from "react";
import { Slot } from "@radix-ui/react-slot";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";

// Avoid
import utils from '@/lib/utils';
import { useState, useEffect } from 'react';

TypeScript

• Use TypeScript for all new files (.ts, .tsx)
• Extend Astro strict TypeScript config
• Use explicit types for component props
• Avoid any, use unknown or specific types

// Good
interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>,
  VariantProps<typeof buttonVariants> {
  asChild?: boolean;
}

// Avoid
const handleClick = (e: any) => { ... }

Components

Astro Components (.astro):

• Use frontmatter fence --- at top
• Separate imports, props, and logic
• Use client:only="react" for React components needing browser APIs
• Use client:load for interactive components that should hydrate on load
• Static content should not have client directives

React Components (.tsx):

• Use React.forwardRef for components that need refs
• Use class-variance-authority (CVA) for component variants where applicable
• Use Radix UI primitives when available
• Prefer named exports (unless file already follows a default-export pattern)

Styling (Tailwind CSS)

• Use Tailwind utility classes as the primary styling approach
• Use cn() utility to merge classes with conditional logic
• Avoid inline style objects unless strictly necessary
• Dark mode styles should use dark: variants and existing tokens

i18n (Internationalization)

• All UI text must be in src/i18n/translations.ts (and related i18n helpers)
• Use translation helpers (useTranslations(lang))
• Avoid hardcoded strings in .astro and .tsx when user-facing text is localized
• Keep EN/ZH content parity for shared pages/components

Naming Conventions

• Components: PascalCase (e.g., GlassHeader)
• Files: kebab-case for Astro routes, PascalCase for React components
• Variables/functions: camelCase
• Constants: SCREAMING_SNAKE_CASE
• Types/Interfaces: PascalCase, with Props suffix for component props

Error Handling

• Use TypeScript types to prevent runtime errors
• Handle null/undefined explicitly
• Prefer optional chaining (?.) and nullish coalescing (??)
• Avoid broad try/catch unless handling known async boundaries

Astro-Specific Conventions

• Pages use file-based routing under src/pages/
• English routes are root-level; Chinese routes are under src/pages/zh/
• Blog content uses markdown posts in:
  • src/pages/blog/posts/
  • src/pages/zh/blog/posts/
• Layouts are in src/layouts/
• Reusable UI/components are in src/components/
• Data source modules are in src/lib/data/

Project Structure

src/
├── components/      # UI components (React & Astro)
│   ├── blog/        # Blog-specific components (meta, lists, comments)
│   ├── layout/      # Layout helper components (TOC, blog nav)
│   ├── markdown/    # Markdown rendering components
│   └── ui/          # Reusable UI primitives
├── layouts/         # Shared page layouts
├── pages/           # Routes (including blog and locale routes)
│   ├── blog/
│   └── zh/
├── lib/
│   ├── data/        # Personal info, projects, services
│   └── utils.ts
├── i18n/            # Locale constants, translation maps, helpers
├── styles/          # Global and integration styles
├── types/           # Type definitions
└── utils/           # Utility functions for blog and helpers

Important Notes

• This is a bilingual site (EN/ZH); maintain both locales
• Default language is English (defaultLang = 'en')
• Use Astro.currentLocale to detect language context
• Keep services semantics as capabilities/skill offerings
• Components depending on window, document, or localStorage must use proper client directives
• Preserve existing integrations: MDX, sitemap i18n, Waline comments, and analytics behavior