From 3872c2a8d0d4c76bb368a1272b4ebefaeb6ceee1 Mon Sep 17 00:00:00 2001 From: tkc Date: Thu, 17 Sep 2026 17:22:04 +0900 Subject: [PATCH] docs: collect work as issues during the day, clear it in one sitting Stopping mid-task to fix what you just noticed costs more than the fix. This writes down the alternative that has been happening informally: capture in one line during the day, triage and clear in the evening. The repository had no CLAUDE.md, so every fresh agent -- and every @claude run, if one is ever set up -- rediscovers the rules or ignores them. Anthropic's own best-practices section names this as the first thing to fix, so CLAUDE.md now carries the six that actually bite here: the scope test from the README, rules-in-config rather than in the binary, branch-PR-CI-squash with no commits to main, English commits with Japanese docs, measure before diagnosing (which has caught the real cause every time reasoning from the code missed it), and the test conventions. The issue templates are deliberately thin, with blank issues left enabled. A template that demands reproduction steps and an environment raises report quality and lowers capture rate, and an idea that is not captured in the moment is gone. Quality is added at triage instead. docs/issue-workflow.md is the procedure, and records what was taken from how others run this: issues as a coordination surface independent of the working tree, one issue per branch because several agents editing one plan file is the most common source of silent corruption, and templates as a way to cut round trips. It also covers what auto-continue at usage limit means for evening work, and where handing an issue to @claude is and is not appropriate. No GitHub Action workflow is included. It needs a secret only the owner can add and spends Actions minutes and tokens on every run, so the setup steps are documented and the decision left open. Co-Authored-By: Claude Opus 5 (1M context) --- .github/ISSUE_TEMPLATE/bug.yml | 30 +++++++ .github/ISSUE_TEMPLATE/config.yml | 3 + .github/ISSUE_TEMPLATE/feature.yml | 27 ++++++ CLAUDE.md | 63 ++++++++++++++ README.md | 1 + docs/issue-workflow.md | 130 +++++++++++++++++++++++++++++ 6 files changed, 254 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature.yml create mode 100644 CLAUDE.md create mode 100644 docs/issue-workflow.md diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..0ccc034 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,30 @@ +name: 不具合 +description: 動きがおかしい +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + 思いついた時点で 1 行だけでも構いません。足りない分は消化するときに埋めます。 + - type: textarea + id: what + attributes: + label: 何が起きたか + placeholder: ⌘W でセッションが閉じない + validations: + required: true + - type: textarea + id: evidence + attributes: + label: 手がかり + description: | + あれば。スクリーンショット、または記録の 1 行。 + `TERMIT_FRAME_LOG=1 RUST_LOG=info termit`（描画・読み取り） + `TERMIT_KEYLOG=/tmp/keys.log termit`（押したキーとその解釈） + placeholder: | + 描く面を取れなかった: 間に合わず=0 隠れて=26 作り直し=0 + - type: input + id: build + attributes: + label: どの版か + placeholder: v0.1.0 / main の 920b7ad diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..afdca7d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,3 @@ +# 空の issue を残す。思いついたことを 1 行で放り込めないと、 +# 昼のあいだに捕まらず、そのまま消える。 +blank_issues_enabled: true diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml new file mode 100644 index 0000000..2b0e6b0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -0,0 +1,27 @@ +name: ほしい機能 +description: できるようにしたいこと +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + 思いついた時点で 1 行だけでも構いません。 + - type: textarea + id: problem + attributes: + label: 困っていること + description: 解決策ではなく、困りごとのほうを書きます。作り方は消化するときに決めます。 + placeholder: エージェントが 6 本動いていると、どれが返事待ちか分からない + validations: + required: true + - type: dropdown + id: scope + attributes: + label: 端末の仕事か + description: | + termit は「プロセスを起こす・PTY を中継する・エスケープ列を解釈する・描く」までを担います。 + 迷ったら「わからない」で構いません。消化するときに一緒に考えます。 + options: + - 端末の仕事だと思う + - 端末の外でもできるかもしれない + - わからない diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..156aa5f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,63 @@ +# termit + +A macOS terminal for working with coding agents. Rust, one binary, no runtime. + +## Scope + +termit spawns processes, relays the pty, interprets escape sequences and draws +the result. It does not manage conversations, drive an agent, or run workflows. +Anything that needs the terminal to understand what an agent is *doing* belongs +outside it. + +Before adding a feature, read `## Why` and `## Not goals` in the README. If the +change does not fit them, say so rather than quietly widening the scope. + +## Rules live in config, not in the binary + +Nothing in the code knows what Claude Code or Codex look like. Agent state is +matched against `[agent]`, paste redaction against `[paste]`. When an upstream +tool changes its wording, the fix is a config edit, not a release. Keep it that +way: if you are about to hard-code a vendor's key shape or prompt text, put it +in a default table instead. + +## Workflow + +- Branch, then PR, then wait for CI, then `gh pr merge --squash --delete-branch`. + **Never commit to `main`.** +- Commit messages and PR bodies in **English**. Code comments and `docs/` in + **Japanese**. +- One issue, one branch, one PR. + +## Measure before you diagnose + +Reasoning from the code has produced the wrong cause more than once here; a +measurement has found it every time. Build the measurement first. + +| Tool | What it answers | +|---|---| +| `TERMIT_FRAME_LOG=1` with `RUST_LOG=info` | per-frame timings, surface failures by reason, which rows were drawn | +| `--bench` | cost of building and submitting a frame | +| `--throughput` | how fast bytes from the pty are consumed | +| `--latency-test` | input round trip, no keyboard needed | +| `--probe out.png` | render one frame offscreen (screen capture is blocked here) | +| `--keytest` | what a key press actually arrives as | + +State what you measured. If you could not measure something, say that instead +of estimating and presenting it as a result. + +## Tests + +Tests sit next to the thing they cover and are named in Japanese, as sentences +about behaviour. Prefer a pure function over a test that needs a window or a +pty: `secret.rs` and `input.rs` are testable because the decisions were pulled +out of the event loop. + +Before claiming a fix works, run `cargo test`, `cargo clippy --all-targets -- +-D warnings` and `cargo fmt --check`, and check that the new test fails when +the fix is reverted. + +## Docs + +`docs/references/*.md` record what other implementations do and which parts +termit took, with the reason for each rejection. Add to them when you research +something rather than leaving it in a PR body. diff --git a/README.md b/README.md index 69cdeb6..73a7c9a 100644 --- a/README.md +++ b/README.md @@ -467,6 +467,7 @@ The detailed design record is in Japanese. - [`docs/superpowers/specs/2026-09-08-agent-terminal-design.md`](docs/superpowers/specs/2026-09-08-agent-terminal-design.md) — the specification - [`docs/performance.md`](docs/performance.md) — where the time actually goes, measured - [`docs/references/performance-techniques.md`](docs/references/performance-techniques.md) — techniques taken from other terminals, each marked adopted, rejected with the measurement, or still open +- [`docs/issue-workflow.md`](docs/issue-workflow.md) — collecting work as issues during the day and clearing them in one sitting - [`docs/references/paste.md`](docs/references/paste.md) — what iTerm2 does at the paste boundary, and which half of it termit took - [`docs/references/agent-state.md`](docs/references/agent-state.md) — how other tools tell a working agent from one that is waiting for you, and which parts of that termit adopted - [`docs/references/sandbox.md`](docs/references/sandbox.md) — how agents are sandboxed elsewhere, what Apple's `container` measured at, and what termit deliberately leaves outside diff --git a/docs/issue-workflow.md b/docs/issue-workflow.md new file mode 100644 index 0000000..ba5b32b --- /dev/null +++ b/docs/issue-workflow.md @@ -0,0 +1,130 @@ +# issue の貯め方と消化のしかた + +作成日：2026-09-17 + +思いついたことを昼のあいだ issue に貯め、夕方以降にまとめて片づける。 +その形にした理由と、実際の手順。 + +## なぜ貯めるのか + +**手を止める費用のほうが高い。** 端末を使っている最中に「⌘W が効かない」と気づいて +そのまま直しはじめると、元の作業の文脈が失われる。気づきは 10 秒で捨てられる場所に +置き、直すのはまとめてやるほうが、一日の総量が増える。 + +**夕方に寄せる理由が 2 つある。** 利用の上限は時間で回復するので、日中に使い切っても +夕方には戻っている。そして Claude Code は、**セッションを開いたままにしておけば +回復した時点で自分から作業を拾い直す**（`autoContinueAtUsageLimit`、既定で有効）。 +待っているあいだに終了・再起動すると、その予約は消える。 + +**issue に置く理由。** 作業ツリーから独立している。ブランチを切り替えても、 +機械を変えても、一覧はそこにある。手元の TODO ファイルだと、 +複数のエージェントが同じ行を書き換えて壊す。これは並行作業での破損の最大要因である。 + +## 昼：捕まえるだけ + +**1 行でよい。** 分類も再現手順も要らない。 + +```sh +gh issue create --title "⌘W でセッションが閉じない" +``` + +型（`.github/ISSUE_TEMPLATE/`）はわざと軽くしてある。空の issue も許してある。 +**捕まえる手間が重いと、昼のあいだに捕まらず、そのまま消える。** + +手がかりがその場にあるなら貼る。あとで再現するより、そのときの 1 行が速い。 + +```sh +# 描画・読み取りの記録 +RUST_LOG=info TERMIT_FRAME_LOG=1 termit +# 押したキーと、その解釈 +TERMIT_KEYLOG=/tmp/keys.log termit +``` + +## 夕方その 1：仕分ける + +消化の前に、**全部まとめて 15 分**で仕分ける。1 件ずつ着手しながら考えない。 + +```sh +gh issue list --state open +``` + +各件について 3 つだけ決める。 + +1. **そのまま着手できるか。** できないなら、足りないのは何か。 + 多くは「測っていない」である。ここで測る。**原因の見当をコードから立てない** —— + このリポジトリでは、それで 2 回外している（`docs/performance.md` 7.9、 + Docker 経由のコピーの件）。 +2. **termit の仕事か。** 端末の責務を超えるものは、超えると書いて閉じる。 + 閉じた理由は残す。同じ提案がまた来る。 +3. **順番。** 直したものが次の土台になる並びにする。 + +仕分けの結果は issue のコメントに書く。夕方の自分と、明日のエージェントが読む。 + +## 夕方その 2：消化する + +**1 issue = 1 ブランチ = 1 PR。** 1 本の PR に 2 件入れない。片方で CI が落ちると +両方止まる。レビューもできない。 + +```sh +git checkout -b fix-close-on-cmd-w +# 直す。テストを先に落としてから直す。 +cargo test && cargo clippy --all-targets -- -D warnings && cargo fmt --check +gh pr create --title "..." --body "... Closes #12" +gh pr checks --watch +gh pr merge --squash --delete-branch +``` + +本文に `Closes #12` と書くと、マージで issue が閉じる。手で閉じない。 + +**並行してやるなら worktree を使う。** 同じ作業ディレクトリで 2 本動かすと、 +互いのファイルを踏む。 + +```sh +git worktree add ../termit-issue-12 -b fix-issue-12 +``` + +**止まったら、止まったと書く。** 分かったことを issue に残して次へ行く。 +半端な PR を開いたままにしない。 + +## 自動に任せる場合 + +`@claude` に投げる形もある。導入は `claude` の中で `/install-github-app` +（`gh` の認証が済んでいること、リポジトリの管理権限が要る）。秘密鍵として +`ANTHROPIC_API_KEY` か `CLAUDE_CODE_OAUTH_TOKEN`（`claude setup-token` で作る）が +リポジトリに入る。以後、issue やコメントで `@claude …` と書けば、Claude が +読んで PR まで作る。 + +**このリポジトリには workflow を置いていない。** 秘密鍵が要り、走らせれば +その都度 GitHub Actions の時間とトークンを使う。導入するかは持ち主が決めることなので、 +手順だけ書いてある。 + +入れる場合に効く制限（費用が青天井にならないようにする）。 + +- `claude_args: --max-turns 5` +- workflow に `timeout-minutes` +- `concurrency` で同時実行を絞る +- **型で文脈を先に渡す。** 往復が減るぶん、そのまま費用が減る + +**線引き。** 自動に向くのは、正解が機械で確かめられるもの（テストが落ちている、 +lint が落ちている、綴りの直し）。向かないのは、**何を作るべきかの判断が要るもの**。 +termit では後者が多い。上の「termit の仕事か」を機械に決めさせない。 + +## 他所から取ったこと + +| 取ったこと | 出どころ | +|---|---| +| issue を、作業ツリーから独立した調整面として使う | 複数エージェント運用の通例 | +| 1 つの計画ファイルを複数で編集しない（= 1 issue 1 ブランチ） | 並行作業での破損の最大要因として報告されている | +| `CLAUDE.md` に規範を置き、簡潔に保つ（毎回読まれる） | [GitHub Actions の推奨](https://code.claude.com/docs/en/github-actions#best-practices) | +| 型で文脈を先に渡して往復を減らす | 同上（費用の節に明記されている） | +| 調べる → 決める → 作る → 見直す → 出す | 主要な運用手順に共通する形 | + +**取らなかったもの：重い型。** 再現手順・期待結果・環境を必須にする型は、 +報告の質は上がるが、**思いつきを捨てる場所としては重すぎる**。 +このリポジトリは一人で回しているので、質は夕方の仕分けで上げるほうが合う。 + +## 参考 + +- [Claude Code GitHub Actions](https://code.claude.com/docs/en/github-actions) +- [claude-code-action の例](https://github.com/anthropics/claude-code-action/tree/main/examples) +- [Git worktrees と並行エージェント](https://www.developersdigest.tech/blog/git-worktrees-claude-code-parallel-agents-guide)