0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

一覧表は手で書かない:Markdown の frontmatter を正典にして README の進捗表を自動生成する

0
Posted at

はじめに

文学部の大学 2 年です。コンテストや懸賞論文への応募を、Claude Code を何本も並べて同時に進めています。管理しているタスクは常に数十件あります。

最初は README.md に進捗の表を手で書き、各タスクのフォルダにも status.md を置いていました。すると、すぐにこうなりました。

  • フォルダの status.md は「提出済」なのに、README の表は「作業中」のまま
  • 2 つのエージェントが同時に README の表を書き換えて、片方の更新が消える
  • 締切順に並べ直すのを誰もやらない

原因は単純で、同じ事実を 2 か所に手で書いている からです。そこで「状態の正典は各フォルダの status.md の先頭だけ。README の表はそこから生成する」に変えました。50 行ほどの Python で済みます。

仕組み

tasks/
├── essay/status.md     ← 先頭の --- の間が正典
├── poster/status.md
└── old/status.md
README.md               ← マーカーの間だけ自動生成。外側は手書きのまま

各 status.md の先頭に、YAML 風の key: value を置きます。

tasks/poster/status.md
---
name: ポスター
due: 2026-11-30
state: 作業中
decision: 縦長か横長か
next: 案を2つ出す
---

# ポスター

(ここから下は経緯やログを自由に書く)

README には、生成する範囲のマーカーだけを置きます。

README.md
# 一覧

<!-- index:begin -->
<!-- index:end -->

## メモ
手書き部分(スクリプトは触らない)

コード

build_index.py
#!/usr/bin/env python3
"""tasks/*/status.md の先頭メタ(--- で囲んだ key: value)から、
README.md のマーカーの間に一覧表を作り直す。一覧表は手で編集しない。

usage: python build_index.py [ルート]
"""
import pathlib
import re
import sys

ROOT = pathlib.Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
INDEX = ROOT / "README.md"
BEGIN, END = "<!-- index:begin -->", "<!-- index:end -->"
CLOSED = {"done", "dropped"}


def meta(path):
    m = re.match(r"---\n(.*?)\n---\n", path.read_text(encoding="utf-8"), re.S)
    if not m:
        return None
    d = {}
    for line in m.group(1).splitlines():
        if ":" in line:
            k, v = line.split(":", 1)
            d[k.strip()] = v.strip()
    d["dir"] = path.parent.name
    return d


rows = [d for p in sorted(ROOT.glob("tasks/*/status.md")) if (d := meta(p))]
rows.sort(key=lambda d: d.get("due") or "9999")  # ISO の日付は文字列のまま並べ替えられる
link = lambda d: f"[{d.get('name', d['dir'])}](tasks/{d['dir']}/status.md)"

out = [BEGIN, "<!-- build_index.py が生成。直接編集しない。 -->", ""]

wait = [d for d in rows if d.get("decision") and d.get("state") not in CLOSED]
out += ["## 判断待ち", "", "| 期限 | タスク | 決めること |", "|---|---|---|"]
out += [f"| {d.get('due', '')} | {link(d)} | {d['decision']} |" for d in wait] or ["| — | なし | — |"]

out += ["", "## 進行中", "", "| 期限 | タスク | 状態 | 次の一手 |", "|---|---|---|---|"]
out += [f"| {d.get('due', '')} | {link(d)} | {d.get('state', '')} | {d.get('next', '') or '—'} |"
        for d in rows if d.get("state") not in CLOSED]

text = INDEX.read_text(encoding="utf-8")
if BEGIN not in text:
    sys.exit("README.md にマーカーがありません")
text = re.sub(re.escape(BEGIN) + ".*?" + re.escape(END), lambda _: "\n".join(out + ["", END]), text, flags=re.S)
INDEX.write_text(text, encoding="utf-8", newline="\n")
print(f"{len(rows)} 件(判断待ち {len(wait)})")

標準ライブラリだけで動きます(:= を使うので Python 3.8 以上)。

実行結果

$ python build_index.py
3 件(判断待ち 1)
README.md(生成後)
# 一覧

<!-- index:begin -->
<!-- build_index.py が生成。直接編集しない。 -->

## 判断待ち

| 期限 | タスク | 決めること |
|---|---|---|
| 2026-11-30 | [ポスター](tasks/poster/status.md) | 縦長か横長か |

## 進行中

| 期限 | タスク | 状態 | 次の一手 |
|---|---|---|---|
| 2026-11-30 | [ポスター](tasks/poster/status.md) | 作業中 | 案を2つ出す |
| 2026-12-10 | [懸賞論文](tasks/essay/status.md) | 作業中 | 第3章を書く |

<!-- index:end -->

## メモ
手書き部分(スクリプトは触らない)

state: done のタスクは表から消え、締切の近い順に並びます。

効いた小さな決まり

decision は「まだ決まっていない論点」だけを書く

decision: に値が入っているタスクは「判断待ち」の表に出ます。決まったら空にして、決まった内容は本文のログへ移します。こうすると「人間が見るべきもの」が表の一番上に必ず集まり、自分は朝そこだけ見れば済むようになりました。

日付は ISO(2026-11-30)で書く

2026-11-30 や 2026-11-30T23:59 は、文字列のまま sort しても時系列順になります。日付のパースを書かずに済み、12/1 と 11/30 の並びがおかしくなる事故もありません。表示用の「12/31(必着)」のような文字列が欲しければ、due_label: を別に持たせます。

re.sub の置換は関数で渡す

置換後の文字列に \1 や \g のような並びが混じると、re.sub がそれを後方参照として解釈して落ちます。タスク名や URL にバックスラッシュが入ることもあるので、lambda _: ... で渡して「そのまま入れる」ようにしています。

生成は 1 人だけがやる

複数のエージェントを同時に動かす場合、各エージェントは自分の status.md だけを書き、build_index.py は流しません。全員が終わったあとに取りまとめ役が 1 回だけ流します。生成物を同時に書き換えなければ、競合も上書きも起きません。

YAML ライブラリを使わない理由

PyYAML で読むほうが正攻法ですが、あえて key: value の 1 行ずつの分割にしています。

  • decision: 縦長か横長か: 要相談 のようにコロンが重なっても、最初のコロンで切るだけなので壊れない
  • due: 2026-11-30 が datetime.date に化けず、文字列のまま比較できる
  • 依存がゼロなので、どの環境のエージェントからでも流せる

入れ子の構造が要らないなら、これで十分でした。

おわりに

「一覧表を手で直す」作業は、件数が増えるほど確実に破綻します。正典を 1 か所に決め、表示はそこから作るだけで、表の食い違いは起きなくなりました。人間もエージェントも、書くのは自分のファイルの先頭の数行だけです。タスク管理ツールを入れるほどではない規模の個人プロジェクトに、おすすめです。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?