676 lines
17 KiB
Plaintext
676 lines
17 KiB
Plaintext
# {PROJECT_NAME} Project Documentation
|
|
|
|
> Auto-generated by autonomous-dev on {DATE}
|
|
> Customize sections marked with TODO
|
|
> For help: /align-project
|
|
|
|
**Last Updated**: {DATE}
|
|
**Version**: {VERSION}
|
|
**Status**: {STATUS}
|
|
|
|
---
|
|
|
|
## Project Vision
|
|
|
|
{PROJECT_VISION}
|
|
|
|
TODO: Describe what this project does and why it exists.
|
|
|
|
**Example**:
|
|
"{ProjectName} enables developers to solve [problem X] by providing [solution Y].
|
|
It was created because existing solutions lacked [gap Z]."
|
|
|
|
**Why this matters**:
|
|
This section helps new contributors quickly understand the project's purpose and
|
|
maintains focus during development. Keep it to 1-2 paragraphs.
|
|
|
|
---
|
|
|
|
## Core Principle
|
|
|
|
{CORE_PRINCIPLE}
|
|
|
|
TODO: What makes this project unique? What's the key architectural insight or approach?
|
|
|
|
**Example**:
|
|
"Active Translation, Not Simple Passthrough - While this project acts as an HTTP proxy,
|
|
its primary role is intelligent translation and adaptation between incompatible API formats."
|
|
|
|
**Why this matters**:
|
|
The core principle guides architectural decisions and helps developers understand
|
|
the project's philosophy. This prevents feature creep and maintains consistency.
|
|
|
|
---
|
|
|
|
## Architecture Overview
|
|
|
|
{ARCHITECTURE_OVERVIEW}
|
|
|
|
TODO: Provide a high-level description of how the system is structured.
|
|
|
|
**Example**:
|
|
"This project implements a 5-layer translation architecture that converts between
|
|
incompatible API formats while preserving streaming, tool calling, and error handling."
|
|
|
|
### Architecture Pattern: {ARCHITECTURE_PATTERN}
|
|
|
|
{PATTERN_DESCRIPTION}
|
|
|
|
TODO: Choose and describe your architecture pattern:
|
|
- **Translation Layer**: Format conversion, adapters
|
|
- **MVC/MVVM**: Models, views, controllers
|
|
- **Microservices**: Independent services
|
|
- **Event-Driven**: Pub/sub, message queues
|
|
- **Monolithic**: Single unified codebase
|
|
|
|
**Why this pattern?**
|
|
TODO: Explain why this pattern fits your project's needs.
|
|
|
|
### Key Components
|
|
|
|
{COMPONENT_LIST}
|
|
|
|
TODO: List major components with brief descriptions
|
|
|
|
**Example**:
|
|
- **API Router** (`src/routes/`) - HTTP endpoint handlers
|
|
- **Service Layer** (`src/services/`) - Business logic
|
|
- **Data Access** (`src/db/`) - Database operations
|
|
- **Utilities** (`src/utils/`) - Shared helper functions
|
|
|
|
### Data Flow
|
|
|
|
{DATA_FLOW_DIAGRAM}
|
|
|
|
TODO: Describe or diagram how data moves through the system
|
|
|
|
**For simple projects**, a text description is fine:
|
|
```
|
|
1. Client sends request to API endpoint
|
|
2. Router validates and forwards to service
|
|
3. Service processes and queries database
|
|
4. Response formatted and returned to client
|
|
```
|
|
|
|
**For complex projects**, an ASCII diagram helps:
|
|
```
|
|
┌─────────────────────────────────────────────┐
|
|
│ Client Input │
|
|
└────────────────┬────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────┐
|
|
│ This System │
|
|
│ ┌─────────────────────────────────────┐ │
|
|
│ │ 1. Receive & Validate │ │
|
|
│ └────────────┬────────────────────────┘ │
|
|
│ │ │
|
|
│ ┌────────────▼────────────────────────┐ │
|
|
│ │ 2. Process & Transform │ │
|
|
│ └────────────┬────────────────────────┘ │
|
|
│ │ │
|
|
│ ┌────────────▼────────────────────────┐ │
|
|
│ │ 3. Store or Forward │ │
|
|
│ └────────────┬────────────────────────┘ │
|
|
└───────────────┼─────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────┐
|
|
│ Output/Storage │
|
|
└─────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Technology Stack
|
|
|
|
### Core Technologies
|
|
|
|
{CORE_TECH}
|
|
|
|
TODO: List primary technologies
|
|
|
|
**Example**:
|
|
- **Language**: TypeScript 5.3
|
|
- **Runtime**: Node.js 20.x
|
|
- **Framework**: Express 4.18
|
|
|
|
### Key Dependencies
|
|
|
|
{KEY_DEPENDENCIES}
|
|
|
|
TODO: List critical dependencies and their purpose
|
|
|
|
**Example**:
|
|
- **express** - Web framework for HTTP server
|
|
- **zod** - Runtime type validation
|
|
- **prisma** - Database ORM and migrations
|
|
- **pino** - Structured logging
|
|
|
|
**Why list dependencies?**
|
|
Helps developers understand the tech stack and makes security audits easier.
|
|
Focus on dependencies that are core to the architecture, not every dev dependency.
|
|
|
|
### Development Tools
|
|
|
|
{DEV_TOOLS}
|
|
|
|
TODO: Document build and quality tools
|
|
|
|
**Example**:
|
|
- **Build**: tsc (TypeScript compiler)
|
|
- **Testing**: Jest with ts-jest
|
|
- **Linting**: ESLint with TypeScript plugin
|
|
- **Formatting**: Prettier
|
|
- **Type Checking**: tsc --noEmit
|
|
|
|
---
|
|
|
|
## File Organization Standards
|
|
|
|
### Root Directory Policy
|
|
|
|
**Maximum**: 8 essential .md files
|
|
|
|
**Allowed in root**:
|
|
- README.md - Project overview and quick start
|
|
- CHANGELOG.md - Version history
|
|
- LICENSE - License terms
|
|
- CONTRIBUTING.md - Contribution guidelines
|
|
- CODE_OF_CONDUCT.md - Community standards
|
|
- SECURITY.md - Security policy
|
|
- CLAUDE.md - Development workflow (if using Claude Code)
|
|
- PROJECT.md - This file
|
|
|
|
**All other .md files** must be in `docs/` subdirectories.
|
|
|
|
**Why this policy?**
|
|
Keeps root directory clean and scannable. Users can quickly find essential info
|
|
without sorting through dozens of documentation files.
|
|
|
|
### Directory Structure
|
|
|
|
{DIRECTORY_STRUCTURE}
|
|
|
|
TODO: Document your actual directory structure
|
|
|
|
**Example**:
|
|
```
|
|
project-name/
|
|
├── src/ # Source code (all .ts/.js files)
|
|
│ ├── routes/ # API endpoints
|
|
│ ├── services/ # Business logic
|
|
│ ├── models/ # Data models
|
|
│ └── utils/ # Helper functions
|
|
├── tests/ # All tests
|
|
│ ├── unit/ # Unit tests (< 1s)
|
|
│ ├── integration/ # Integration tests (< 10s)
|
|
│ └── uat/ # User acceptance tests (< 60s)
|
|
├── docs/ # Documentation
|
|
│ ├── guides/ # User guides
|
|
│ ├── debugging/ # Debug and troubleshooting
|
|
│ ├── development/ # Developer documentation
|
|
│ └── architecture/ # Architecture Decision Records (ADRs)
|
|
├── scripts/ # Utility scripts
|
|
│ ├── debug/ # Debugging tools
|
|
│ └── test/ # Testing utilities
|
|
├── dist/ # Build output (gitignored)
|
|
└── node_modules/ # Dependencies (gitignored)
|
|
```
|
|
|
|
### When Creating New Files
|
|
|
|
TODO: Provide examples for common file types
|
|
|
|
#### Shell Scripts (.sh)
|
|
|
|
❌ **Wrong**:
|
|
```
|
|
./test-auth.sh
|
|
./debug-local.sh
|
|
```
|
|
|
|
✅ **Correct**:
|
|
```
|
|
./scripts/test/test-auth.sh
|
|
./scripts/debug/debug-local.sh
|
|
```
|
|
|
|
**Rule**: All shell scripts go in `scripts/` subdirectories:
|
|
- `scripts/debug/` - Debugging and troubleshooting tools
|
|
- `scripts/test/` - Testing utilities
|
|
- `scripts/build/` - Build and deployment scripts
|
|
|
|
#### Documentation (.md)
|
|
|
|
❌ **Wrong** (unless essential):
|
|
```
|
|
./GUIDE.md
|
|
./ARCHITECTURE.md
|
|
./RESEARCH.md
|
|
```
|
|
|
|
✅ **Correct**:
|
|
```
|
|
./docs/guides/user-guide.md
|
|
./docs/architecture/system-design.md
|
|
./docs/research/api-comparison.md
|
|
```
|
|
|
|
**Rule**: Documentation goes in `docs/` subdirectories:
|
|
- `docs/guides/` - User-facing guides
|
|
- `docs/debugging/` - Troubleshooting and debug info
|
|
- `docs/development/` - Developer documentation
|
|
- `docs/architecture/` - Architecture decisions and diagrams
|
|
- `docs/reference/` - API reference, technical specs
|
|
|
|
**Exception**: Only 8 essential .md files allowed in root (see list above).
|
|
|
|
#### Source Code
|
|
|
|
❌ **Wrong**:
|
|
```
|
|
./my-module.ts
|
|
./helper.js
|
|
```
|
|
|
|
✅ **Correct**:
|
|
```
|
|
./src/my-module.ts
|
|
./src/utils/helper.js
|
|
./tests/unit/my-module.test.ts
|
|
```
|
|
|
|
**Rule**: All source code in `src/`, all tests in `tests/`.
|
|
|
|
#### Configuration Files
|
|
|
|
✅ **Root is OK for config**:
|
|
```
|
|
./package.json
|
|
./tsconfig.json
|
|
./.env.example
|
|
./.gitignore
|
|
```
|
|
|
|
**Why?** Build tools expect config files in root. This is a standard convention.
|
|
|
|
---
|
|
|
|
## Development Workflow
|
|
|
|
### Setup
|
|
|
|
{SETUP_INSTRUCTIONS}
|
|
|
|
TODO: Document setup steps
|
|
|
|
**Example**:
|
|
```bash
|
|
# Clone repository
|
|
git clone https://github.com/user/project.git
|
|
cd project
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Copy environment variables
|
|
cp .env.example .env
|
|
# Edit .env with your values
|
|
|
|
# Run database migrations
|
|
npm run db:migrate
|
|
|
|
# Start development server
|
|
npm run dev
|
|
```
|
|
|
|
### Building
|
|
|
|
{BUILD_INSTRUCTIONS}
|
|
|
|
TODO: Document build process
|
|
|
|
**Example**:
|
|
```bash
|
|
# Build for production
|
|
npm run build
|
|
|
|
# Output: dist/ directory with compiled JavaScript
|
|
```
|
|
|
|
### Testing
|
|
|
|
{TEST_INSTRUCTIONS}
|
|
|
|
TODO: Document testing commands
|
|
|
|
**Example**:
|
|
```bash
|
|
# Run all tests
|
|
npm test
|
|
|
|
# Run specific test category
|
|
npm run test:unit # Unit tests only
|
|
npm run test:integration # Integration tests only
|
|
|
|
# Run with coverage
|
|
npm run test:coverage
|
|
|
|
# Watch mode (re-run on file changes)
|
|
npm run test:watch
|
|
```
|
|
|
|
### Common Tasks
|
|
|
|
{COMMON_TASKS}
|
|
|
|
TODO: List frequent developer tasks
|
|
|
|
**Example**:
|
|
- **Start dev server**: `npm run dev`
|
|
- **Run linter**: `npm run lint`
|
|
- **Format code**: `npm run format`
|
|
- **Type check**: `npm run type-check`
|
|
- **Database reset**: `npm run db:reset`
|
|
- **View logs**: `tail -f logs/app.log`
|
|
|
|
**Why document common tasks?**
|
|
Reduces onboarding friction and creates muscle memory for frequent operations.
|
|
|
|
---
|
|
|
|
## Known Issues
|
|
|
|
> Track critical issues, bugs, and technical debt here.
|
|
> Update status as issues are discovered and resolved.
|
|
|
|
### Template for New Issues
|
|
|
|
```markdown
|
|
### {NUMBER}. {Issue Title} ({STATUS})
|
|
|
|
**Status**: CRITICAL | HIGH | MEDIUM | LOW | SOLVED
|
|
**Discovered**: {Date}
|
|
**Affects**: {Which components/features}
|
|
|
|
**Problem**:
|
|
{Clear description of what's broken or wrong}
|
|
|
|
**Root Cause**:
|
|
{Why does this happen? What's the underlying issue?}
|
|
|
|
**Solution**: {If SOLVED}
|
|
{How was it fixed? Link to commit SHA or PR}
|
|
|
|
**Workaround**: {If not yet solved}
|
|
{How can users work around this issue?}
|
|
|
|
**Related**:
|
|
- Issue: #{number}
|
|
- PR: #{number}
|
|
- Commit: {SHA}
|
|
```
|
|
|
|
### Example Entry
|
|
|
|
```markdown
|
|
### 1. API Rate Limiting Not Working (HIGH)
|
|
|
|
**Status**: HIGH
|
|
**Discovered**: 2024-01-15
|
|
**Affects**: All API endpoints
|
|
|
|
**Problem**:
|
|
Rate limiting middleware is installed but not enforcing limits.
|
|
Users can make unlimited requests, risking DoS.
|
|
|
|
**Root Cause**:
|
|
Redis connection string in .env uses wrong port (6380 instead of 6379).
|
|
Middleware fails silently when Redis is unavailable.
|
|
|
|
**Workaround**:
|
|
Monitor request counts manually. Plan to fix in next sprint.
|
|
|
|
**Related**:
|
|
- Issue: #42
|
|
```
|
|
|
|
TODO: Add known issues as they're discovered. Keep this section updated!
|
|
|
|
**Why track issues here?**
|
|
Prevents knowledge loss when team members leave. Makes onboarding transparent
|
|
about current challenges. Helps prioritize technical debt.
|
|
|
|
---
|
|
|
|
## Testing Strategy
|
|
|
|
### Test Categories
|
|
|
|
{TEST_CATEGORIES}
|
|
|
|
TODO: Document your testing approach
|
|
|
|
**Example**:
|
|
|
|
#### Unit Tests
|
|
- **Location**: `tests/unit/`
|
|
- **Count**: {COUNT} tests
|
|
- **Framework**: Jest
|
|
- **Coverage Target**: 80% overall, 90% for critical paths
|
|
- **Purpose**: Test individual functions/modules in isolation
|
|
- **Speed**: < 1 second total runtime
|
|
|
|
**When to write unit tests**:
|
|
- New functions or classes
|
|
- Bug fixes (test first, then fix)
|
|
- Complex logic or algorithms
|
|
|
|
#### Integration Tests
|
|
- **Location**: `tests/integration/`
|
|
- **Count**: {COUNT} tests
|
|
- **Purpose**: Test component interactions (e.g., API + database)
|
|
- **Speed**: < 10 seconds total runtime
|
|
|
|
**When to write integration tests**:
|
|
- New API endpoints
|
|
- Database schema changes
|
|
- Service-to-service communication
|
|
|
|
#### User Acceptance Tests (UAT)
|
|
- **Location**: `tests/uat/` or documented in `tests/manual/`
|
|
- **Count**: {COUNT} scenarios
|
|
- **Purpose**: Validate complete user workflows
|
|
- **Type**: Automated (< 60s) or manual checklist
|
|
|
|
**When to write UAT**:
|
|
- New user-facing features
|
|
- Critical user workflows
|
|
- Before releases
|
|
|
|
### Running Tests
|
|
|
|
{TEST_COMMANDS}
|
|
|
|
TODO: Document test execution
|
|
|
|
**Example**:
|
|
```bash
|
|
# All automated tests
|
|
npm test
|
|
|
|
# Quick validation (unit tests only)
|
|
npm run test:unit
|
|
|
|
# Comprehensive check (all tests + coverage)
|
|
npm run test:all
|
|
|
|
# Manual test procedures
|
|
See: tests/manual/README.md
|
|
```
|
|
|
|
### Coverage Requirements
|
|
|
|
{COVERAGE_REQUIREMENTS}
|
|
|
|
TODO: Define coverage targets
|
|
|
|
**Example**:
|
|
- **Minimum overall**: 80%
|
|
- **Critical paths** (auth, payments): 90%
|
|
- **New code** (in PRs): 100%
|
|
|
|
**How to check coverage**:
|
|
```bash
|
|
npm run test:coverage
|
|
# Opens: coverage/lcov-report/index.html
|
|
```
|
|
|
|
**Why 80%?**
|
|
Balances quality with pragmatism. Some code (simple getters, type definitions)
|
|
doesn't benefit from tests. Focus on business logic and critical paths.
|
|
|
|
---
|
|
|
|
## Documentation Map
|
|
|
|
### User Documentation
|
|
|
|
{USER_DOCS}
|
|
|
|
TODO: Link to user-facing documentation
|
|
|
|
**Example**:
|
|
- [Getting Started](docs/guides/getting-started.md) - New user onboarding
|
|
- [API Reference](docs/reference/api.md) - Complete API documentation
|
|
- [Troubleshooting](docs/debugging/common-issues.md) - Common problems and solutions
|
|
|
|
### Development Documentation
|
|
|
|
{DEV_DOCS}
|
|
|
|
TODO: Link to developer documentation
|
|
|
|
**Example**:
|
|
- [Contributing Guide](CONTRIBUTING.md) - How to contribute
|
|
- [Architecture Overview](docs/architecture/system-design.md) - System design
|
|
- [Coding Standards](docs/development/standards.md) - Code style and conventions
|
|
- [Database Schema](docs/development/database.md) - Data model documentation
|
|
|
|
### Debugging Guides
|
|
|
|
{DEBUG_DOCS}
|
|
|
|
TODO: Link to debugging resources
|
|
|
|
**Example**:
|
|
- [Debug Mode Setup](docs/debugging/debug-mode.md) - Enable verbose logging
|
|
- [Common Errors](docs/debugging/common-errors.md) - Error codes and fixes
|
|
- [Performance Profiling](docs/debugging/profiling.md) - Find bottlenecks
|
|
|
|
### Architecture Documentation
|
|
|
|
{ARCH_DOCS}
|
|
|
|
TODO: Link to architecture decision records (ADRs)
|
|
|
|
**Example**:
|
|
- [ADR-001: Choosing TypeScript](docs/architecture/adr-001-typescript.md)
|
|
- [ADR-002: Database Selection](docs/architecture/adr-002-postgres.md)
|
|
- [System Diagrams](docs/architecture/diagrams/) - Visual architecture
|
|
|
|
**Why maintain a documentation map?**
|
|
Helps developers find information quickly. Documents grow organically; a map
|
|
prevents them from becoming a maze.
|
|
|
|
---
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for:
|
|
- Code style guidelines
|
|
- Pull request process
|
|
- Development setup details
|
|
- Testing requirements
|
|
- Commit message conventions
|
|
|
|
**Quick contributor checklist**:
|
|
1. Fork and clone repository
|
|
2. Create feature branch (`git checkout -b feature/my-feature`)
|
|
3. Make changes with tests
|
|
4. Run `npm run full-check` (lint + test + format)
|
|
5. Commit with conventional message (`feat:`, `fix:`, etc.)
|
|
6. Push and create PR
|
|
|
|
---
|
|
|
|
## Maintenance Notes
|
|
|
|
### Last Review
|
|
TODO: Track when this document was last reviewed
|
|
|
|
**Last full review**: {DATE}
|
|
**Reviewed by**: {NAME}
|
|
**Changes made**: {SUMMARY}
|
|
|
|
**Why track reviews?**
|
|
PROJECT.md should evolve with the codebase. Schedule quarterly reviews to ensure
|
|
accuracy and relevance.
|
|
|
|
### Update Triggers
|
|
|
|
**Update PROJECT.md when**:
|
|
- Architecture changes (new pattern, major refactor)
|
|
- File organization changes (new directories, moved files)
|
|
- Technology stack changes (new framework, language version bump)
|
|
- Testing strategy changes (new test category, coverage targets)
|
|
- Major feature additions (changes to core principle or data flow)
|
|
|
|
**Don't update for**:
|
|
- Minor bug fixes
|
|
- Dependency patches
|
|
- Code refactoring within existing structure
|
|
- Documentation typos
|
|
|
|
**How to validate after updates**:
|
|
```bash
|
|
/align-project
|
|
```
|
|
|
|
---
|
|
|
|
## Version History
|
|
|
|
### {VERSION} - {DATE}
|
|
|
|
**Added**:
|
|
- {Feature or section}
|
|
|
|
**Changed**:
|
|
- {Updated section}
|
|
|
|
**Removed**:
|
|
- {Deprecated section}
|
|
|
|
TODO: Track major PROJECT.md changes here
|
|
|
|
**Why version the documentation?**
|
|
Helps track how the project evolved. Useful for understanding architectural
|
|
decisions in historical context.
|
|
|
|
---
|
|
|
|
**End of PROJECT.md Template**
|
|
|
|
**Next Steps After Customizing**:
|
|
|
|
1. Fill in all TODO sections
|
|
2. Replace placeholder values ({PROJECT_NAME}, {VERSION}, etc.)
|
|
3. Remove sections that don't apply to your project
|
|
4. Add project-specific sections as needed
|
|
5. Run `/align-project` to validate
|
|
6. Commit to version control
|
|
|
|
**Remember**: PROJECT.md is a living document. Update it as your project evolves!
|