Communicate Effectively with AI! Markdown Syntax Cheat Sheet

Introduction: Why Markdown Matters for AI

In the modern AI era, communication with AI tools like ChatGPT, Claude, and GitHub Copilot has become part of our daily work. However, what’s often overlooked is the importance of “how” you write your instructions to AI.

Markdown syntax is more than just a document format. It’s a structured language that AI can easily understand. By using appropriate Markdown:

• 🎯 Improved AI comprehension - Structured information allows AI to accurately grasp context
• ⚡ Efficient work instructions - Clear formatting conveys intent precisely, reducing back-and-forth
• 📋 Reusable instructions - Instructions created once can be used across different AI tools
• 🔄 Consistent output - Structured input leads to organized AI output

This article explains “Markdown syntax that communicates effectively with AI”, essential for the AI era, with practical examples.

📑 Table of Contents

Basics

• Fundamentals of AI-Friendly Document Structure
• Effective Use of Headings
• Clarifying Tasks with Lists
• Distinguishing Between Emphasis and Code

Practical Applications

• AI Request Templates
• Code-Related Instructions
• Organizing Data with Tables
• Specifying Reference Information with Quotes

Advanced

• Communicating Complex Requirements
• Error Reporting and Debug Requests
• How to Request Code Reviews

AI-Specific Considerations

• Effective AI Communication Techniques
• Writing Styles to Avoid
• Platform-Specific Adaptations

Fundamentals of AI-Friendly Document Structure

🏗️ Importance of Structure

AI excels at hierarchical information structures. Follow these principles:

✅ Good Example: Structured Instructions

# Project: E-commerce Product Search Feature

## Requirements

- Partial match search by product name
- Filter by category
- Filter by price range

## Technical Specifications

- Frontend: React
- Backend: Node.js
- Database: MongoDB

## Deadline

Complete by end of October 2024

❌ Bad Example: Unstructured Instructions

I want to make product search work on an e-commerce site. Search by product name, filter by category, and filter by price. Use React, Node.js, and MongoDB, and want it done by end of October.

📋 Basic Structure Template

# [Project/Task Name]

## Overview

Brief description (1-2 sentences)

## Requirements

- Required feature 1
- Required feature 2
- Optional features (if any)

## Constraints/Conditions

- Technical constraints
- Time constraints
- Other constraints

## Expected Deliverables

Specific description of deliverables

Effective Use of Headings

🎯 Headings That Help AI Understand Context

AI recognizes headings as section boundaries.

✅ Effective Heading Examples

# Main Task: User Authentication System

## 1. Current Situation

Description of existing system

## 2. Problems to Solve

Specific issues

## 3. Desired Solutions

Expected improvements

## 4. Technical Requirements

Technical specifications and constraints

## 5. Priority and Deadline

Schedule information

⚠️ Note: Heading Level Consistency

✅ Good Example:

# Main Title

## Section 1

### Subsection 1-1

### Subsection 1-2

## Section 2

❌ Bad Example:

# Main Title

### Jumping to H3

## Back to H2

#### Even deeper H4

Clarifying Tasks with Lists

📝 Task Lists AI Can Understand

Priority Task Lists

## High Priority (Required)

1. Implement user registration feature
2. Implement login feature
3. Password reset feature

## Medium Priority (Important)

- Profile editing feature
- Two-factor authentication
- Social login

## Low Priority (If Possible)

- [ ] User avatar feature
- [ ] Activity log
- [ ] Notification settings

Phased Work Instructions

## Phase 1: Basic Features

1. Database design
   - Create user table
   - Create authentication info table
2. API design
   - Registration API
   - Login API

## Phase 2: Extended Features

1. Security enhancements
   - Implement encryption
   - Session management
2. UI improvements
   - Responsive design
   - Error handling

Distinguishing Between Emphasis and Code

💡 Effective Emphasis

Highlighting Keywords and Important Items

**Important**: Security requirements are top priority.

_Caution_: This change may affect existing data.

~~Old spec~~ → **New spec**: Use OAuth 2.0

**Highlight**: Performance requirement is response time within 200ms

Specifying Code and Filenames

Please edit the configuration file `config.json`:

```json
{
  "apiEndpoint": "https://api.example.com",
  "timeout": 5000
}
```

Execute command:

```bash
npm install
npm run build
```

Please check variable `userName` and function `validateUser()`.

AI Request Templates

📄 Basic Template

# Request: [Specific Task Name]

## Background/Purpose

Explanation of why this work is needed

## Current Situation

- Existing state
- Available resources
- Constraints

## Expected Deliverables

- Specific deliverables
- Quality standards
- Format (files, code, documents, etc.)

## Technical Requirements

- Technologies/languages to use
- Compatibility requirements
- Performance requirements

## Reference Information

Related documents or links

## Questions/Unclear Points

Note any points to clarify in advance

🎯 Specific Request Example

# Request: Create Responsive Navigation Menu

## Background/Purpose

Need responsive navigation menu as existing website is difficult to use on mobile

## Current Situation

- Existing: Fixed-width header menu
- Tech stack: HTML, CSS, vanilla JavaScript
- Target browsers: Chrome, Firefox, Safari, Edge

## Expected Deliverables

- Responsive navigation with hamburger menu
- Smooth animations
- Accessibility compliant

## Technical Requirements

- **Required**: Use CSS Grid/Flexbox
- **Required**: JavaScript ES6+
- **Recommended**: Utilize CSS variables
- **Constraint**: No libraries like jQuery

## Reference Information

- [Current design mockup](./mockup.png)
- [Competitor site reference](https://example.com)

## Questions/Unclear Points

- Do you have animation speed preferences?
- Do you have icon font specifications?

Code-Related Instructions

💻 Effective Code Requests

Code Modification Request

# Bug Fix Request: Login Function

## Current Code

```javascript
function loginUser(email, password) {
  if (email && password) {
    // Authentication logic
    authenticateUser(email, password);
  }
}
```

## Problems

- Insufficient input validation
- No error handling
- Not compatible with asynchronous processing

## Expected Fixes

- **Required**: Add input validation
- **Required**: Error handling with try-catch
- **Required**: Asynchronous processing with async/await
- **Recommended**: TypeScript type definitions

New Feature Implementation Request

# New Feature: Product Search Filter

## Requirements

- Multi-condition filter search
- Real-time search (update results while typing)
- Save search history

## API Specification

```javascript
// Expected API call
searchProducts({
  query: 'keyword',
  category: 'electronics',
  priceRange: { min: 1000, max: 5000 },
  sortBy: 'price_asc',
});
```

## UI Requirements

- Search bar and filter panel
- Results display area
- Pagination

## Technical Constraints

- React 18 + TypeScript
- State management with Zustand
- Styling with Tailwind CSS

Organizing Data with Tables

📊 Using Specification Tables

API Specification Table

## API Endpoint Specifications

| Endpoint          | Method | Description   | Auth     | Response     |
| ----------------- | ------ | ------------- | -------- | ------------ |
| `/api/users`      | GET    | Get user list | Required | JSON array   |
| `/api/users`      | POST   | Create user   | Not req. | User object  |
| `/api/users/{id}` | PUT    | Update user   | Required | Updated obj. |
| `/api/users/{id}` | DELETE | Delete user   | Required | Delete conf. |

Feature Comparison Table

## Implementation Approach Comparison

| Item           | Method A (REST API) | Method B (GraphQL) | Recommended |
| -------------- | ------------------- | ------------------ | ----------- |
| Dev Speed      | Fast                | Average            | A           |
| Flexibility    | Average             | High               | B           |
| Learning Curve | Low                 | High               | A           |
| Performance    | Average             | High               | B           |
| **Overall**    | **🥈**              | **🥇**             | **B**       |

Progress Management Table

## Development Progress

| Feature         | Assignee | Progress | Deadline | Status         |
| --------------- | -------- | -------- | -------- | -------------- |
| User Auth       | Tanaka   | 90%      | 10/15    | ✅ On Track    |
| Product Mgmt    | Sato     | 60%      | 10/20    | ⚠️ Delayed     |
| Payment Feature | Yamada   | 30%      | 10/25    | 🔄 In Dev      |
| Testing         | All      | 0%       | 10/30    | ⏳ Not Started |

Specifying Reference Information with Quotes

📝 Effective Use of Quotes

Quoting Requirements and Specifications

## Client Requirements

> "If users cannot log in, display a clear error message and
> provide guidance for resolving the issue.
> Also need a feature to temporarily lock the account after 3 failed attempts."
>
> — Client representative (from meeting on September 29, 2024)

## Excerpt from Technical Specifications

> **Security Requirements**
>
> - Password must be at least 8 characters
> - Must include alphanumerics + symbols
> - Common words prohibited as dictionary attack countermeasure
> - Salted hashing required

Quoting Error Messages

## Current Error

Currently experiencing the following error:

> ```
> TypeError: Cannot read property 'map' of undefined
>     at ProductList (ProductList.jsx:15:23)
>     at renderWithHooks (react-dom.development.js:14985:18)
> ```

## Reproduction Steps

1. Access product list page
2. Apply search filter
3. Above error occurs

Communicating Complex Requirements

🧩 Phased Requirement Definition

Breaking Down Large Features

# E-commerce Site Construction Project

## Phase 1: Basic Features (MVP)

### 1.1 User Management

- [ ] User registration
- [ ] Login/Logout
- [ ] Profile editing

### 1.2 Product Display

- [ ] Product list display
- [ ] Product detail display
- [ ] Basic search function

## Phase 2: Purchase Features

### 2.1 Shopping Cart

- [ ] Add to cart
- [ ] Change quantity
- [ ] Remove from cart

### 2.2 Payment

- [ ] Order form
- [ ] Payment processing
- [ ] Order confirmation email

## Phase 3: Admin Features

### 3.1 Product Management

- [ ] Product registration/editing
- [ ] Inventory management
- [ ] Category management

### 3.2 Order Management

- [ ] Order list
- [ ] Shipping status update
- [ ] Sales reports

Specifying Dependencies

## Implementation Order and Dependencies

```mermaid
graph TD
    A[User Auth] --> B[Product Display]
    A --> C[Profile Management]
    B --> D[Shopping Cart]
    D --> E[Payment Feature]
    E --> F[Order Management]
    C --> G[Order History]
    F --> G
```

## Phase Details

### 🥇 Phase 1 (Highest Priority)

**Deadline**: 2 weeks
**Prerequisites**: None
**Deliverable**: Site with login and product display

### 🥈 Phase 2 (High Priority)

**Deadline**: 1 week after Phase 1 completion
**Prerequisites**: Full verification of Phase 1
**Deliverable**: Site with actual purchase capability

### 🥉 Phase 3 (Medium Priority)

**Deadline**: 2 weeks after Phase 2 completion
**Prerequisites**: Payment feature testing completed
**Deliverable**: Site that administrators can operate

Error Reporting and Debug Requests

🐛 Effective Bug Reports

Structured Error Reporting

# Bug Report: Product Search Function

## 🔍 Problem Overview

Searching with Japanese keywords returns 0 results

## 📱 Environment Information

- **Browser**: Chrome 118.0.5993.70
- **OS**: macOS Sonoma 14.0
- **Screen Size**: 1920x1080
- **Device**: MacBook Pro

## 🔄 Reproduction Steps

1. Enter "ノートパソコン" (laptop) in search box on top page
2. Click search button
3. "No search results found" is displayed

## ✅ Expected Behavior

Products related to keyword "ノートパソコン" are displayed

## ❌ Actual Behavior

0 search results displayed

## 📋 Additional Information

- Works correctly with English keyword "laptop"
- Same error with hiragana "のーとぱそこん"
- Products containing "ノートパソコン" in product name actually exist

## 🔧 Investigated Items

- Checked API response in Network tab → Empty array returned
- Confirmed relevant products exist in database

## 🆘 Requested Action

Fix so Japanese product search works correctly

Organizing Debug Information

# Debug Request: API Communication Error

## 🚨 Error Information

### Console Error

```javascript
Uncaught (in promise) TypeError: Failed to fetch
    at async fetchProducts (api.js:23:17)
    at async ProductList.componentDidMount (ProductList.jsx:45:19)
```

### Network Error

```
Status: 500 Internal Server Error
Response: {
  "error": "Database connection failed",
  "timestamp": "2024-09-29T10:30:45.123Z"
}
```

## 🔍 Related Code

### API Call Section (api.js:23)

```javascript
export async function fetchProducts(category) {
  const response = await fetch(`/api/products?category=${category}`);
  return response.json(); // ← Error occurs here
}
```

### Usage Location (ProductList.jsx:45)

```javascript
async componentDidMount() {
  try {
    const products = await fetchProducts(this.props.category);
    this.setState({ products });
  } catch (error) {
    console.error('Failed to load products:', error);
  }
}
```

## 💡 Suspected Causes

1. Database connection pool exhaustion
2. SQL query syntax error
3. Environment variable configuration error

## 🔧 Attempted Solutions

- [x] Clear browser cache
- [x] Restart application
- [ ] Verify database connection
- [ ] Check log files

How to Request Code Reviews

👥 Effective Code Review Requests

Specifying Review Points

# Code Review Request: User Authentication Module

## 📝 Change Overview

Implemented JWT token authentication in user authentication system

## 🎯 Please Review Especially

### 1. Security Aspects

- [ ] JWT secret key management method
- [ ] Token expiration settings
- [ ] CSRF countermeasure implementation

### 2. Performance Aspects

- [ ] Database query optimization
- [ ] Token verification caching strategy

### 3. Code Quality

- [ ] Error handling appropriateness
- [ ] Test code sufficiency

## 📁 Changed Files List

- `src/auth/jwt.js` - JWT operation functions
- `src/middleware/auth.js` - Authentication middleware
- `tests/auth.test.js` - Test code
- `docs/api.md` - API documentation update

## 🔍 Main Changes

### JWT Token Generation

```javascript
function generateToken(user) {
  return jwt.sign(
    {
      userId: user.id,
      email: user.email,
    },
    process.env.JWT_SECRET,
    { expiresIn: '24h' }
  );
}
```

### Authentication Middleware

```javascript
function authenticateToken(req, res, next) {
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1];

  if (!token) {
    return res.status(401).json({ error: 'Access token required' });
  }

  jwt.verify(token, process.env.JWT_SECRET, (err, user) => {
    if (err) return res.status(403).json({ error: 'Invalid token' });
    req.user = user;
    next();
  });
}
```

## ⚠️ Known Issues/TODO

- Refresh token implementation (future task)
- Token invalidation on logout
- Rate limiting implementation

## 🧪 Test Results

- ✅ Unit tests: All 16 passed
- ✅ Integration tests: All 8 passed
- ⏳ E2E tests: Running

## 📚 Reference Materials

- [JWT Best Practices](https://auth0.com/blog/a-look-at-the-latest-draft-for-jwt-bcp/)
- [Node.js Security Checklist](https://blog.risingstack.com/node-js-security-checklist/)

Effective AI Communication Techniques

🤖 Writing That Leverages AI Characteristics

1. Step-by-Step Instructions

## Step-by-Step Approach

### Step 1: Assess Current State

First, identify problems in current code:

- Performance bottlenecks
- Security concerns
- Code readability

### Step 2: Present Improvement Ideas

Present 3 specific improvement ideas for each problem.

### Step 3: Implementation Plan

Select optimal improvement ideas and create implementation order and effort estimates.

2. Clarifying Constraints

## Constraints and Guidelines

### Mandatory Constraints (MUST)

- Maintain compatibility with existing API
- Response time within 200ms
- Use PostgreSQL 14.x

### Recommendations (SHOULD)

- Improve TypeScript type safety
- Comply with ESLint/Prettier rules
- Unit test coverage above 80%

### Optional (MAY)

- Consider GraphQL support
- Docker compatibility
- CI/CD pipeline improvements

3. Explanation Through Examples

## Expected Output Format

Please respond in the following format:

### Analysis Results

Problem: [Specific problem]
Impact: [High/Medium/Low]
Solution: [Specific solution]

### Implementation Example

```javascript
// Before fix
function oldFunction() { ... }

// After fix
function newFunction() { ... }
```

Effort Estimate

• Design: 0.5 days
• Implementation: 2 days
• Testing: 1 day
• Total: 3.5 days

---

## Writing Styles to Avoid

### ❌ NG Patterns and Improvements

#### 1. Vague Instructions

```markdown
❌ Bad Example:
"Please clean up this code"

✅ Good Example:
## Code Refactoring Request

### Points to Improve
- Split functions into single responsibilities
- Change variable names to more descriptive ones
- Consolidate duplicate code
- Add error handling

### Coding Standards
- ESLint ruleset: @typescript-eslint/recommended
- Functions within 50 lines
- Files within 300 lines

2. Insufficient Information

❌ Bad Example:
"There's an error. Please fix it"

✅ Good Example:

## Error Fix Request

### Error Content

TypeError: Cannot read property ‘name’ of null at getUserInfo (user.js:42:18)

### Occurrence Conditions
- User is logged out
- When accessing profile page
- 100% reproducible

### Environment
- Browser: Chrome 118
- Node.js: v18.17.0
- App version: v2.1.3

3. Mixed Multiple Requests

❌ Bad Example:
"Create login function, dashboard, and report function, also change the design, and strengthen security too"

✅ Good Example:

# Development Task List

## Priority 1: Login Function

[Detailed specifications...]

## Priority 2: Dashboard

[Detailed specifications...]

## Priority 3: Report Function

[Detailed specifications...]

_Note: Each task will be requested/confirmed individually_

Platform-Specific Adaptations

🛠️ Optimization by AI Tool

ChatGPT / Claude

• ✅ Provide detailed context in long text
• ✅ Syntax highlighting in code blocks
• ✅ Refine requirements through step-by-step conversation

## ChatGPT Optimization Example

### Background Information

[Detailed background...]

### Specific Questions

1. [Question 1]
2. [Question 2]
3. [Question 3]

### Expected Response Format

[Specific output example...]

GitHub Copilot

• ✅ Function descriptions in comments
• ✅ Express intent through function/variable names
• ✅ Express constraints through type definitions

// Function to authenticate user and generate JWT token
// Input: email(string), password(string)
// Output: Promise<{token: string, user: User} | null>
async function authenticateUser(email, password) {
  // AI suggests implementation from here
}

Notion AI

• ✅ Organize information with block structure
• ✅ Concise requests
• ✅ Template utilization

## Notion AI Optimization

### Background (1 sentence)

[Brief explanation]

### Request (Specific)

[Clear instructions]

### Constraints (Minimum necessary)

- [Constraint 1]
- [Constraint 2]

Practical Template Collection

📋 Commonly Used Request Patterns

1. Bug Fix Request Template

# 🐛 Bug Fix: [Brief Bug Description]

## 📋 Basic Information

- **Discovery Date**: YYYY-MM-DD
- **Severity**: High/Medium/Low
- **Affected Area**: [User/Admin/System]

## 🔍 Problem Details

### Phenomenon

[What is happening]

### Expected Behavior

[How it should be]

### Reproduction Steps

1. [Step 1]
2. [Step 2]
3. [Result]

## 🔧 Technical Details

### Error Message

[Actual error]

### Related Files
- `[Filename]` - [Description]

### Environment Information
- OS:
- Browser:
- Version:

## 💡 Investigated Items
- [x] [Confirmed item 1]
- [ ] [Unconfirmed item 1]

## ⏰ Deadline
[Desired fix date/time]

2. New Feature Development Request Template

# ✨ New Feature: [Feature Name]

## 🎯 Purpose/Background

[Why this feature is needed]

## 👥 Target Users

[Who will use it]

## 📋 Requirements

### Required Features

- [ ] [Feature 1]
- [ ] [Feature 2]

### Optional Features

- [ ] [Feature 3]
- [ ] [Feature 4]

## 💻 Technical Specifications

### Frontend

- Framework:
- Libraries:

### Backend

- Language:
- Database:

## 🎨 UI/UX Requirements

### Design

[Design direction]

### Usability

[Usability requirements]

## ⚡ Performance Requirements

- Response time: Within [X]ms
- Concurrent connections: [X] users

## 🧪 Testing Requirements

- [ ] Unit tests
- [ ] Integration tests
- [ ] E2E tests

## 📅 Schedule

- Design complete: MM/DD
- Development complete: MM/DD
- Testing complete: MM/DD
- Release: MM/DD

3. Code Review Request Template

# 👀 Code Review: [PR/Feature Name]

## 📝 Change Overview

[What was changed]

## 🎯 Review Points

### High Priority

- [ ] [Point to review 1]
- [ ] [Point to review 2]

### Medium Priority

- [ ] [Point to review 3]

## 📁 Changed Files

| File     | Changes  | Priority |
| -------- | -------- | -------- |
| [File 1] | [Desc 1] | High     |
| [File 2] | [Desc 2] | Medium   |

## 🧪 Test Status

- [ ] Unit tests added
- [ ] Existing tests verified
- [ ] Manual testing complete

## ⚠️ Notes

[Special notes if any]

## 🔗 Related Materials

- Issue: #XXX
- Design Doc: [Link]

Summary: Markdown Usage in the AI Era

🎯 Key Points

1. Structure is most important - AI excels at hierarchical information
2. Emphasize specificity - Clear instructions over vague expressions
3. Step-by-step approach - Break down complex requirements
4. Specify constraints - Clearly state technical constraints and deadlines
5. Use examples - Show expected output format with specific examples

📚 For Continuous Improvement

• Utilize feedback: Improve instructions based on AI output
• Accumulate templates: Template effective instruction documents
• Team sharing: Share effective writing styles within team
• Tool-specific optimization: Adjust writing style according to AI tool used

🚀 Next Steps

1. Start practicing with basic templates
2. Customize to suit your work
3. Continuously improve through dialogue with AI
4. Share know-how with team members

Appendix: Additional AI Usage Considerations

🔒 Security & Privacy

Handling Confidential Information

## Security Guidelines

### ❌ Information NOT to Share with AI

- Production environment passwords/API keys
- Personal information (email addresses, phone numbers, etc.)
- Highly confidential business information
- Unreleased product/service information

### ✅ Safe Information Sharing Methods

- Use sample data
- Pseudonymized/anonymized information
- General technical information
- Published technical specifications

### 📝 Alternative Expressions for Confidential Information

❌ Bad Example:
"Cannot connect to production_db_password=abc123"

✅ Good Example:
"Authentication error occurs during database connection"

📊 Tips for Improving Accuracy

1. Providing Context

## Context Information Template

### Project Background

- Industry: [Web Service/E-commerce/Gaming, etc.]
- Scale: [Startup/SME/Enterprise]
- Tech Stack: [List of main technologies]

### Current Situation

- Development Phase: [Planning/Design/Implementation/Testing]
- Team Composition: [Number/Roles]
- Deadline: [Specific dates]

### Constraints/Assumptions

- Budget Constraints: [Yes/No]
- Technical Constraints: [Compatibility with existing systems, etc.]
- Quality Requirements: [Performance/Security, etc.]

2. Iterative Improvement

## Utilizing Feedback Loop

### Initial Question

[First request]

### AI Response

[AI's response content]

### Follow-up Questions/Corrections

- Additional points to verify: [Specific questions]
- Points to correct: [Specific correction requests]
- Consider alternatives: [Request for other options]

### Final Confirmation

- Confirm understood content
- Agree on implementation approach
- Confirm next steps

🔄 Continuous Learning

Responding to AI Tool Updates

## Responding to New Features/Changes

### Regular Check Items

- [ ] New Markdown syntax support status
- [ ] Input limit changes
- [ ] Output format changes
- [ ] Security policy updates

### Best Practice Updates

- Record effective instruction methods
- Identify instruction patterns needing improvement
- Share knowledge within team
- Learn from external sources

We hope this cheat sheet streamlines your communication with AI and contributes to creating better outcomes. We plan to continuously update this guide as AI technology advances.

Last Updated: October 16, 2025 Version: 1.0.0