Skip to content

PROJECT_PLAN.md

Latest commit

 

History

History
340 lines (264 loc) · 12.5 KB

PROJECT_PLAN.md

File metadata and controls

340 lines (264 loc) · 12.5 KB

AI Development Guide - Project Plan

Status: Phase 1 Complete - In Progress Last Updated: 2025-11-10 Goal: Create a comprehensive, language-agnostic repository for AI-assisted development best practices

Project Vision

A professional, open-source repository that provides:

  • Language-agnostic core principles for AI-assisted development
  • Stack-specific implementation guides (starting with Python/FastAPI)
  • General AI tool guidance with Claude-specific sections where relevant
  • Practical templates and checklists for developers and reviewers
  • Framework for future expansion (more stacks, code examples, workflows)

Current State

Existing Files

  • AI_DEVELOPMENT_GUIDE.md (24.5 KB) - Comprehensive guide covering philosophy, practices, deployment, anti-patterns, glossary
  • CLAUDE.md (2.6 KB) - Quick reference for Python/FastAPI project with Claude

Current Gaps

  • No README or navigation guide
  • No getting-started documentation
  • Python-specific content mixed with universal principles
  • No templates or practical examples
  • No clear structure for adding more programming stacks
  • Missing repository infrastructure (.gitignore, LICENSE, etc.)

Target Repository Structure

ai-development-guide/
├── README.md                          # Main navigation & project overview
├── AI_DEVELOPMENT_GUIDE.md            # Refactored to be language-agnostic
├── docs/
│   ├── getting-started/
│   │   ├── README.md                  # General onboarding
│   │   ├── for-ai-tools.md            # How any AI tool should use this
│   │   └── for-claude.md              # Claude Code specific guidance
│   ├── core-principles/
│   │   ├── empiricism.md              # Testing and validation requirements
│   │   ├── incrementalism.md          # Small, atomic changes
│   │   ├── testing.md                 # TDD with AI
│   │   └── human-ai-collaboration.md  # Roles and responsibilities
│   ├── guides/
│   │   ├── code-review.md             # How to review AI-generated code
│   │   ├── deployment.md              # Feature flags, rollback, monitoring
│   │   ├── testing-strategy.md        # TDD workflow with AI
│   │   └── incident-response.md       # Retrospectives and learning
│   ├── stacks/
│   │   └── python-fastapi/
│   │       ├── README.md              # Stack overview
│   │       ├── CLAUDE.md              # Quick reference (moved from root)
│   │       ├── conventions.md         # Python-specific patterns
│   │       ├── testing-guide.md       # pytest, fixtures, TDD examples
│   │       └── deployment-guide.md    # Docker, FastAPI specifics
│   ├── anti-patterns/
│   │   ├── README.md                  # Overview of common pitfalls
│   │   └── detection-guide.md         # How to spot and avoid issues
│   └── templates/
│       ├── pr-template.md
│       ├── review-checklist.md
│       ├── commit-messages.md
│       └── retrospective-template.md
├── .github/
│   └── pull_request_template.md
├── .gitignore
├── LICENSE                            # MIT or Apache 2.0
└── CHANGELOG.md

Implementation Roadmap

Phase 1: Core Restructuring

Goal: Establish foundation and make existing content language-agnostic

  • Create README.md - Main entry point explaining:

    • Project purpose and audience
    • How to navigate the documentation
    • How AI tools should use this repository
    • Link to getting started guides

  • Refactor AI_DEVELOPMENT_GUIDE.md:

    • Remove Python/FastAPI specific examples
    • Make all examples pseudocode or multi-language
    • Keep focus on universal principles
    • Update references to point to stack-specific guides

  • Move CLAUDE.md → docs/stacks/python-fastapi/CLAUDE.md

  • Create docs/stacks/python-fastapi/README.md:

    • Overview of Python/FastAPI stack guidance
    • Links to conventions, testing, deployment guides
    • How to use with Claude Code

Phase 2: Getting Started Documentation

Goal: Provide clear onboarding for developers and AI tools

  • Create docs/getting-started/README.md:

    • Quick orientation for new developers
    • Which documents to read for which scenarios
    • How to adopt these practices in your project

  • Create docs/getting-started/for-ai-tools.md:

    • How AI coding assistants should read and apply these docs
    • Order of operations when helping with a task
    • Universal guidance for any AI tool

  • Create docs/getting-started/for-claude.md:

    • Claude Code specific features and workflows
    • File reference syntax
    • Tool usage patterns
    • How to read CLAUDE.md quick references

Phase 3: Core Principles Extraction

Goal: Break down monolithic guide into focused, digestible documents

  • Create docs/core-principles/empiricism.md:

    • Extract from AI_DEVELOPMENT_GUIDE.md
    • Expand on testing requirements
    • Add language-agnostic examples
    • Link to stack-specific testing guides

  • Create docs/core-principles/incrementalism.md:

    • What qualifies as "atomic"
    • PR size guidelines
    • Reversibility requirements

  • Create docs/core-principles/testing.md:

    • TDD workflow with AI
    • Test-first development
    • Framework for future code examples

  • Create docs/core-principles/human-ai-collaboration.md:

    • Division of responsibilities
    • Human-in-the-loop requirements
    • Accountability and ownership

Phase 4: Practical Guides

Goal: Provide task-specific, actionable guidance

  • Create docs/guides/code-review.md:

    • Expand checklist from AI_DEVELOPMENT_GUIDE.md
    • Step-by-step review process
    • What to look for in AI-generated code
    • Red flags and rejection criteria

  • Create docs/guides/deployment.md:

    • Feature flags and experimentation
    • Rollback strategies
    • Monitoring AI-generated code
    • Canary releases and blue-green deployments

  • Create docs/guides/testing-strategy.md:

    • TDD with AI workflow
    • Test design considerations
    • Framework for adding code examples later
    • Integration vs unit testing

  • Create docs/guides/incident-response.md:

    • Blameless retrospectives
    • Root cause analysis for AI-generated issues
    • Learning and improvement process

Phase 5: Anti-Patterns & Templates

Goal: Consolidate pitfalls and provide reusable resources

  • Create docs/anti-patterns/README.md:

    • Consolidate from AI_DEVELOPMENT_GUIDE.md
    • Organize by category
    • Link to detection guide

  • Create docs/anti-patterns/detection-guide.md:

    • How to spot common issues
    • Automated detection strategies
    • Code review focus areas

  • Create docs/templates/pr-template.md:

    • Structure for AI-assisted PRs
    • Required sections
    • Examples

  • Create docs/templates/review-checklist.md:

    • Comprehensive checklist for reviewers
    • Categorized by concern (security, correctness, maintainability)

  • Create docs/templates/commit-messages.md:

    • Format and conventions
    • How to document AI assistance
    • Examples

  • Create docs/templates/retrospective-template.md:

    • Blameless incident review structure
    • Questions to ask
    • Action item tracking

Phase 6: Infrastructure & Polish

Goal: Professional repository setup

  • Create .gitignore:

    • Standard patterns for documentation repos
    • IDE files, OS files, etc.

  • Create LICENSE:

    • MIT or Apache 2.0 (to be decided)
    • Standard open source license

  • Create CHANGELOG.md:

    • Version history
    • Track major documentation updates

  • Create .github/pull_request_template.md:

    • GitHub integration
    • Enforce documentation standards

  • Final review and polish:

    • Consistent formatting across all files
    • Working internal links
    • Table of contents where needed
    • Spell check and grammar review

Content Strategy

Language-Agnostic Core

  • Philosophy and principles apply to any programming language
  • Examples in pseudocode or conceptual descriptions
  • When showing code, provide examples in 2-3 popular languages
  • Focus on concepts: modularity, coupling, testing, not syntax

Stack-Specific Guides

  • Python/FastAPI as first complete implementation
  • Clear structure allows adding: Node.js/Express, Rust/Axum, Go, etc.
  • Each stack has consistent structure:
    • README.md (overview)
    • conventions.md (language/framework patterns)
    • testing-guide.md (framework-specific testing)
    • deployment-guide.md (stack-specific deployment)
    • Quick reference for AI tools (like CLAUDE.md)

AI Tool Guidance

  • General instructions work for any AI coding assistant
  • Separate Claude-specific sections clearly marked
  • Universal concepts: TDD, code review, incrementalism
  • Tool-specific: file references, workflow patterns, UI features

Key Design Decisions

Decided

  • Language-agnostic core: Principles apply universally, examples removed or generalized
  • Stack-specific guides: Start with Python/FastAPI, structure allows expansion
  • AI tool neutral + Claude sections: Works for any AI tool, with Claude-specific guidance
  • Open source: MIT or Apache 2.0 license for public use
  • Code examples later: Framework in place for TDD guide and examples, to be added after structure is complete

To Be Decided

  • Exact open source license (MIT vs Apache 2.0)
  • Contribution guidelines for community additions
  • How to handle stack-specific guide requests (process for adding new stacks)
  • Whether to include GitHub Actions / CI examples

Success Criteria

This project will be considered successful when:

  1. Navigation is clear: Any developer can find relevant guidance within 2 clicks
  2. AI tools can use it: Clear instructions for how AI assistants should read and apply docs
  3. Principles are universal: Core concepts work for any programming language
  4. Stacks are extensible: Easy to add new language/framework guides
  5. Templates are actionable: Developers can copy/paste and customize templates
  6. Open source ready: Professional structure, licensing, documentation suitable for public GitHub repo

Future Expansion Ideas

Not part of initial implementation, but documented for future consideration:

  • Code examples in stack guides (especially TDD workflows)
  • Video walkthroughs or tutorials
  • GitHub Actions / CI/CD pipeline examples
  • More programming stacks (Node.js, Rust, Go, Java, etc.)
  • IDE integration guides (VS Code, JetBrains, etc.)
  • Metrics and success measurement guide
  • Advanced topics: microservices, distributed systems with AI
  • Community contribution guidelines
  • Case studies from real projects

Notes & Rationale

Why Language-Agnostic Core?

The fundamental principles of AI-assisted development (empiricism, incrementalism, human oversight, testing) apply regardless of programming language. Keeping the core universal makes the guide more valuable and widely applicable.

Why Stack-Specific Guides?

While principles are universal, practical application requires language/framework specific guidance. Developers need to see "here's exactly how to do TDD with pytest" or "here's how to structure FastAPI endpoints." Stack guides bridge the gap between principles and practice.

Why Separate AI Tool Guidance?

Most AI coding assistants (Claude, GitHub Copilot, Cursor, etc.) share common challenges and best practices. Keeping general guidance separate from Claude-specific features makes the repo useful to a broader audience while still providing specialized help for Claude Code users.

Why Templates?

Templates enforce best practices and reduce decision fatigue. A good PR template ensures developers document their AI usage, testing, and rationale consistently. Checklists catch common mistakes before they reach production.

Getting Started with This Plan

For immediate next steps:

  1. Phase 1 - Start with core restructuring to establish foundation
  2. Focus on README.md first - it's the entry point and will clarify scope
  3. Refactor AI_DEVELOPMENT_GUIDE.md to be language-agnostic before creating spin-off docs
  4. Move CLAUDE.md to stack directory to establish pattern

To resume this project later:

  1. Read this PROJECT_PLAN.md to understand vision and structure
  2. Check off completed items in the roadmap
  3. Start with next uncompleted phase
  4. Refer to "Content Strategy" section for writing guidelines
  5. Update "Last Updated" date at top when making progress

Ready to implement? Start with Phase 1, Item 1: Creating README.md