# AIUSE.md

A simple standard for disclosing how AI is used in a project.

"AI is encouraged. Just be transparent about how it's used." --Confucius

# What is AIUSE.md?

AIUSE.md is a lightweight, markdown-based convention for transparency in AI usage.

It defines:

• How to declare AI usage policy and contribution guidelines
• Where to store supporting logs (chat transcripts) for disclosure of AI usage
• How to keep humans accountable and fight low quality AI slop

# Quick Start

1. Add AIUSE.md to your project root to define your AI policy [templates]
2. Add /aiuse/ folders to store AI interaction logs [format]
3. Optionally override AIUSE.md in subfolders if different rules apply

# Main Idea

It is not possible to reliably classify whether AI usage is "fair" or "slop" in an automated way. These judgments are inherently subjective. Instead of enforcing rules, this standard promotes transparent disclosure.

Contributors are expected to share the raw AI interactions that influenced their work. This may include chats, prompts, or tool usage logs. Reviewers can then inspect this data and form their own judgment if the AI usage is "fair" based on their own criteria.

The format is designed to be human-readable and easy to review in Git.

# Spec

# AIUSE.md

This file defines the project's AI usage policy and contribution guidelines.

The primary file should be placed in the project root. If different parts of the project require different rules, AIUSE.md can be overridden in subfolders. There is no strict format for this file. You are encouraged to use the following templates:

# Template: default (disclose)

# AIUSE.md

This project allows and encourages the use of AI tools. Contributors are expected to disclose
how AI was used according to the spec: https://aiuse.md

If AI tools were used (chats, prompts, agents, etc.), add logs of the interaction under
`/aiuse/` subfolders in the relevant part of the project.

Automatic log exporters for popular AI tools: https://aiuse.md#exporters

# Template: AI prohibited

# AIUSE.md

This project prohibits any use of AI tools for creating or editing content. All contributions
must be created entirely by a human.

This includes, but is not limited to:
- Chat-based AI systems (e.g. ChatGPT, Claude, Gemini)
- Code generation tools (e.g. GitHub Copilot, Cursor)
- AI writing assistants or paraphrasing tools
- Image, audio, or video generation tools
- Autonomous agents or workflows that produce or modify content

# Logs

Human-readable records of interactions with AI tools used to create or modify content.

Logs should be stored under /aiuse/ subfolders in the relevant part of the project, typically alongside the content they were used to create or modify.

# Log File Structure

Example:

aiuse/
  2026-04/
    2026-04-28--feature-design--k3f9.md
    2026-04-28--feature-design--k3f9--image.jpg

• Each file represents a single AI interaction session
• Filenames follow: YYYY-MM-DD--topic--rand.md
  • topic: allowed chars [a-z0-9-], no consecutive dashes --, max 40 chars
  • rand: short random string to avoid collisions, allowed chars [a-z0-9], usually 4 chars
• Attachments follow: YYYY-MM-DD--topic--rand--filename.ext
  • Attachments are optional (images, videos, PDFs, etc.)
  • Referenced in the log using <attachment:filename.ext> tags
  • filename.ext: allowed chars [a-z0-9-], no consecutive dashes --, max 40 chars

# Log File Format

Example:

### User
Hello, I want to design the checkout feature.

### Assistant
You can approach this by ...

### User
My Stripe API key is <redacted>, will it be protected against abuse?

### Assistant
Yes, since the API key is placed on the server side, users won't have access to it.

• Supported roles:
  • User: prompts entered by the user
  • Assistant: replies generated by the AI assistant
  • System: initial instructions or hidden setup (rare)
  • Tool: when the assistant runs an external tool (e.g. CLI commands, APIs)
• Replies should remain concise for readability
  • Replies appear in chronological order and are not nested
  • Replies over 4000 chars should be shortened with <truncated> or replaced with <attachment>
  • Replies unrelated to the disclosed interaction topic may be omitted
• Special tags:
  • <redacted>: removes sensitive information (e.g. secrets, PII)
  • <truncated>: indicates content that was shortened to respect length limits
  • <attachment:filename.ext>: references an external file (e.g. images, videos, PDFs)
  • <changes>: summarizes multi-file modifications by agents

# Reply Format

• Replies should be plain text when possible

• If a reply contains structured markdown (e.g. headings, lists, tables), it should be wrapped in a ```markdown block:

  ### User
  Create bullet points for my presentation
  
  ### Assistant
  ```markdown
  # Presentation
  ## Slide 1
  * Bullet a
  * Bullet b
  * Bullet c
  ```
  

• Code should always be wrapped in ```code blocks with the appropriate language:

  ### User
  How do I reverse an ascii string in javascript?
  
  ### Assistant
  ```js
  function reverse(s) {
    return s.split("").reverse().join("");
  }
  ```
  

# Special Tags

• <redacted>: removes sensitive information (e.g. secrets, PII)

  ### User
  My Stripe API key is <redacted>, will it be protected against abuse?
  

• <truncated>: indicates content that was shortened to respect length limits

  ### User
  What is the full text of Harry Potter?
  
  ### Assistant
  Mr. and Mrs. Dursley, of number four, Privet Drive, were proud to say that they were
  perfectly normal, thank you very much. They were the last people you'd expect to be
  involved in anything strange or mysterious, because they just didn't hold with such
  nonsense.<truncated>
  

• <attachment:filename.ext>: references an external file (e.g. images, videos, PDFs)

  ### User
  Remove the background from this image
  <attachment:input.jpg>
  
  ### Assistant
  <attachment:output.png>
  

  If the session file was named 2026-04-28--logo-design--a2xz.md, the adjacent attachment files should be named:

  • 2026-04-28--logo-design--a2xz--input.jpg
  • 2026-04-28--logo-design--a2xz--output.png

  Including the adjacent attachment files is optional, if the files are not included, omit the filename:

  ### User
  Remove the background from this image
  <attachment>
  
  ### Assistant
  <attachment>
  

• <changes>: summarizes multi-file modifications by agents

  ### User
  Implement the new authentication flow
  
  ### Assistant
  <changes>
  - modified: src/auth.ts
  - modified: src/api/login.ts
  - created: src/utils/token.ts
  - deleted: src/old/auth_old.ts
  </changes>
  

  If the number of changes exceeds 20 files, provide a summary instead of listing individual files:

  ### User
  Implement the new authentication flow
  
  ### Assistant
  <changes>
  - modified: 34 files
  - created: 2 files
  - deleted: 7 files
  </changes>
  

# Tools

• The Tool role is used when the assistant runs an external tool (e.g. CLI commands, APIs)

• The input command should be wrapped in a ```code block:

  ### User
  Are the tests passing?
  
  ### Assistant
  Running the test suite
  
  ### Tool
  ```bash
  npm run test
  ```
  

• Command output is optional and should be wrapped in a consecutive ```text block:

  ### User
  Are the tests passing?
  
  ### Assistant
  Running the test suite
  
  ### Tool
  ```bash
  npm run test
  ```
  ```text
  > project@1.0.0 test
  > jest
  
  PASS src/utils.test.ts
  FAIL src/api.test.ts
  
  * GET /api/user › should return 200
    Expected: 200
    Received: 500
  
  Tests:       1 failed, 5 passed
  ```
  

• Input or output over 4000 chars should be shortened with <truncated> or replaced with <attachment>

# Automatic Log Exporters

Logs can be created manually, but using an automatic exporter is recommended.

Exporters are available for popular AI tools:

# Contribute

If you'd like to contribute to this spec please open a PR in https://github.com/aiusemd/spec

AIUSE.md was created by Tal Kol