Skip to content

Add CLAUDE.md and check in the project-level .claude configuration - #896

Open
yutaro-sakamoto wants to merge 8 commits into
opensourcecobol:developfrom
yutaro-sakamoto:claude/add-claude-md-guide-develop
Open

Add CLAUDE.md and check in the project-level .claude configuration#896
yutaro-sakamoto wants to merge 8 commits into
opensourcecobol:developfrom
yutaro-sakamoto:claude/add-claude-md-guide-develop

Conversation

@yutaro-sakamoto

@yutaro-sakamoto yutaro-sakamoto commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

概要

Claude Code のプロジェクト設定をリポジトリに登録する。これまで各開発者のマシンにしか無かったもので、cloneした人が同じ手順・同じ注意事項で作業を始められるようにする。

  • CLAUDE.md を追加。ビルド手順とその落とし穴（sandbox無効化、UTF-8ビルド時の touch cobj/*.m4、Makefile.in/configure を手で編集しないこと、autoreconfの出力確認）、テストの方針、./format の実行、サブエージェントの使い分け、gitの注意点、フォルダ構成をまとめている。
  • .claude/ を追加。サブエージェント5つ（cobj-explorer / ci-triage / commit-preflight / code-reviewer / docs-sync-inspector）、スラッシュコマンド3つ、スキル5つ、ファイル種別ごとの注意事項を書いた rules/ 5つ、./format を自動実行するStopフックを含む。
  • .gitignore に .claude-work/（作業用ディレクトリ）、local/（make install のインストール先）、wt/（git worktreeの置き場）、.claude/settings.local.json（個人設定）を追加。local/ と wt/ はこれまで除外されておらず、git status に出続けていた。

設定ファイルの分割

  • .claude/settings.json（リポジトリ管理）: 共有してよい設定。skillOverrides、sandboxの設定、読み取り系コマンドの許可リスト、./format を走らせるStopフック。フックのパスは $CLAUDE_PROJECT_DIR 経由で解決するため、cloneした場所に依存しない。
  • .claude/settings.local.json（.gitignore で除外）: デスクトップ通知の実行ファイルや絶対パス、個人のMCPサーバなど、マシン固有の設定。

マシン固有の記述は取り除いてある。個人のリモート名やフォークURLの決め打ちをやめて git remote -v で確認する形にし、ブランチ名の決め打ちもやめてデフォルトブランチを実行時に解決するようにした。ESQLテストの手順は、特定マシンのPostgreSQLのインストール先・DBユーザ・ソケットパス・ポートを前提としない書き方に直してある。

作業用ディレクトリ

.claude-work/ をリポジトリルート直下に定め、タスク定義・調査メモ・一時スクリプト・CIログの退避・動作確認用の書き捨てCOBOLなど、成果物ではないファイルの置き場をここに統一した。local/ と wt/ は同じく .gitignore で除外するが作業用ディレクトリではない（wt/ は未コミットの変更を含む本物のチェックアウトである）ことを明記している。

動作への影響

ドキュメントと Claude Code の設定のみの追加で、既存ファイルの変更は .gitignore の12行だけ。cobj/ libcobj/ tests/ などの製品コードとビルド構成には一切触れていない。

補足

.claude/skills/local-pr は「自分のフォークで先にCIを回す」という運用のためのスキルで、上流では使わない。不要であれば削除して構わない。

Summary

This PR checks in the Claude Code project configuration, which until now lived only on individual developers' machines, so that anyone who clones the repository starts with the same build steps and the same caveats.

  • Adds CLAUDE.md: build commands and their pitfalls (disabling the sandbox, touch cobj/*.m4 for UTF-8 builds, never hand-editing Makefile.in/configure, reviewing autoreconf output before committing), the testing policy, running ./format, when to use each subagent, git caveats, and the directory layout.
  • Adds .claude/: five subagents (cobj-explorer, ci-triage, commit-preflight, code-reviewer, docs-sync-inspector), three slash commands, five skills, five rules/ files with per-file-type caveats, and a Stop hook that runs ./format.
  • Adds .claude-work/, local/, wt/, and .claude/settings.local.json to .gitignore. local/ and wt/ were never ignored, so they showed up in git status.

Settings split

Shared options live in .claude/settings.json (tracked): skillOverrides, the sandbox settings, an allowlist of read-oriented commands, and the Stop hook, whose path resolves through $CLAUDE_PROJECT_DIR so it does not depend on where the repository is cloned. Machine-specific settings stay in .claude/settings.local.json, which is gitignored.

Machine-specific content was stripped: hardcoded personal remote names and fork URLs give way to checking git remote -v, hardcoded branch names give way to resolving the default branch at run time, and the ESQL instructions no longer assume one machine's PostgreSQL installation path, database user, socket path, or port.

Working directory

.claude-work/ at the repository root is now the single place for files that are not deliverables: task definitions, investigation notes, throwaway scripts, saved CI logs, and scratch COBOL used to inspect generated Java. local/ and wt/ are ignored too but are explicitly not scratch space — wt/ holds real checkouts with uncommitted work.

Impact

Documentation and Claude Code configuration only. The sole change to an existing file is 12 lines in .gitignore. No product code or build configuration under cobj/, libcobj/, or tests/ is touched.

Note

.claude/skills/local-pr supports a workflow of running CI on a personal fork first; it is not useful upstream and can be dropped if you prefer.

🤖 Generated with Claude Code

https://claude.ai/code/session_01S8etHNhhErc4UwGDkW7HTe

@claude
Add CLAUDE.md with development guide
d0cf5f4 
Document build procedures and pitfalls, test workflow, subagent usage,
git conventions, and the repository directory layout.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S8etHNhhErc4UwGDkW7HTe
@claude
Add .claude configuration to the repository
26169f3 
Register the project-level Claude Code configuration (agents, commands,
rules, skills, the format-on-stop hook, and shared settings) so that every
clone and worktree picks it up.

Machine-specific content was removed or generalized:
- Split settings: shared options live in .claude/settings.json with the
  Stop hook resolved through $CLAUDE_PROJECT_DIR; the personal
  settings.local.json (desktop notification commands, absolute paths,
  personal MCP server) is gitignored instead.
- ci-triage no longer hardcodes personal git remote names.
- The ESQL rule no longer assumes one machine's PostgreSQL install,
  database user, socket path, or port.
- The worktree skill and command drop the symlink workaround, which is
  unnecessary now that .claude/ is tracked.
- The PR skills no longer point at a personal fork URL or a stale
  pull request number, and gained the frontmatter they were missing.

CLAUDE.md is updated to match the new settings file name and the fact
that .claude/ is now tracked.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S8etHNhhErc4UwGDkW7HTe
@claude
Add docs-sync-inspector agent and generalize the git remote notes
55ab92e 
- Register the docs-sync-inspector agent definition, which CLAUDE.md and
  the fix-skipped-test command already referred to.
- List it in the CLAUDE.md agent table and correct the claim that every
  agent is read-only: this one edits documentation.
- Replace the personal remote names in CLAUDE.md with instructions to
  check git remote -v, keeping only the upstream repository and the role
  a fork plays.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S8etHNhhErc4UwGDkW7HTe
@claude
Write the docs-sync-inspector description in Japanese
0d0f97e 
The description mixed English prose with Japanese example dialogues.
Make it Japanese throughout, matching the other agent definitions.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S8etHNhhErc4UwGDkW7HTe
@claude
Give Claude a single, declared working directory
c25bb7c 
Skills and commands scattered their scratch files across the repository
root (task.md), /tmp, and other ad hoc places. Declare one directory,
.claude-work/ at the repository root, as the place for files that are not
deliverables, and point everything that used a scratch path at it.

- .gitignore: ignore /.claude-work/, and also /local/ and /wt/, which were
  never ignored even though the build and the worktree skills create them.
- .claude/settings.json: declare CLAUDE_WORK_DIR and pre-approve mkdir and
  rm under .claude-work/ only.
- CLAUDE.md: document the directory, and state explicitly that local/ and
  wt/ are ignored but are NOT scratch space - wt/ holds real checkouts with
  uncommitted work.
- setup-worktree writes .claude-work/task.md and fix-skipped-test reads it
  from there.
- The ESQL rule puts its PostgreSQL cluster under .claude-work/, keeping
  the Unix socket in /tmp because of the 107-byte path limit.
- commit-preflight checks that nothing from .claude-work/ leaks into a diff.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S8etHNhhErc4UwGDkW7HTe
@claude
Refer to the default branch instead of naming develop or main
7ed0f34 
The branch names in these instructions came from whatever the default
branch happened to be at the time, so they break when a repository uses a
different one. Say "default branch" and resolve it at run time:
git remote show <remote> for the HEAD branch, or gh repo view
--json defaultBranchRef.

Covers the pr and local-pr skills, the setup-worktree command, and the git
section of CLAUDE.md.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S8etHNhhErc4UwGDkW7HTe
@claude
Route the remaining scratch files through .claude-work
6034454 
Four places still wrote Claude's temporary files outside the declared
working directory:

- CLAUDE.md named task.md without its directory. Spell out
  .claude-work/task.md, and mention CI artifacts and throwaway COBOL in
  the same list.
- cobj-explorer suggested writing a small COBOL program to inspect the
  generated Java without saying where; it landed in the repository root.
- ci-triage ran gh run download without -D, which unpacks the artifact
  into the current directory.
- The format-on-stop hook kept its timestamp in .git/. Move it to
  .claude-work/format-stamp so all Claude-owned state lives in one place;
  losing it only costs one extra ./format run.

Also note in the ESQL rule that PGDIR is per-worktree while the socket
directory and port are not, so concurrent worktrees must vary them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S8etHNhhErc4UwGDkW7HTe
@claude
Allow running the tests for a change locally before pushing
ac88094 
The testing section read as an absolute rule that tests run only in CI.
Keep CI as the default for the whole suite, but say that running just the
test cases covering the change beforehand is a legitimate choice, and when
it pays off (iterating on a fix, small changes where a CI round trip
costs more) versus when it does not (build configuration, character
encoding, cross-OS differences).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S8etHNhhErc4UwGDkW7HTe

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@yutaro-sakamoto @claude