Skip to content

AI.md

Latest commit

 

History

History
94 lines (71 loc) · 4.44 KB

AI.md

File metadata and controls

94 lines (71 loc) · 4.44 KB

AI Documentation Requirements

About This Project

This project was created with AI assistance and continues to be maintained with AI help. This document serves as a contract between the project maintainers and any AI system that assists with development. It ensures that AI contributions maintain the project's documentation quality and consistency across all files.

Yes, it's overkill for a repository for simple bash script. This is an experiment in handing off repeatable tasks. Feel free to comment on the approach.

Purpose

This document outlines the requirements for AI-assisted changes to the gitls project. Any AI making changes to any part of the project must adhere to these requirements.

The requirements are structured to ensure that AI contributions consider both implementation and design aspects of the project. By requiring AI to maintain documentation across all project files, we ensure that:

  • Code changes are made with full awareness of their design implications
  • Design decisions are properly documented and justified
  • Implementation details are accurately reflected in technical documentation
  • User-facing documentation remains clear and helpful
  • The project maintains a cohesive architecture and design philosophy

This holistic approach to development helps AI produce better code by considering the broader context and impact of changes, rather than focusing solely on implementation details.

AI Instruction Prompts

Validation Prompt

If the user asks me to "run validation" I should:

  • Use git diff |cat to assess any changes made
  • Read this file to ensure I still meet its requirements
  • Tidy up formatting on the .md files if required

Testing Prompt

If the user asks me to "run tests" I should:

  • Run ./gitls ~/Projects - the ~/Projects parameter is important when testing command-line options, as this directory contains git repositories. The default directory many not.
  • Run with the --help command. Note the different command-line options that you will need to test.
  • Test each of the command-line options, validating that the output of each matches expectations. Stop on the first test that produces unexpected output and engage the user in debugging.

Commit Prompt

If the user asks me to run commit I should do the following:

  • Follow the run tests steps - don't follow further steps if we encounter a failure we need to fix
  • Follow the run validation steps - don't follow further steps if we needed to make changes
  • Use git diff |cat to assess any changes made since checkout, prepare a one-line commit message, a concise description of the changes unless the changes are deminimis, and offer to use git to stage changes and run the commit.
  • If the commit was successful, check for gitls in the user's path. If it exists and if the file contents differ, offer to copy the new version over the version in the user's path.

Documentation Synchronization

The following files must be kept in sync when making changes to the tool:

  1. gitls (the script itself)

    • Contains the actual implementation
    • Includes version number
    • Contains help text with all options and status indicators
    • Must be updated first when making changes

  2. README.md

    • User-facing documentation
    • Must match the script's:
      • Version number
      • Command-line options
      • Status indicators and their resolutions
      • Example output format
      • Dependencies and requirements
      • License information

  3. DESIGN.md

    • Technical documentation
    • Must match the script's:
      • Implementation details
      • Output formatting specifications
      • Status detection methods
      • Parallel processing implementation
      • Error handling mechanisms
      • Performance considerations

Change Process

When making changes, AI must follow this order:

  1. Update the script first
  2. Update README.md to reflect user-facing changes
  3. Update DESIGN.md to reflect implementation changes
  4. Verify all three files are consistent
  5. Update version number in all files if making significant changes

Verification Checklist

Before completing any changes, AI must verify:

  • All three files are consistent
  • Version numbers match across all files
  • Command-line options are documented in all relevant files
  • Status indicators and their resolutions are documented
  • Implementation details are accurately reflected
  • User-facing documentation is clear and complete
  • Technical documentation is accurate and detailed