Skip to content

AI Collaboration Overview

This document explains the philosophy and rules for using AI assistants (ChatGPT, Cursor, Factory agents) in ConnectSoft work. It is written for ConnectSoft team members who use AI tools in their daily work.

ConnectSoft uses AI assistants as co-pilots to accelerate work while maintaining quality and consistency. This guide establishes principles and practices for effective AI collaboration.

Important

Core Rules: 1. AI is a co-pilot, not an unquestioned authority—always review AI outputs 2. Human reviews are required for critical decisions, code, and documentation 3. Never paste secrets, API keys, or sensitive information into AI tools 4. Bias toward reproducible, template-friendly outputs 5. Use AI to maintain consistency with ConnectSoft patterns and style 6. Document AI-assisted decisions in ADRs/BDRs when appropriate

Why We Use AI Assistants

ConnectSoft uses AI assistants to:

  • Speed Up Drafting - Accelerate initial drafts of code, docs, and designs
  • Explore Options - Quickly explore architectural options and alternatives
  • Maintain Consistency - Keep templates, docs, and code consistent with ConnectSoft patterns
  • Reduce Boilerplate - Generate boilerplate code and documentation structure
  • Enhance Productivity - Focus human time on high-value decisions and reviews

Principles of AI Usage

Principle 1: AI as Co-Pilot

  • AI Assists, Humans Decide - AI provides suggestions, humans make final decisions
  • Review Everything - Always review AI-generated code, docs, and designs
  • Question Assumptions - Challenge AI suggestions that don't align with ConnectSoft patterns

Principle 2: Human Review Required

  • Critical Decisions - All architecture and business decisions require human review
  • Code Changes - All code changes require human review before merge
  • Documentation - All documentation requires human review for accuracy and style
  • Security - All security-related changes require human security review

Principle 3: Reproducible Outputs

  • Template-Friendly - Prefer outputs that can be templated and reused
  • Consistent Patterns - Use AI to maintain consistency with ConnectSoft patterns
  • Documented Decisions - Document AI-assisted decisions in ADRs/BDRs

Principle 4: Security and Privacy

  • No Secrets - Never paste secrets, API keys, or sensitive data into AI tools
  • No Customer Data - Never paste customer data or PII into AI tools
  • Use Public Context - Use only public, non-sensitive context in AI prompts

Important

Security Rules: 1. Never paste secrets, API keys, or credentials into AI tools 2. Never paste customer data or PII into AI tools 3. Use only public, non-sensitive context in prompts 4. Review AI outputs for accidental data leakage 5. Use environment variables and secure storage for sensitive data

Typical Use Cases

Architecture and Design

  • Bounded Context Design - Use AI to explore bounded context boundaries
  • API Design - Use AI to draft API contracts and schemas
  • Event Modeling - Use AI to design domain and integration events
  • Pattern Selection - Use AI to explore architectural patterns

Documentation

  • Draft Documentation - Use AI to draft initial documentation structure
  • Style Consistency - Use AI to maintain documentation style
  • Cross-Linking - Use AI to identify and add cross-links
  • Diagrams - Use AI to generate Mermaid diagrams

Code and Refactoring

  • Code Generation - Use AI to generate boilerplate code
  • Refactoring - Use AI to suggest refactoring improvements
  • Test Generation - Use AI to generate test cases
  • Code Review - Use AI to review code for style and patterns

Decision Making

  • Option Exploration - Use AI to explore decision options
  • ADR/BDR Drafting - Use AI to draft ADR/BDR structure
  • Risk Analysis - Use AI to identify risks and mitigations

Tools in Use

ChatGPT

Primary Use: - Architecture brainstorming and design - Documentation drafting - Decision option exploration - ADR/BDR drafting

Best For: - High-level thinking and design - Text generation and editing - Option exploration - Learning and research

Cursor

Primary Use: - Code editing and refactoring - Documentation editing - Multi-file changes - Code review

Best For: - Code-focused work - Large refactorings - Documentation updates - Context-aware editing

Factory Agents

Primary Use: - Code generation via Factory - Architecture design via Architect agents - Quality validation via QA agents - Documentation generation

Best For: - Production code generation - Consistent pattern application - Quality validation - Scalable automation

See: Factory Overview for Factory capabilities.

See: Agent System Overview for agent details.