Skip to content

README.md

Latest commit

 

History

History
328 lines (244 loc) · 9.37 KB

README.md

File metadata and controls

328 lines (244 loc) · 9.37 KB

DevLog AI Guidance System

This directory contains a comprehensive framework for AI-assisted development, ensuring consistency, quality, and adherence to best practices across the project.

📁 Directory Structure

.github/
├── README.md                    # This file
├── copilot-instructions.md      # Main AI architecture guide
├── GITHUB_AUTH_SETUP.md         # GitHub authentication setup
├── pr-template-commits.md       # PR description template
├── instructions/                # Scope-specific guidelines
│   ├── development-standards.instructions.md
│   ├── web-interface-guidelines.instructions.md
│   ├── github-issue.instructions.md
│   ├── github-release-notes.instructions.md
│   └── storybook.instructions.md
├── rules/                       # Architectural principles
│   ├── accessibility.md
│   ├── component-architecture.md
│   ├── react-19-compiler.md
│   ├── spec-driven-development.md
│   ├── supabase.md
│   ├── tailwind-v4.md
│   ├── three-js-react.md
│   └── web-performance.md
├── skills/                      # Executable workflows
│   ├── accessibility_audit/
│   ├── scaffold_component/
│   ├── vercel-react-best-practices/
│   └── workflows/
└── prompts/                     # Agent prompt templates
    └── create-pr.prompt.md

🎯 Three-Layer Framework

Layer 1: Instructions (Scope-Specific)

Files in instructions/ apply to specific file types or contexts using frontmatter:

---
applyTo: '**/*.tsx'
---

When these apply:

  • Automatically loaded by AI when working with matching files
  • Referenced in code reviews for specific file types
  • Used to enforce patterns on particular scopes

Key files:

  • development-standards.instructions.md - TypeScript/React standards, Airbnb style, APCA contrast
  • web-interface-guidelines.instructions.md - MUST/SHOULD/NEVER UI rules, accessibility (24px targets, keyboard)
  • github-issue.instructions.md - Issue template and format
  • github-release-notes.instructions.md - Release notes structure
  • storybook.instructions.md - Storybook usage patterns

Layer 2: Rules (Architectural Principles)

Files in rules/ define non-negotiable architectural patterns:

When to reference:

  • Making architectural decisions
  • Designing new features
  • Reviewing code structure
  • Setting up infrastructure

Key files:

  • component-architecture.md - Folder-per-component with named exports
  • spec-driven-development.md - Create SPEC.md before coding ("Zero Vibe Rule")
  • supabase.md - Database, auth, RLS, storage best practices
  • accessibility.md - WCAG compliance requirements
  • react-19-compiler.md - React 19 optimization patterns
  • web-performance.md - Performance optimization guidelines

Layer 3: Skills (Executable Workflows)

Files in skills/ provide step-by-step workflows:

When to use:

  • Creating new components
  • Running audits
  • Following complex procedures
  • Applying best practice patterns

Key skills:

scaffold_component/

Component creation workflow with SDD:

  1. Create SPEC.md with requirements
  2. Generate component structure
  3. Implement with tests
  4. Document in Storybook

accessibility_audit/

Comprehensive accessibility testing:

  • Keyboard navigation check
  • Screen reader compatibility
  • Color contrast validation
  • ARIA attributes review

vercel-react-best-practices/

45 performance rules across 8 categories:

  • Async (7 rules) - API routes, dependencies, parallel fetching, suspense
  • Bundle (6 rules) - Dynamic imports, barrel imports, tree shaking
  • Client (4 rules) - Event listeners, localStorage, SWR dedup
  • JS (11 rules) - Caching, batching, early exits
  • Rendering (8 rules) - SVG, hydration, transitions
  • Re-render (10 rules) - Memo, derived state, lazy init
  • Server (7 rules) - Auth, caching, serialization

🚀 How to Use This System

For Developers

Starting a New Feature

  1. Check Instructions

    • Read relevant instructions/ files for your file types
    • Example: Building a component? Read web-interface-guidelines.instructions.md

  2. Review Rules

    • Understand architectural constraints
    • Example: New component? Follow component-architecture.md folder structure

  3. Follow Skills

    • Use workflow templates
    • Example: Run scaffold_component/ to create proper structure

  4. Reference in PRs

    • Cite specific rules when reviewing
    • Link to guidance files in comments

Making Changes

# Before coding a component
cat .github/rules/component-architecture.md
cat .github/instructions/web-interface-guidelines.instructions.md

# During development
# Follow patterns in .github/skills/scaffold_component/

# Before PR
cat .github/pr-template-commits.md

For AI Assistants

The guidance system is automatically integrated into AI tools:

GitHub Copilot:

  • Reads copilot-instructions.md for architecture
  • Applies instructions/ files based on applyTo patterns
  • References rules/ for decision-making

Creating Features:

  1. Read relevant instructions/ and rules/
  2. Generate code following patterns
  3. Reference skills/ for workflows
  4. Use prompts/ for common tasks

Common Workflows

Creating a New Component

# 1. Review guidance
cat .github/rules/component-architecture.md
cat .github/rules/spec-driven-development.md

# 2. Create SPEC.md first (SDD)
# Document requirements, props, behavior

# 3. Scaffold component following folder pattern
mkdir src/components/MyComponent
touch src/components/MyComponent/{MyComponent.tsx,index.ts,SPEC.md}

# 4. Implement with accessibility in mind
cat .github/instructions/web-interface-guidelines.instructions.md

Running an Accessibility Audit

# Follow the checklist
cat .github/skills/accessibility_audit/SKILL.md

# Check key requirements:
# - 24px × 24px minimum hit targets
# - APCA contrast ≥60 (normal) / ≥45 (large)
# - Keyboard navigation functional
# - Screen reader labels present

Optimizing Performance

# Review best practices
cat .github/skills/vercel-react-best-practices/SKILL.md

# Check specific patterns
cat .github/skills/vercel-react-best-practices/rules/rerender-memo.md
cat .github/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md

📖 Key Concepts

Spec-Driven Development (SDD)

From rules/spec-driven-development.md:

Create SPEC.md BEFORE writing code. No exceptions.

The "Zero Vibe Rule": If you're coding based on vibes, stop and write the spec.

Template:

# Component/Feature Name

## Purpose
[Why this exists]

## Requirements
- [ ] Requirement 1
- [ ] Requirement 2

## API/Props
[Interface definition]

## Behavior
[How it works]

## Changelog
[Track changes to spec during implementation]

Folder-per-Component

From rules/component-architecture.md:

src/components/MyComponent/
├── MyComponent.tsx       # Implementation
├── MyComponent.test.tsx  # Tests
├── index.ts             # export { MyComponent } from './MyComponent'
└── SPEC.md              # Specification

Why: Encapsulation, discoverability, and maintainability.

Accessibility First

From instructions/web-interface-guidelines.instructions.md:

MUST:

  • Hit targets ≥24px × 24px
  • APCA contrast ≥60 (normal text)
  • Full keyboard navigation
  • Proper ARIA labels

SHOULD:

  • Focus indicators visible
  • Skip links for navigation
  • Semantic HTML

🔄 Updating the Guidance System

When to Update

  • New patterns emerge → Add to rules/
  • Common mistakes → Add to instructions/
  • Repeated workflows → Create in skills/
  • File type standards → Update instructions/ applyTo patterns

How to Update

  1. Create/edit file in appropriate directory
  2. Test with AI to verify it's followed correctly
  3. Document in this README if structural change
  4. Update copilot-instructions.md if architecture changes
  5. Commit with docs: prefix

File Naming

  • Instructions: topic.instructions.md
  • Rules: topic.md
  • Skills: skill-name/SKILL.md
  • Prompts: action-name.prompt.md

🛠️ Utilities

GitHub Authentication

See GITHUB_AUTH_SETUP.md for:

  • GitHub CLI setup
  • Personal access token generation
  • mcp_github tools configuration

PR Templates

Use pr-template-commits.md for consistent PR descriptions.

Prompts

Reusable AI prompts in prompts/:

  • create-pr.prompt.md - Automated PR creation from commits

📚 Additional Resources

💡 Philosophy

This guidance system embodies:

  1. Explicit over Implicit - Written standards beat tribal knowledge
  2. Automation over Documentation - Executable workflows beat manuals
  3. Consistency over Cleverness - Predictable patterns beat one-off solutions
  4. Accessibility First - Inclusive design is not optional
  5. Performance by Default - Optimization patterns built-in

Questions? See CONTRIBUTING.md or open a discussion.