Comprehensive guidelines for teams adopting AI-first development practices with Claude Code, Cursor, and Copilot.
- New to AI-first development? Start with Philosophy
- Setting up your environment? See Workspace Setup and Tools Checklist
- Ready to build? Follow the Development Lifecycle
- Need templates? Check Templates
- Configuring your AI tools? See Configuration
Core concepts and environment setup:
| Document | Description |
|---|---|
| Philosophy | Why AI-first, core principles |
| Substrate Model | Durable vs fluid layers, hiring implications |
| Workspace Setup | Directory structure, multi-repo layout |
| Tools Checklist | CLI tools, authentication, MCP servers |
The 5-phase development cycle:
| Phase | Document | Description |
|---|---|---|
| Overview | Lifecycle Overview | The complete cycle with diagram |
| 1 | Design & Spec | Collaborative spec iteration |
| 2 | Planning | Agent plan mode |
| 3 | Implementation | Branch/PR workflow |
| 4 | Validation | Testing, CI/CD monitoring |
| 5 | Closure | Docs, Jira, cleanup |
| + | Config Evolution | Maintaining AI configuration |
Ready-to-use templates:
| Template | Use Case |
|---|---|
| Spec Proposal | Design documents, feature proposals |
| Contract | Component-level Design by Contract specs |
| Migration Plan | System migrations, refactoring plans |
| Decision Record | Architecture Decision Records (ADRs) |
| Pull Request | PR template with AI usage disclosure |
| TODO.md | Task tracking (Jira alternative) |
AI tool configuration, plugins, and MCP integration:
| Category | Documents |
|---|---|
| AI Tools | Claude Code, Cursor, Copilot |
| Plugins | Overview, Superpowers |
| MCP | Overview, Servers, Workflows |
| Secrets | Environment & Secrets |
Rules and anti-patterns:
| Document | Description |
|---|---|
| MUST Rules | Non-negotiable requirements |
| SHOULD Rules | Strong recommendations |
| AI Task Boundaries | What to delegate to AI vs own manually |
| Anti-Patterns | Common mistakes to avoid |
Team adoption guides and case studies:
| Document | Description |
|---|---|
| Onboarding Guide | Getting started as a new engineer on an AI-first team |
Guidance for engineering leaders navigating AI-first:
| Document | Description |
|---|---|
| AI-First Leadership | What leaders get wrong, what to do instead |
| For Junior Engineers | Building depth alongside AI fluency |
| For Domain Experts | Growing into production as a non-engineer |
| For Experienced Engineers | When the tools changed - the identity shift |
Concrete configuration examples:
| Example | Description |
|---|---|
| Workspace CLAUDE.md | Workspace-level configuration |
| Project CLAUDE.md | Project-specific overrides |
| .mcp.json | MCP server configuration |
Slide decks for introducing AI-first development (Marp format):
| Presentation | Audience | Description |
|---|---|---|
| Intro | All technical staff | What AI-first is, why it matters, 5-phase workflow |
| Getting Started | Engineers | Hands-on setup: tools, CLAUDE.md, MCP configuration |
These guidelines are designed for:
- Immediate team members - Daily reference for AI-assisted development
- Broader organization - Standardizing AI practices across teams
- New hires - Onboarding to AI-first workflows
This documentation is itself maintained using AI-first practices. See CLAUDE.md for guidelines on contributing with AI assistance.
- Spec-driven development - Design in markdown before coding
- AI as collaborator - Not just autocomplete, but design partner
- Guardrails over guidelines - Clear MUST/MUST NOT rules for critical paths
- Documentation as code - Docs live in git, evolve with the project
- Multi-agent support - Consistent experience across Claude Code, Cursor, Copilot