TaskJuggler Playground

TaskJuggler 3.8.4 を段階的に学ぶためのサンプル集。

各段階に実際に動く .tjp と、その段階の解説を置いてある。
条件だけを変えた比較になるよう作ってあるので、読むだけでなく数値の差で確認できる。

各段階のページには、解説・tj3 が生成したレポート・tjp のソースがまとまっている。
環境を用意しなくてもブラウザだけで読み進められる。

公開サイト: https://takumi.tmfam.com/task-juggler-playground/
リポジトリ: https://github.com/takumin/task-juggler-playground
手元で動かす手順・サイトの組み立て方:
DEVELOPMENT.md

学習ロードマップ

各段階に詳しい解説がある。番号順に進めるのが前提。

#	段階	概要
01	基礎	プロジェクト宣言からレポート出力までの最小の一往復。`effort` / `duration` / `length` の違いを押さえる
02	構造	タスクをツリーに組み、依存を張る。`!` `!!` 絶対パスの参照記法とマイルストーン
03	リソース	「誰が」を精密に表現する。複数割当・`efficiency`・`limits`・代替リソース
04	カレンダー	「いつ働けるか」の定義。稼働時間・祝日・休暇・シフト。日本の営業日を扱う
05	制約	スケジューラへの指示。ASAP/ALAP・日付固定・`priority` による競合解決・事後検査
06	進捗と実績	実績を入れて残作業を再計算させる。`booking` と `complete` の使い分け
07	レポート	出力の作り分け。列のカスタマイズ・CSV・時系列集計・ページ合成
08	フィルタ	論理式で「何を出すか」を絞る。組み込み関数とスコープ評価
09	シナリオ	同じ計画を条件違いで同時にスケジュールし、横並びで比較する
10	コスト	工数計画から原価と収支を出す。勘定科目・単価・按分
11	モジュール化	規模が大きくなったときのファイル分割。マクロ・`supplement`・独自属性
12	運用	状況記録・報告書の自動生成・タイムシート。継続運用に乗せる

段階のつながり

01〜02 が文法の骨格
03〜06 で計画を現実に近づける
07〜09 が出力と分析の層 (07 でレポートの器、08 でその中身を絞る、という対の関係)
10〜12 が規模と運用の層

06 の実績追跡は 09 のシナリオ機能の上に乗っており、
06 で実績を扱ってから 11 の supplement に進むと、
計画と実績を分離する実務パターンの意味が腑に落ちる。

用語メモ

effort — 人的工数。担当者が割り当たって初めて期間が決まる。担当が増えれば期間は縮む
duration — 暦時間ベースの期間。担当者に依存しない (待ち時間、外部レビュー期間など)
length — 稼働日ベースの期間。休日は数えないが、担当者の負荷には依存しない

リファレンスの引き方

構文は推測せずに必ず引く。公式マニュアルがそのまま 3.8.4 のリファレンスになっている。

TaskJuggler User Manual — 全 266 キーワード
columnid — レポートで使える列の一覧
task — task の属性一覧 ([sc] = シナリオ固有)

各段階の「学ぶ内容」に挙げたキーワードは、公式マニュアルの該当ページへリンクしてある。
冒頭に Warning が出るキーワードは非推奨か未テスト。

横断的なハマりどころ

段階固有の注意点は各段階の「ハマりどころ」に書いてある。
ここには複数段階にまたがるものと、段階をまたいで引きたい索引
(「書く場所」「非推奨・未テストのキーワード」) を置く。

日付とタイムゾーン

project ヘッダの日付は timezone 属性を読む前に解釈されるため UTC 基準になる。
timezone "Asia/Tokyo" を指定していても project x "..." 2026-08-03 +2m の開始は
2026-08-03 09:00 JST になり、booking や start で 8/3 0:00 を指すと
「must be within the project time frame」エラーになる。

対処: プロジェクト開始を前の週末側に広げる (06 と 10 はこの方法をとっている)。

区間指定の終了日は 0 時に展開されるため、終了日当日は含まれない。
2026-08-13 - 2026-08-17 は 8/13〜8/16 の 4 日間になる。
leaves の期間 (04) にも booking の期間 (06) にも同じ規則が効く。

書く場所

要素	書く場所
`leaves`	トップレベル (properties スコープ)。`project {}` の中ではない
`extend` / `scenario` / `trackingscenario`	`project {}` の中
`balance`	トップレベル、またはレポートの中
`include`	タスク定義の中には書けない。`taskprefix` 付きでトップレベルに置く

論理式 (05・07・08 で共通)

比較演算子は & | より結合が弱い。比較は必ず括弧で囲む
属性はシナリオ ID 付きで参照する (plan.effort)。非シナリオ属性でも必要
関数に渡すタスク ID はルートからのフルパス。
短く書くとエラーも出ないまま結果が空になる

レポート出力

レポート名 (第2引数) は拡張子なしで書く。拡張子は formats の指定から自動で付く。
書き足すと overview.html.html のように二重になる
export と timesheetreport は outputdir が効かない。
他のレポートが outputdir に従ってもこの 2 つは無視するので、
出力先を揃えたいならレポート名側にパスを書く (07 と 12 の教材はこの形)。
拡張子は formats ではなく決め打ち (export は中身に応じて .tjp / .tji、
timesheetreport は .tji) だが、自動で付く点は同じ

非推奨・未テストのキーワード

非推奨: shift.resource (→ shifts)、projection (booking があれば自動)、vacation (→ leaves)
未テスト警告つき: effortdone / effortleft、leaveallowance、accountreport、
formats.export、alertlevels