markdown-doc-writer

Markdown ドキュメントライター

このスキルを使う場面

以下の場合にこのスキルを使います：

• README ファイルを作成するとき
• アルゴリズムの説明を作成するとき
• システム設計の解決策をドキュメント化するとき
• 面接準備ガイドを作成するとき
• チートシートやリファレンス資料を作成するとき
• コードのドキュメントを追加するとき

ドキュメントの標準

1. 構成ガイドライン

doc/cheatsheet/ と doc/faq/ 以外のドキュメントは通常、明確な H1、1 段落の説明、見出しレベルを飛ばさないセクションで構成されます。この 2 つのツリーには、それぞれ独自の必須形式があります（以下の「プロジェクト固有のガイドライン」を参照してください）。

標準テンプレート：

# Title

Brief description of what this document covers.

## Table of Contents
- [Section 1](#section-1)
- [Section 2](#section-2)

## Section 1

Content...

## Section 2

Content...

## References
- [Link 1](url)

2. アルゴリズムドキュメントの形式

アルゴリズムの問題には、次の構成を使います：

# Problem Number: Problem Title

**Difficulty**: Easy/Medium/Hard
**Topics**: Array, Two Pointers, Hash Table
**Companies**: Google, Amazon, Meta

## Problem Statement

[Clear description of the problem]

**Example 1:**

Input: [example input] Output: [example output] Explanation: [why this is the output]

**Constraints:**
- [List constraints]

## Approach

### Intuition

[Explain the key insight in simple terms]

### Algorithm

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

### Complexity Analysis

- **Time Complexity**: O(n) - [Explain why]
- **Space Complexity**: O(1) - [Explain why]

## Solution

### Java
```java
class Solution {
    public ReturnType method(InputType param) {
        // Implementation
    }
}

Python

class Solution:
    def method(self, param: InputType) -> ReturnType:
        # Implementation

別のアプローチ

アプローチ 2：[名前]

[説明]

計算量：時間 O(?)、空間 O(?)

比較

アプローチ	時間	空間	備考
アプローチ 1	O(n)	O(1)	最適
アプローチ 2	O(n²)	O(1)	コードがより簡潔

主なポイント

• [学習ポイント 1]
• [学習ポイント 2]

関連する問題

• 問題 A
• 問題 B

### 3. System Design Documentation Format

**Follow the template structure:**

```markdown
# System Name: Brief Description

## 1. Requirements

### Functional Requirements
- Feature 1: [Description]
- Feature 2: [Description]

### Non-Functional Requirements
- **Scale**: X million DAU, Y QPS
- **Performance**: p99 latency < Z ms
- **Availability**: 99.9% uptime

## 2. Capacity Estimation

### Traffic
- Daily Active Users: 100M
- Requests per user: 10/day
- QPS: 100M * 10 / 86400 ≈ 11,574

### Storage
- Per user data: 1KB
- Total: 100M * 1KB = 100GB

### Bandwidth
- Average request size: 10KB
- Bandwidth: 11,574 QPS * 10KB ≈ 115MB/s

## 3. API Design

POST /api/resource GET /api/resource/{id} PUT /api/resource/{id} DELETE /api/resource/{id}

## 4. High-Level Architecture

[クライアント] → [ロードバランサー] → [アプリサーバー] ↓ [キャッシュ] [DB]

## 5. Database Design

### Schema

```sql
CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

インデックス戦略

• 高速な検索のために username にインデックスを設定
• ソートのために created_at にインデックスを設定

6. コンポーネントの詳細設計

コンポーネント 1：[名前]

責務：[実行する内容]

テクノロジー：[具体的な技術の選択]

スケーリング：[スケール方法]

7. スケーラビリティと信頼性

キャッシュ戦略

• [何を、どこに、なぜキャッシュするか]

シャーディング戦略

• [データの分割方法]

レプリケーション

• [マスター・スレーブ構成]

8. トレードオフと代替案

決定事項	選択したもの	代替案	理由
データベース	PostgreSQL	MongoDB	ACID が必要

9. モニタリングとアラート

• 追跡するメトリクス：[一覧]
• アラート：[通知を発生させる条件]

10. セキュリティに関する考慮事項

• 認証：[方式]
• 認可：[方式]
• データ暗号化：[保存時、転送時]

参考資料

• [外部リソース]

### 4. Code Formatting

**Inline code**: Use `backticks` for variable names, commands, short code

**Code blocks**: Use fenced code blocks with language

```markdown
```java
public class Example {
    // Code here
}

**Supported languages:**
- `java`, `python`, `javascript`, `sql`, `bash`
- `json`, `yaml`, `xml`, `markdown`
- `c`, `cpp`, `scala`, `go`

### 5. Visual Elements

**Tables:**
```markdown
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |

リスト：

Unordered:
- Item 1
  - Nested item
- Item 2

Ordered:
1. First step
2. Second step
3. Third step

強調：

*italic* or _italic_
**bold** or __bold__
***bold italic***
`code`
~~strikethrough~~

リンク：

[Link text](URL)
[Link with title](URL "Title")
[Reference link][ref]

[ref]: URL "Title"

画像：

![Alt text](image-url)
![Alt text](image-url "Title")

6. 計算量の分析ドキュメント

標準形式：

## Complexity Analysis

### Time Complexity: O(n log n)
- Sorting takes O(n log n)
- Single pass takes O(n)
- Overall: O(n log n)

### Space Complexity: O(n)
- Hash map stores n elements: O(n)
- Result array: O(n)
- Overall: O(n)

### Optimization Notes
- Can reduce space to O(1) by modifying input in-place
- Trade-off: Destroys original input

参照用の計算量チートシート：

| Notation | Name | Example |
|----------|------|---------|
| O(1) | Constant | Array access |
| O(log n) | Logarithmic | Binary search |
| O(n) | Linear | Array scan |
| O(n log n) | Linearithmic | Merge sort |
| O(n²) | Quadratic | Nested loops |
| O(2ⁿ) | Exponential | Recursive Fibonacci |
| O(n!) | Factorial | Permutations |

7. 文体ガイドライン

明確に書く：

• 簡潔な言葉を使う
• 必要がない限り、専門用語を避ける
• 技術用語は初出時に定義する
• 能動態を使う

簡潔に書く：

• 不要な言葉を削る
• リストには箇条書きを使う
• 長い段落を分割する
• 1 段落につき 1 つの考えを述べる

一貫性を保つ：

• 全体を通して同じ用語を使う
• 命名規則に従う
• 書式を一貫させる
• 類似したドキュメントにはテンプレートを使う

例：

❌ 悪い例：

The algorithm basically works by iterating through the array and
then it checks if the element is what we're looking for.

✅ 良い例：

The algorithm iterates through the array to find the target element.

8. 面接準備用ドキュメント

パターンのテンプレート：

# Pattern Name

## When to Use
- [Characteristic 1]
- [Characteristic 2]

## Template Code

```python
def pattern_template(arr):
    # Step 1: Setup

    # Step 2: Main logic

    # Step 3: Return result

問題の例

1. 問題 1 - 易しい
2. 問題 2 - 中程度
3. 問題 3 - 難しい

要点

• [ヒント 1]
• [ヒント 2]

### 9. Cheat Sheet Format

**Keep it scannable:**
```markdown
# Topic Cheat Sheet

## Quick Reference

| Operation | Syntax | Complexity |
|-----------|--------|------------|
| Access | arr[i] | O(1) |
| Search | arr.indexOf(x) | O(n) |

## Common Patterns

### Pattern 1
```code
// Code snippet

使用する場面：[説明]

パターン 2

// Code snippet

使用する場面：[説明]

注意点

• ⚠️ [よくある間違い 1]
• ⚠️ [よくある間違い 2]

### 10. Document Maintenance

**Version control:**
- Use git to track changes
- Write meaningful commit messages
- Keep documents up to date with code

**Cross-references:**
- Link related documents
- Reference source code files
- Point to external resources

**Validation:**
- Check all links work
- Verify code examples compile
- Test complexity analysis accuracy

## Project-Specific Guidelines

**For CS_basics repository:**

- **Cheatsheets** live in `doc/cheatsheet/` and follow the Cheatsheet Style Guide in
  `CLAUDE.md` (Skeleton A/B, the mandatory Scope line, a `data/cheatsheet_meta.json`
  entry). Use `/lc-cheatsheet` for them; this skill is for everything else.
- **FAQs** live in `doc/faq/` and have a zh overlay; use `/lc-faq-add`.
- **System design** docs follow `system_design/00_template.md`.

## Quality Checklist

Before finalizing documentation:
- [ ] Clear title and description
- [ ] Proper heading hierarchy
- [ ] Code examples tested and working
- [ ] Complexity analysis included
- [ ] Consistent formatting
- [ ] No broken links
- [ ] Spell-checked
- [ ] Follows project conventions
- [ ] Related content linked

## Tools & References

**Markdown validation:**
- Check syntax with markdown linters
- Preview before committing
- Use consistent line breaks

**Useful symbols:**
- ✅ Checkmark for correct approach
- ❌ X for incorrect approach
- ⚠️ Warning for gotchas
- 💡 Bulb for tips
- 📝 Note for important points