# 指令檔開頭「用途／更新時間」標頭範本

本範本定義 doc-funcs 第 3-2 步指令檔草稿開頭必備的註解區塊格式。「用途」與「更新時間」必須包在同一個註解區塊內，不得拆成兩個分開的區塊；此標頭屬於檔案說明標頭（含外框分隔線），實作與後續輸出訊息格式正規化時必須原樣保留，不得移除或轉成 `階段` 前綴。

## 佔位符

- `{用途說明}`：一到三行，說明這份指令檔做什麼、在什麼情境被呼叫、重要副作用；多行時每行開頭都要有註解符號。
- `{更新時間}`：台灣時區（Asia/Taipei），固定格式 `yyyy/MM/dd HH:mm:ss`，可用下列指令取得：

  ```bash
  TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S'
  ```

## 變體 A：`#` 註解（`*.sh`、`*.bash`、`*.ps1`、`Makefile`、yaml、`Dockerfile`、docker-compose）

```
# ============================================================================
# 用途：{用途說明}
# 更新時間：{更新時間}
# ============================================================================
```

填入後範例：

```bash
#!/usr/bin/env bash
# ============================================================================
# 用途：打包 Web 專案並上傳部署壓縮檔至部署主機，供 CI 部署階段呼叫。
# 更新時間：2026/07/15 14:30:00
# ============================================================================
```

## 變體 B：`::` 註解（`*.bat`、`*.cmd`）

```
:: ===========================================================================
:: 用途：{用途說明}
:: 更新時間：{更新時間}
:: ===========================================================================
```

填入後範例：

```bat
@echo off
:: ===========================================================================
:: 用途：清理建置輸出目錄並重新建置方案，供本機開發快速重建使用。
:: 更新時間：2026/07/15 14:30:00
:: ===========================================================================
```

（改用 `REM` 亦可，但同一份檔案內擇一使用並保持一致。）

## 放置規則

- 標頭放在檔案最前面；若第一行是必須位於首行的宣告（例如 shebang `#!...`、`@echo off`），標頭緊接在其後。
- yaml 檔若有 document marker（`---`），`#` 標頭放在 `---` 之前即可。
- 外框分隔線長度不強制，但上下外框必須成對出現，且整個標頭（含外框）視為同一個註解區塊。
- 「用途」與「更新時間」兩行的中文標籤與順序依本範本，不得只留其中一項。