Vibe-Architecting: Collaborative Architecting and Planning with AI: Enhance Your Development Workflow

When building software, the quality of your architecture and planning often dictates the success of your project. However, planning and documenting can quickly become tedious or overlooked tasks. Integrating AI into your workflow, specifically during the planning and implementation stages, can greatly streamline this process and ensure clarity and consistency.

Why Architect and Plan with AI?

Artificial Intelligence, like GitHub Copilot or Claude Code, can play a significant role in creating structured, actionable, and clear implementation plans from your high-level requirements. By engaging in collaborative "vibe coding," where you and your AI assistant iterate on architectural plans first, you ensure a solid foundation before diving into code.

How to tell the AI to work like this?

The magic is in the instruction files you can provide to most AI coding assistants.

• GitHub Copilot: .github/copilot-instructions.md
• Claude Code: CLAUDE.md
• Cursor IDE: .cursorrules

By adding the following markdown, you can tell the AI to follow this pattern.

## Documentation

The `/docs` directory contains:
- Implementation notes in `/docs/notes/`
- Implementation plans in `/docs/plans/`

## Guidelines for Creating or Updating a Plan

- When creating a plan, organize it into numbered phases (e.g., "Phase 1: Setup Dependencies")
- Break down each phase into specific tasks with numeric identifiers (e.g., "Task 1.1: Add Dependencies")
- Please only create one document per plan
- Mark phases and tasks as `- [ ]` while not complete and `- [x]` once completed
- End the plan with success criteria that define when the implementation is complete
- Plans that you produce should go under `docs/plans`
- Use a consistent naming convention `YYYYMMDD-<short-description>.md` for plan files

## Guidelines for Implementing a Plan

- Code you write should go under `src`
- When coding you need to follow the plan and check off phases and tasks as they are completed
- As you complete a task, update the plan by marking that task as complete before you begin the next task
- As you complete a phase, update the plan by marking that phase as complete before you begin the next phase
- Tasks that involve tests should not be marked complete until the tests pass
- Create one coding notes file per plan, in `docs/notes` with naming convention `<plan-file-name>-notes.md`
  - Include a link to the plan file
- When you complete implementation for a plan phase, create a notes entry in the notes file for the plan and summarize the completed work as follows:

   ```markdown
   ## Phase <phase-number>: <phase-name>
   - Completed on: <current UTC date and time>
   - Completed by: <name of the person who completed the phase, not Copilot>

   ### Major files added, updated, removed
   <list of files and brief summary of changes>

   ### Major features added, updated, removed
   <list of features and brief summary of changes>

   ### Patterns, abstractions, data structures, algorithms, etc.
   <list of patterns, abstractions, data structures, algorithms, etc. and brief summary of changes>

   ### Governing design principles
   <list of design principles and brief summary of changes>

## Personal information
- Name: Your Name
- Email: your@name.com

Establishing Your Workflow

Here's how you can structure your project for effective AI-assisted collaboration:

Phase 1: Creating Structured Implementation Plans

Your AI partner can transform initial requirements into well-organized implementation plans, ensuring each plan clearly defines:

• Phases: Breaking the work down into logical, numbered phases (e.g., Phase 1: Setup Dependencies).
• Tasks: Further breaking each phase into clearly defined tasks (e.g., Task 1.1: Add Dependencies).
• Completion Tracking: Adopting a checklist style (- [ ] for incomplete tasks, - [x] for completed tasks) to visualize progress.
• Success Criteria: Clearly defining success criteria to explicitly identify completion points.

These structured plans facilitate better project management and enhanced clarity for everyone involved.

Phase 2: Collaborative Refinement and Discussion

Once an initial AI-generated plan is drafted, take the opportunity to:

• Review and discuss the feasibility of tasks and phases.
• Refine and adjust tasks for accuracy and comprehensiveness.
• Ensure all team members are aligned and clear on the implementation strategy.

This collaborative step is crucial for refining the accuracy of AI-generated plans and ensuring team consensus.

You can also manually edit the plans generated by AI as it will re-read them when prompted to start implementing a phase.

Phase 3: Implementing with AI-Assisted Guidance

With a clear plan in hand, begin your coding efforts by leveraging AI to:

• Generating initial code snippets and implementations under the src directory.
• Following the defined implementation plan closely, marking each task and phase complete upon completion.
• Ensuring any tasks involving testing are only marked as complete when tests successfully pass.

Phase 4: Documentation and Notes

AI will maintain clear documentation by:

• Creating corresponding notes files under docs/notes with a consistent naming convention (e.g., <plan-file-name>-notes.md).
• Regularly summarizing completed phases with details including:
  • Date and time of completion.
  • Name of the team member responsible for the completion.
  • A clear overview of files changed, features adjusted, and core design principles involved.

These detailed notes serve as a reliable reference for future work and ongoing project review.

They also help keep track on how the system evolved over time.

Seeing the System in Action

Here is some sample output from Claude Code using this form of interaction:

Embracing AI as Your Planning Partner

Integrating AI into your planning and documentation workflow can revolutionize how your team approaches software architecture. AI tools empower you to structure and implement plans more effectively, keep comprehensive notes effortlessly, and continuously adapt to changes seamlessly.

By architecting and planning together with AI, you achieve clarity, enhance collaboration, and significantly boost your project's success rate.

Happy coding and planning!