ai-dev-diary/README.md

Intelligent development diary system for AI-assisted projects

# AI Development Diary

An intelligent development diary system for AI-assisted projects that helps teams and AI agents learn, improve, and build better software together.

## Overview

AI Development Diary is a standalone tool that creates a structured knowledge system for development projects. It captures insights, mistakes, breakthroughs, and context to make both AI agents and human developers more effective over time.

## Features

- 📝 **Structured Entries**: Journey, insight, mistake, breakthrough, and context entries
- 🤖 **AI Agent Protocol**: Standard interface for AI assistants to log and learn
- 🔍 **Smart Search**: Find patterns and insights across entries
- 📊 **Analytics**: Track learning velocity and mistake patterns
- 🔗 **Git Integration**: Auto-generate entries from commits
- 📚 **Knowledge Base**: Build reusable patterns and avoid repeated mistakes
- 🌐 **Team Sharing**: Share learnings across projects and teams

## Quick Start

### Installation

```bash
# Install globally
npm install -g ai-dev-diary

# Or use in a project
npm install --save-dev ai-dev-diary
```

### Initialize in Your Project

```bash
# Navigate to your project
cd my-project

# Initialize diary
ai-diary init

# This creates:
# - .ai-diary/ directory for entries and knowledge
# - .ai-diary/config.json for configuration
# - Git hooks for automatic entry generation
```

### Basic Usage

```bash
# Create a new entry interactively
ai-diary entry

# Quick entry types
ai-diary journey "Implemented new authentication system"
ai-diary insight "Discovered that caching improves performance by 40%"
ai-diary mistake "Assumed API would return array, but returns object"
ai-diary breakthrough "Found solution to memory leak issue"

# Update AI context
ai-diary context update

# Search entries
ai-diary search "performance"
ai-diary search --type=mistake --last=30d

# Generate reports
ai-diary report weekly
ai-diary report insights
```

## For AI Agents

Add this to your AI agent's system prompt:

```markdown
## Development Diary Protocol

This project uses ai-dev-diary. You MUST:

1. Start each session by reading context:
   ```bash
   ai-diary context read
   ```

2. Log significant events during work:
   ```bash
   ai-diary insight "Discovered X pattern works well for Y"
   ai-diary mistake "Assumed Z but actually it was W"
   ai-diary journey "Refactored authentication to use JWT"
   ```

3. End each session with context update:
   ```bash
   ai-diary context update --summary "What changed in this session"
   ```

4. Search for relevant past experiences:
   ```bash
   ai-diary search "similar problem"
   ```
```

## Directory Structure

After initialization, your project will have:

```
.ai-diary/
├── config.json                  # Configuration
├── context/
│   ├── AGENT_CONTEXT.md        # Current AI context
│   ├── PROJECT_STATE.md        # Project state
│   └── MEMORY.md               # Important things to remember
├── entries/
│   └── [YYYY]/[MM]/[DD]/       # Date-organized entries
├── knowledge/
│   ├── patterns.md             # Successful patterns
│   ├── antipatterns.md         # What to avoid
│   ├── mistakes.md             # Mistakes log
│   └── breakthroughs.md        # Major wins
└── insights/
    └── [category].md           # Categorized insights
```

## Entry Types

### Journey Entry
Documents development progress and decisions made.

```bash
ai-diary journey "Migrated database from MongoDB to PostgreSQL"
```

### Insight Entry
Captures discoveries and realizations.

```bash
ai-diary insight "Using connection pooling reduced latency by 60%"
```

### Mistake Entry
Logs errors and their corrections for future prevention.

```bash
ai-diary mistake "Used synchronous file operations causing blocking"
```

### Breakthrough Entry
Records major solutions and wins.

```bash
ai-diary breakthrough "Solved the race condition with mutex locks"
```

### Context Update
Updates the AI agent context with current project state.

```bash
ai-diary context update --summary "Added authentication system"
```

## Advanced Features

### Analytics

```bash
# View learning velocity
ai-diary analytics velocity

# Analyze mistake patterns
ai-diary analytics mistakes

# Generate insights from entries
ai-diary analytics insights
```

### Team Collaboration

```bash
# Share insights with team
ai-diary share insights --team

# Import learnings from another project
ai-diary import ~/other-project/.ai-diary/knowledge/

# Export diary for backup
ai-diary export --format=json > diary-backup.json
```

### Git Integration

```bash
# Install git hooks
ai-diary install-hooks

# This enables:
# - Auto-generate entries from commits
# - Link entries to code changes
# - Track which files are frequently modified
```

## Configuration

Edit `.ai-diary/config.json`:

```json
{
  "author": "Your Name",
  "team": "Your Team",
  "ai": {
    "model": "claude-3",
    "autoContext": true
  },
  "git": {
    "autoEntries": true,
    "linkCommits": true
  },
  "sharing": {
    "team": true,
    "public": false
  }
}
```

## Benefits

- **Continuous Learning**: Every session builds on previous knowledge
- **Mistake Prevention**: Avoid repeating documented failures
- **Context Preservation**: New team members understand quickly
- **Better AI Assistance**: AI agents have full project context
- **Knowledge Sharing**: Learn from collective team experience

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Support

- Documentation: [https://ai-dev-diary.dev](https://ai-dev-diary.dev)
- Issues: [GitHub Issues](https://github.com/yourusername/ai-dev-diary/issues)
- Discord: [Join our community](https://discord.gg/ai-dev-diary)

---

Built with ❤️ to make AI-assisted development more intelligent and effective.