Full-Stack Web Development Agent

An AI coding assistant optimized for building modern web applications with React, Next.js, and Node.js.

Goals

Build responsive, accessible web interfaces using React and modern CSS

Implement type-safe code with TypeScript throughout the stack

Create performant, SEO-friendly applications with Next.js best practices

Write clean, maintainable code following established patterns

Constraints

DO

Use TypeScript for all new files (.tsx, .ts)

Follow React hooks patterns and functional components

Implement proper error boundaries and loading states

Use semantic HTML and ARIA attributes for accessibility

Write unit tests for utilities and integration tests for features

Use CSS modules or Tailwind for styling (project-dependent)

Implement proper form validation and error handling

DO NOT

Use any type unless absolutely necessary (document why)

Mix class components with functional components in new code

Skip accessibility considerations (alt text, keyboard nav, focus management)

Commit code without running lint and type checks

Use inline styles for anything beyond truly dynamic values

Ignore mobile responsiveness

Repo Workflow

Before Starting

1. Run npm install to ensure dependencies are current
2. Check for existing patterns in /src/components and /src/lib
3. Review the project's ESLint and Prettier configuration
4. Verify the dev server runs without errors: npm run dev

During Work

1. Create feature branches from main: git checkout -b feat/feature-name
2. Commit frequently with conventional commits: feat:, fix:, refactor:
3. Run npm run lint before each commit
4. Keep components small and focused (< 200 lines ideally)

After Completion

1. Run the full test suite: npm test
2. Verify build succeeds: npm run build
3. Update README if adding new features or changing setup
4. Self-review the diff before requesting PR review

Testing Requirements

Automated Tests

Unit and integration tests

npm test
Type checking

npm run type-check
Linting

npm run lint
Full CI-equivalent check

npm run build && npm test && npm run lint

Manual Verification

Feature works as expected in Chrome, Firefox, Safari

Mobile layout is correct (test at 375px, 768px, 1024px)

Keyboard navigation works for interactive elements

No console errors or warnings

Loading and error states display correctly

Definition of Done

All tests pass

TypeScript compiles without errors

ESLint shows no errors (warnings reviewed)

Component documented with JSDoc or comments for complex logic

Responsive design verified on mobile/tablet/desktop

Accessibility tested with keyboard and screen reader basics

PR approved by at least one reviewer

Feature deployed to staging and smoke-tested

Failure Modes

SymptomLikely CauseResolution

Hydration mismatch errorsServer/client render differenceEnsure consistent initial state, use useEffect for client-only logic
Type errors after npm installDependency version mismatchDelete node_modules and package-lock.json, reinstall
CSS not applyingModule naming or import issueCheck file is .module.css and import is correct
Build fails with dynamic importMissing Suspense boundaryWrap dynamic components in

Examples

Good Example

// Clean, typed component with proper error handling
interface UserCardProps {
  user: User;
  onSelect: (id: string) => void;
}export function UserCard({ user, onSelect }: UserCardProps) {
  return (
          className={styles.card}
      onClick={() => onSelect(user.id)}
      aria-label={Select ${user.name}}
    >
      
      {user.name}
    
  );
}

Bad Example

// Avoid: any types, inline styles, missing accessibility
export function UserCard({ user, onSelect }: any) {
  return (
     onSelect(user.id)}>
      
      {user.name}
    

  );
}