From 397da76952b48a963e59ab363238a2bd9132169f Mon Sep 17 00:00:00 2001 From: wishket-pjw Date: Sun, 21 Dec 2025 23:52:32 +0900 Subject: [PATCH] docs: Add comprehensive project documentation - Add README, getting started, philosophy, and supported tools guides - Update CI badge URL in mcp-server README close #39 --- README.md | 89 ++++++++++++++++ docs/getting-started.md | 211 ++++++++++++++++++++++++++++++++++++ docs/philosophy.md | 128 ++++++++++++++++++++++ docs/supported-tools.md | 230 ++++++++++++++++++++++++++++++++++++++++ mcp-server/README.md | 2 +- 5 files changed, 659 insertions(+), 1 deletion(-) create mode 100644 README.md create mode 100644 docs/getting-started.md create mode 100644 docs/philosophy.md create mode 100644 docs/supported-tools.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..d3f9e883 --- /dev/null +++ b/README.md @@ -0,0 +1,89 @@ +# Codingbuddy + +[![CI](https://github.com/Codingbuddydev/codingbuddy/actions/workflows/dev.yml/badge.svg)](https://github.com/Codingbuddydev/codingbuddy/actions/workflows/dev.yml) +[![npm version](https://img.shields.io/npm/v/codingbuddy.svg)](https://www.npmjs.com/package/codingbuddy) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + +**One source of truth for AI coding rules across all AI assistants.** + +Codingbuddy provides a unified rules system that works with Cursor, Claude Code, GitHub Copilot, and more—so your entire team follows the same coding standards, regardless of which AI tool they use. + +## Why Codingbuddy? + +- **Consistency**: All AI tools follow identical coding standards +- **Single Source of Truth**: Update rules once, all tools benefit +- **No Vendor Lock-in**: AI-agnostic rules work with any assistant +- **Structured Workflow**: PLAN → ACT → EVAL development cycle + +## Quick Start + +```bash +# Initialize your project (analyzes codebase and creates config) +npx codingbuddy init + +# Add to your AI tool (example: Claude Desktop) +# See docs/supported-tools.md for other AI tools +``` + +Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`): + +```json +{ + "mcpServers": { + "codingbuddy": { + "command": "npx", + "args": ["codingbuddy-mcp"] + } + } +} +``` + +[Full Getting Started Guide →](docs/getting-started.md) + +## Supported AI Tools + +| Tool | Status | +|------|--------| +| Claude Code | ✅ Full MCP support | +| Cursor | ✅ Supported | +| GitHub Copilot | ✅ Supported | +| Antigravity | ✅ Supported | +| Amazon Q | ✅ Supported | +| Kiro | ✅ Supported | + +[Setup Guides →](docs/supported-tools.md) + +## Documentation + +| Document | Description | +|----------|-------------| +| [Getting Started](docs/getting-started.md) | Installation and quick setup | +| [Philosophy](docs/philosophy.md) | Vision and design principles | +| [Supported Tools](docs/supported-tools.md) | AI tool integration guides | +| [Configuration](docs/config-schema.md) | Config file options | +| [API Reference](docs/api.md) | MCP server capabilities | +| [Development](docs/development.md) | Contributing and local setup | + +## How It Works + +``` +.ai-rules/ ← Shared rules (single source of truth) +├── rules/ ← Core rules (workflow, quality) +├── agents/ ← Specialist expertise (security, performance, etc.) +└── adapters/ ← Tool-specific integration guides + +.cursor/ ← Cursor references .ai-rules/ +.claude/ ← Claude Code references .ai-rules/ +.codex/ ← GitHub Copilot references .ai-rules/ +... +``` + +All AI tool configurations reference the same `.ai-rules/` directory. Change the rules once, and every tool follows the updated standards. + +## Contributing + +We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. + +## License + +MIT © [Codingbuddy](https://github.com/Codingbuddydev) diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..44b55348 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,211 @@ +# Getting Started + +Get up and running with Codingbuddy in minutes. + +## Prerequisites + +- **Node.js**: v18 or higher +- **AI Tool**: Any supported AI coding assistant ([see full list](./supported-tools.md)) + +## Quick Start + +### Step 1: Initialize Your Project + +```bash +# Set your Anthropic API key (required for project analysis) +export ANTHROPIC_API_KEY=sk-ant-... + +# Initialize Codingbuddy in your project +npx codingbuddy init +``` + +This command analyzes your project and creates a `codingbuddy.config.js` file with: + +- Detected tech stack (languages, frameworks, tools) +- Architecture patterns +- Coding conventions +- Testing strategy + +### Step 2: Configure Your AI Tool + +Add Codingbuddy to your AI assistant. Here's an example for Claude Desktop: + +**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` + +```json +{ + "mcpServers": { + "codingbuddy": { + "command": "npx", + "args": ["codingbuddy-mcp"] + } + } +} +``` + +For other AI tools, see [Supported Tools](./supported-tools.md). + +### Step 3: Start Coding + +Your AI assistant now has access to: + +- **Project context**: Tech stack, architecture, conventions +- **Workflow modes**: PLAN → ACT → EVAL +- **Specialist agents**: Security, performance, accessibility experts + +Try it: + +``` +You: PLAN Create a user authentication feature + +AI: # Mode: PLAN + I'll design an authentication feature following your project's patterns... +``` + +## Configuration + +### Generated Config File + +The `codingbuddy.config.js` file customizes AI behavior: + +```javascript +module.exports = { + // AI responds in this language + language: 'en', + + // Project metadata + projectName: 'my-app', + + // Technology stack + techStack: { + languages: ['TypeScript'], + frontend: ['React', 'Next.js'], + backend: ['Node.js'], + }, + + // Architecture pattern + architecture: { + pattern: 'feature-sliced-design', + }, + + // Coding conventions + conventions: { + naming: { + files: 'kebab-case', + components: 'PascalCase', + }, + }, + + // Testing approach + testStrategy: { + approach: 'tdd', + coverage: 80, + }, +}; +``` + +See [Configuration Schema](./config-schema.md) for all options. + +### Additional Context + +Add project-specific documentation that AI should know about: + +``` +my-project/ +├── codingbuddy.config.js +└── .codingbuddy/ + └── context/ + ├── architecture.md # System architecture docs + └── api-conventions.md # API design guidelines +``` + +### Ignore Patterns + +Create `.codingignore` to exclude files from AI analysis: + +```gitignore +# Dependencies +node_modules/ + +# Build output +dist/ +.next/ + +# Sensitive files +.env* +*.pem +``` + +## Using Workflow Modes + +### PLAN Mode (Default) + +Start with planning before making changes: + +``` +You: PLAN Add dark mode support + +AI: # Mode: PLAN + + ## Implementation Plan + 1. Create theme context... + 2. Add toggle component... + 3. Persist preference... +``` + +### ACT Mode + +Execute the plan with code changes: + +``` +You: ACT + +AI: # Mode: ACT + + Creating theme context... + [Makes code changes following TDD] +``` + +### EVAL Mode + +Review and improve implementation: + +``` +You: EVAL + +AI: # Mode: EVAL + + ## Code Review + - ✅ Theme context properly typed + - ⚠️ Consider adding system preference detection +``` + +## Using Specialist Agents + +Activate domain experts for specific tasks: + +``` +You: Activate the security-specialist agent to review authentication + +AI: [Activates security-specialist] + + ## Security Review + - Password hashing: ✅ Using bcrypt + - Session management: ⚠️ Consider shorter token expiry + ... +``` + +Available specialists: + +- `security-specialist` - Security audits +- `performance-specialist` - Optimization +- `accessibility-specialist` - WCAG compliance +- `code-reviewer` - Code quality +- And [other specialists](../.ai-rules/agents/README.md) + +## Next Steps + +- [Supported Tools](./supported-tools.md) - Setup guides for each AI tool +- [Philosophy](./philosophy.md) - Understanding the design principles +- [API Reference](./api.md) - MCP server capabilities +- [Development Guide](./development.md) - Contributing to Codingbuddy diff --git a/docs/philosophy.md b/docs/philosophy.md new file mode 100644 index 00000000..3f1198f9 --- /dev/null +++ b/docs/philosophy.md @@ -0,0 +1,128 @@ +# Philosophy + +This document explains the vision, core beliefs, and design principles behind Codingbuddy. + +## Vision + +**One source of truth for AI coding rules across all AI assistants.** + +Today's development teams use multiple AI coding tools—Cursor, Claude Code, GitHub Copilot, and more. Each tool has its own configuration format, leading to: + +- Duplicated rules across multiple config files +- Inconsistent coding standards depending on which AI tool is used +- Maintenance burden when rules need to be updated + +Codingbuddy solves this by providing a unified rules system that works with any AI assistant. + +## Core Beliefs + +### 1. AI-Agnostic Rules + +Rules should be written once and work everywhere. No vendor lock-in, no tool-specific syntax in core rules. Each AI tool adapts to the common format through lightweight adapters. + +### 2. Progressive Disclosure + +Start simple, go deep when needed: + +- **Quick Start**: Get running in 2 minutes with `npx codingbuddy init` +- **Configuration**: Customize tech stack, architecture, and conventions +- **Specialist Agents**: Access domain experts (security, performance, accessibility) +- **Full Customization**: Extend with project-specific rules + +### 3. Convention Over Configuration + +Sensible defaults that work for most projects: + +- PLAN → ACT → EVAL workflow +- TDD-first development approach +- 80%+ test coverage target +- SOLID principles and clean code + +Override only what you need to change. + +### 4. Community-Driven Standards + +The best practices come from real-world experience: + +- Rules are based on proven patterns from production codebases +- Specialist agents encode domain expertise from practitioners +- Open source and open to contributions + +## Design Principles + +### Single Source of Truth + +``` +.ai-rules/ ← The authoritative source +├── rules/ ← Core rules (workflow, quality, project) +├── agents/ ← Specialist knowledge +└── adapters/ ← Tool-specific integration guides +``` + +All AI tool configurations reference `.ai-rules/`. Update once, all tools benefit. + +### Separation of Concerns + +| Layer | Purpose | Format | +|-------|---------|--------| +| **Rules** | What to do (workflow, quality standards) | Markdown | +| **Agents** | Who knows what (specialist expertise) | JSON | +| **Adapters** | How to integrate (tool-specific setup) | Markdown | + +This separation allows: + +- Rules to evolve independently of tool support +- New agents without changing core rules +- New tool support without modifying existing rules + +### Extensibility Over Complexity + +The system is designed to be extended, not configured: + +- Add new specialist agents by creating JSON files +- Support new AI tools by writing adapter guides +- Include project-specific context without modifying core rules + +Simple things should be simple. Complex things should be possible. + +## The Workflow Model + +Codingbuddy introduces a structured workflow for AI-assisted development: + +``` +PLAN → ACT → EVAL +``` + +### PLAN Mode (Default) + +- Understand requirements +- Design implementation approach +- Identify risks and edge cases +- No code changes made + +### ACT Mode + +- Execute the plan +- Follow TDD: Red → Green → Refactor +- Make incremental, tested changes + +### EVAL Mode + +- Review implementation quality +- Identify improvements +- Suggest refactoring opportunities + +This workflow prevents the common pitfall of AI assistants jumping straight into code without proper planning. + +## What Codingbuddy Is Not + +- **Not a code generator**: It provides rules and context, not generated code +- **Not a replacement for human judgment**: It augments, not replaces, developer decision-making +- **Not a one-size-fits-all solution**: It's designed to be customized per project + +## Further Reading + +- [Getting Started](./getting-started.md) - Quick setup guide +- [Supported Tools](./supported-tools.md) - AI tool integration +- [Core Rules](../.ai-rules/rules/core.md) - Workflow details +- [Agents System](../.ai-rules/agents/README.md) - Specialist agents diff --git a/docs/supported-tools.md b/docs/supported-tools.md new file mode 100644 index 00000000..d1761074 --- /dev/null +++ b/docs/supported-tools.md @@ -0,0 +1,230 @@ +# Supported AI Tools + +Codingbuddy works with multiple AI coding assistants through a unified rules system. + +## Overview + +| Tool | Integration | Setup Guide | +|------|-------------|-------------| +| [Claude Code](#claude-code) | MCP Server | [Guide](../.ai-rules/adapters/claude-code.md) | +| [Cursor](#cursor) | Rules Directory | [Guide](../.ai-rules/adapters/cursor.md) | +| [GitHub Copilot / Codex](#github-copilot--codex) | Instructions File | [Guide](../.ai-rules/adapters/codex.md) | +| [Antigravity](#antigravity) | Config Directory | [Guide](../.ai-rules/adapters/antigravity.md) | +| [Amazon Q](#amazon-q) | Rules Directory | [Guide](../.ai-rules/adapters/q.md) | +| [Kiro](#kiro) | Spec Directory | [Guide](../.ai-rules/adapters/kiro.md) | + +## Claude Code + +**Integration Type**: MCP (Model Context Protocol) Server + +Claude Code connects via MCP, providing full access to project configuration, rules, and specialist agents. + +### Quick Setup + +1. Add to Claude Desktop config: + + **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` + + **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` + + ```json + { + "mcpServers": { + "codingbuddy": { + "command": "npx", + "args": ["codingbuddy-mcp"] + } + } + } + ``` + +2. Restart Claude Desktop + +### Features + +- Full MCP resource access (config, rules, agents) +- Tool calls (search_rules, get_agent_details, parse_mode) +- Prompt templates (activate_agent) + +[Full Guide](../.ai-rules/adapters/claude-code.md) + +## Cursor + +**Integration Type**: Rules Directory + +Cursor uses `.cursor/rules/` for project-specific instructions. + +### Quick Setup + +1. Create `.cursor/rules/` directory +2. Reference common rules: + +```markdown + + +# Project Rules + +Follow the common rules in `.ai-rules/`: + +- Workflow: @.ai-rules/rules/core.md +- Quality: @.ai-rules/rules/augmented-coding.md +- Context: @.ai-rules/rules/project.md +``` + +### Features + +- File reference with `@` syntax +- Project-specific customizations +- Agent context via file references + +[Full Guide](../.ai-rules/adapters/cursor.md) + +## GitHub Copilot / Codex + +**Integration Type**: Instructions File + +GitHub Copilot uses `.github/copilot-instructions.md` for custom instructions. + +### Quick Setup + +1. Create instructions file: + +```markdown + + +# Coding Standards + +Follow the guidelines in `.ai-rules/rules/`: + +## Workflow +Use PLAN → ACT → EVAL workflow as defined in core.md + +## Code Quality +- TDD approach (Red → Green → Refactor) +- TypeScript strict mode +- 80%+ test coverage +``` + +### Features + +- Markdown-based instructions +- Repository-wide settings +- Team-shared configuration + +[Full Guide](../.ai-rules/adapters/codex.md) + +## Antigravity + +**Integration Type**: Config Directory + +Antigravity (Gemini-based) uses `.antigravity/` for configuration. + +### Quick Setup + +1. Create `.antigravity/rules/` directory +2. Add rule references: + +```markdown + + +# Project Guidelines + +Reference: .ai-rules/rules/core.md +Reference: .ai-rules/rules/augmented-coding.md +``` + +### Features + +- Gemini model integration +- Rule file references +- Project context awareness + +[Full Guide](../.ai-rules/adapters/antigravity.md) + +## Amazon Q + +**Integration Type**: Rules Directory + +Amazon Q Developer uses `.q/rules/` for custom rules. + +### Quick Setup + +1. Create `.q/rules/` directory +2. Add consolidated rules: + +```markdown + + +# Development Standards + +Follow .ai-rules/ for consistent coding practices. + +Key files: +- .ai-rules/rules/core.md (workflow) +- .ai-rules/rules/augmented-coding.md (TDD) +``` + +### Features + +- AWS integration +- Enterprise features +- Custom rule support + +[Full Guide](../.ai-rules/adapters/q.md) + +## Kiro + +**Integration Type**: Spec Directory + +Kiro uses `.kiro/` for specifications and steering files. + +### Quick Setup + +1. Create `.kiro/steering/` directory +2. Add steering file: + +```markdown + + +# Project Steering + +Apply rules from .ai-rules/: +- Workflow modes (PLAN/ACT/EVAL) +- TDD development +- Code quality standards +``` + +### Features + +- Spec-driven development +- Steering file system +- Task management integration + +[Full Guide](../.ai-rules/adapters/kiro.md) + +## Adding New Tools + +Codingbuddy is designed to support additional AI tools: + +1. Create adapter guide in `.ai-rules/adapters/{tool}.md` +2. Create tool directory `.{tool}/` +3. Reference common rules from `.ai-rules/` + +See [Contributing](../CONTRIBUTING.md) for details. + +## Comparison + +| Feature | Claude | Cursor | Copilot | Antigravity | Q | Kiro | +|---------|--------|--------|---------|-------------|---|------| +| MCP Support | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | +| File References | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | +| Agent Activation | ✅ | ⚠️ | ❌ | ⚠️ | ⚠️ | ⚠️ | +| Project Config | ✅ | ⚠️ | ❌ | ⚠️ | ⚠️ | ⚠️ | + +✅ Full support | ⚠️ Partial (via file reference) | ❌ Not supported + +## Next Steps + +- [Getting Started](./getting-started.md) - Initial setup +- [Philosophy](./philosophy.md) - Design principles +- [API Reference](./api.md) - MCP capabilities diff --git a/mcp-server/README.md b/mcp-server/README.md index cb251d21..32e4bd82 100644 --- a/mcp-server/README.md +++ b/mcp-server/README.md @@ -1,6 +1,6 @@ # Codingbuddy MCP Server -[![CI](https://github.com/Codingbuddydev/codingbuddy/actions/workflows/ci.yml/badge.svg)](https://github.com/Codingbuddydev/codingbuddy/actions/workflows/ci.yml) +[![CI](https://github.com/Codingbuddydev/codingbuddy/actions/workflows/dev.yml/badge.svg)](https://github.com/Codingbuddydev/codingbuddy/actions/workflows/dev.yml) A NestJS-based Model Context Protocol (MCP) server that provides AI coding assistants with project-specific context and rules.