Human-AI Software Engineering Principles¶

This document presents general Human-AI Software Engineering Principles, a comprehensive framework that builds upon established software engineering, architecture, and design principles from human-only teams and extends them to optimize collaboration between humans and AI agents.

We adopt this general vision for TNH Scholar project recognizing that some elements may not be in use, and that the system of collaboration is evolving organically through development.

Central to this framework is the clear distinction between the Design Phase and the Coding Phase, each with distinct goals, modes, and workflows. It also addresses challenges such as context window limitations and maintaining alignment despite session resets. In addition to general principles, this framework incorporates concrete documentation and planning strategies designed to support long-term, sustainable human-AI collaboration.

1. Core Philosophy: Dialogical Alignment¶

At the heart of this framework lies the principle of dialogical alignment—an ongoing, interactive process of maintaining shared understanding and coordinated goals between human and AI collaborators. This alignment is one layer within a broader system of practices designed to optimize collaboration efficiency, reliability, and adaptability across both design and coding phases.

2. Phases of Engineering: Design vs Coding¶

Engineering work is divided into two primary phases, each with distinct objectives and collaboration modes:

Design Phase (Exploratory Mode): This phase emphasizes creativity, curiosity, and broad ideation. It involves open-ended discussion, exploration of solution spaces, and conceptual modeling. The goal is to generate ideas, define architecture, and plan approaches without premature convergence or repetitive loops.
Coding Phase (Convergent Mode): This phase focuses on decision-making, refinement, and alignment. It involves translating designs into working code, iterative improvement, validation, and ensuring correctness. The goal is clarity, consensus, and delivering actionable outcomes.

Both phases integrate essential engineering activities such as testing, debugging, refinement, and iteration, which are treated as integral loops within the workflow rather than isolated steps.

3. Roles and Responsibilities¶

Human Agent(s): Provide domain expertise, set requirements, validate outputs, and guide the AI through iterative feedback across both design and coding phases.
AI Agent(s): Generate, transform, and organize code and documentation artifacts based on human input and learned patterns.
Shared Responsibility: Both agents engage in continuous communication to ensure mutual understanding and alignment throughout the engineering lifecycle.

4. Artifacts¶

Codebase: The evolving source code, organized into modules and components.
Documentation: Includes design documents, ADRs (Architecture Decision Records), and inline comments.
ADRs and Snapshots: Captured decisions and system states that serve as reference points for future sessions.
Task Lists and Backlogs: Structured to track progress and plan next steps.
Capsules: Bundled collections of relevant artifacts and context representing a session’s core content.
Deltas: Incremental changes or updates made during or between sessions.
Session Summaries: High-level overviews capturing session intent, key decisions, and outcomes.
Conceptual Map / Index of Abstracts: A navigational tool organizing abstracts and top-of-document summaries to provide a structured overview of the knowledge base.

5. Loops and Interactions: Mapping to Phases¶

The framework organizes iterative workflows into loops explicitly mapped to engineering phases:

Exploration Loop (Design Phase): Early-stage ideation and prototyping to explore solution spaces and generate design concepts.
Refinement Loop (Coding Phase): Iterative improvement cycles incorporating feedback and testing to enhance code quality and alignment.
Alignment Loop (Coding Phase): Continuous dialogical checks to confirm shared understanding and consensus during implementation.
Error Recovery Loop (Testing/Debugging/Correction): Mechanisms to detect, communicate, and resolve misunderstandings, bugs, or mistakes throughout both phases.

6. Macros and Pattern Usage¶

Reusable Macros: Predefined prompts, templates, and code snippets to streamline common tasks.
Best Practice Patterns: Established coding and design patterns adapted for human-AI workflows.
Automation Scripts: Tools to automate repetitive or error-prone steps.

7. Context & Memory Strategy¶

Effective collaboration requires managing context and memory across sessions.

AI-specific considerations¶

Context Window Limitations: AI models have finite input sizes; prioritize and compress information to fit within these constraints.
Session Continuity: Use snapshots, ADRs, structured artifacts, capsules, and deltas to maintain continuity across resets or new sessions.
Persistence Strategy: Capture critical decisions and system states regularly to minimize loss of context and facilitate resumption.
Capsule vs Library Layers: Capsules contain session-specific context and deltas, while the Library layer holds stable, abstracted knowledge such as abstracts and top-of-document summaries.
Session Boot Sequence: A structured process to initialize sessions by loading relevant capsules, summaries, and context from the library to establish shared understanding before work begins.

8. Communication and Feedback: Phase-Specific Approaches¶

Communication strategies differ between phases to support their unique goals:

Design Phase (Exploratory Mode):
Emphasizes open-ended, creative dialogue.
Encourages questions, brainstorming, and conceptual clarifications.
Uses flexible, unstructured formats to foster ideation and avoid premature convergence.
Coding Phase (Convergent Mode):
Prioritizes explicit, clear, and unambiguous communication.
Employs structured formats, checkpoints, and validation steps to ensure correctness.
Includes clarification protocols to prevent drift and maintain alignment.

Across both phases:

Mode Declaration: Explicitly state the current mode of collaboration—Exploratory (design) or Convergent (coding)—to align communication and expectations.

9. Quality Assurance¶

Automated Testing: Integrate tests early and often during coding and refinement.
Code Reviews: Human oversight to catch subtle issues.
Continuous Integration: Regular builds and deployments to detect integration problems promptly.

10. Adaptability and Learning¶

Continuous Improvement: Incorporate lessons learned into macros, prompts, and workflows.
Knowledge Sharing: Maintain shared repositories of best practices and artifacts.
Scalability: Design processes to accommodate growing complexity and team size.

11. Meta-Level Design & Documentation Framework¶

This framework introduces a meta-level strategy to organize long-term human-AI collaboration around a Design-OS metaphor, structured documentation, and flexible collaboration modes explicitly connected to the phases of engineering:

Design-OS Metaphor: The collaboration environment is conceptualized as an operating system with a kernel (core shared knowledge and processes), a periphery (dynamic, session-specific artifacts), and rituals (established workflows and communication protocols).
Capsule + Deltas + Session Intent: Each session is encapsulated in a Capsule containing relevant artifacts and context, with Deltas capturing incremental changes. The Session Intent frames the goals and focus for the session, guiding interactions.
Outcomes as Historical Design Memory: Sessions produce structured outcomes including Decisions, Open Questions, and Findings & Ideas that build a living historical record of the design evolution.
Library Layer with Abstracts: Instead of relying on YAML or other rigid formats, the Library layer organizes knowledge through Abstracts and Top-of-Document Summaries, providing concise, human- and AI-readable overviews.
Conceptual Map / Index of Abstracts: A navigational tool that maps relationships between abstracts, enabling efficient exploration and retrieval of knowledge.
Two Modes of Collaboration Linked to Phases:
Exploratory Mode = Design Phase: Prioritizes creativity, curiosity, and broad ideation; encourages open-ended discussion and avoids premature convergence or repetitive loops.
Convergent Mode = Coding Phase: Focuses on decision-making, refinement, and alignment; emphasizes clarity, consensus, and actionable outcomes.
Emphasis on Creativity and Curiosity: The framework encourages maintaining a balance between exploration and convergence, avoiding unproductive cycles by clearly signaling mode shifts and leveraging structured artifacts.

By integrating these meta-level strategies with the core principles, this framework supports sustainable, scalable, and effective human-AI software engineering collaboration that adapts to evolving project needs and complexity.

By combining these principles, the Human-AI Software Engineering Principles framework aims to foster robust, efficient, and aligned collaboration between human developers and AI agents, leveraging the strengths of both to create high-quality software.