DDD-TDD Development with Cursor Tools

A comprehensive development workflow that combines Domain-Driven Design (DDD) and Test-Driven Development (TDD) principles with AI-powered tools for research, code review, and browser automation.

Overview

This skill enables developers to build applications using best practices with integrated AI assistance. It emphasizes clean architecture, composable functions, and continuous feedback loops with AI teammates (Perplexity for research, Gemini for code review, Stagehand for browser testing).

Core Principles

1. **Domain-Driven Design (DDD)**: Split main domains into separate folders for clear separation of concerns

2. **Test-Driven Development (TDD)**: Write unit tests using Vitest before implementation

3. **Type Safety**: Avoid type repetition by placing types near their domain and reusing them via Extract/Pick

4. **Functional Programming**: Write small, composable, pure functions using Dependency Injection

5. **Code Quality**: Always format with Prettier and lint with ESLint

6. **AI-Powered Workflow**: Use AI tools in feedback loops for research, review, and testing

7. **Environment Security**: Use environment variables and never commit `.env` files (provide `.env.sample` instead)

8. **Clean Imports**: Do not explicitly declare file extensions in imports

Step-by-Step Instructions

1. Project Setup and Architecture

When starting a new feature or domain:

1. Identify the domain and create a dedicated folder structure following DDD principles

2. Define types close to the domain they represent

3. Create a `.env.sample` file with placeholder values for any required configuration

4. Set up Vitest test files alongside domain code

2. AI-Assisted Research Phase

Before implementing any feature:

1. Use **Perplexity** (via `cursor-tools web`) to research best practices:

```bash

cursor-tools web "best practices for [your topic]" --save-to=local-research/[topic].md

```

2. Review research results and identify patterns to apply

3. For complex queries, always save output to `local-research/` directory

3. Type-First Development

1. Define types and interfaces first, placing them near their domain

2. Reuse types across domains using TypeScript's Extract/Pick utilities

3. Ensure type relationships are clear and non-redundant

4. Test-Driven Development Cycle

For each function or module:

1. Write the test first using Vitest

2. Define the function signature with proper Dependency Injection

3. Implement the minimal code to pass the test

4. Refactor for composability and purity

5. Run tests: ensure all pass before proceeding

5. AI Code Review Loop

After writing code:

1. Use **Gemini** (via `cursor-tools repo`) for peer review:

```bash

cursor-tools repo "review the code in [file/module] for best practices and potential issues"

```

2. Address feedback and iterate

3. Use for repository-specific questions:

```bash

cursor-tools repo "explain the authentication flow"

```

6. Code Quality Checks

Before committing:

1. Format code with Prettier

2. Lint code with ESLint

3. Ensure all tests pass

4. Verify no `.env` files are staged for commit

7. Browser Testing with Stagehand

For web applications:

1. **Open and inspect pages**:

```bash

cursor-tools browser open "https://your-app.com" --html --screenshot=screenshots/page.png

```

2. **Automated interactions** (multi-step with pipe separator):

```bash

cursor-tools browser act "Click Login | Type '[email protected]' into email | Click Submit" --url=https://your-app.com

```

3. **Extract data**:

```bash

cursor-tools browser extract "product names and prices" --url=https://your-app.com/products

```

4. **Long-lived sessions** for development:

```bash

cursor-tools browser act "navigate to dashboard" --url=https://your-app.com --connect-to=reload-current

```

5. **Record interactions** for documentation:

```bash

cursor-tools browser act "complete user signup flow" --url=https://your-app.com --video=videos/ --no-headless

```

8. Documentation Generation

Generate comprehensive documentation:

```bash

cursor-tools doc --output docs.md

```

For remote repositories:

```bash

cursor-tools doc --from-github=username/repo --save-to=local-docs/repo-name.md

```

9. GitHub Integration

Monitor issues and pull requests:

```bash

View last 10 PRs

cursor-tools github pr

View specific PR

cursor-tools github pr 123

View issues from another repo

cursor-tools github issue --from-github=username/repo

```

10. Continuous Feedback Loop

**ALWAYS work in this cycle:**

1. **Search** (Perplexity) → Research best practices

2. **Try** → Implement with TDD

3. **Review** (Gemini) → Get AI peer review

4. **Test** → Run unit tests and browser tests

5. **Repeat** → Iterate based on feedback

Tool Quick Reference

Nicknames

Common Options

Browser Options

Important Notes

1. **Context Limits**: `cursor-tools repo` has 2M token limit. Use `.repomixignore` to reduce context

2. **Browser Prerequisites**: Install Playwright globally: `npm install -g playwright`

3. **Stagehand Wait**: DO NOT ask browser act to "wait" - the wait command is disabled

4. **Stateless Browser**: Browser commands are stateless unless using `--connect-to`

5. **Configuration**: Store configs in `cursor-tools.config.json` and API keys in `.cursor-tools.env`

Example Workflow

```bash

1. Research best practices

cursor-tools web "DDD patterns for user authentication" --save-to=local-research/auth-patterns.md

2. Get repository context

cursor-tools repo "show me the current authentication implementation"

3. Write tests (in code editor)

4. Implement feature (in code editor)

5. Review with Gemini

cursor-tools repo "review the new authentication module for security issues"

6. Test in browser

cursor-tools browser act "test login with valid credentials | verify dashboard loads" --url=http://localhost:3000 --video=test-videos/

7. Format and lint

Run prettier and eslint

8. Generate documentation

cursor-tools doc --output docs/authentication.md

```

Constraints