スキップしてメイン コンテンツに移動

Streamlining Claude Code Projects: The Design Philosophy Behind dotclaude-template

Are you experiencing challenges as your projects become more complex with Claude Code? To solve these challenges, I developed dotclaude-template.

The Challenge: Limitations of AI in Complex Projects

Claude Code is a powerful tool capable of handling diverse tasks in a single conversation. However, complex projects face these challenges.

Context Bloat

As projects grow larger, trying to hold all knowledge at once blurs focus. "Can do anything" paradoxically makes "what to do" unclear.

Quality Variance

Areas requiring specialization—optimization problem formulation, test design, debugging strategies—tend to receive generic responses instead of expert-level guidance.

Context Loss Between Sessions

When you interrupt and resume work, recalling the previous state and incomplete tasks takes time.

What is dotclaude-template?

A .claude/ directory template for Claude Code projects. Through agent separation and command definitions, it enables consistent development experience even in complex projects.

.claude/
├── agents/           # Specialized agent definitions
│   ├── project-manager.md
│   ├── implementer.md
│   ├── test-runner.md
│   └── debugger.md
└── commands/         # Custom command definitions
    ├── session-start.md
    └── session-end.md

Design Philosophy: Responsibility Separation with Specialized Agents

Core 4 Agents

  • project-manager: Planning, task breakdown, delegation to other agents
  • implementer: Code implementation, refactoring
  • test-runner: Test execution, result analysis, coverage management
  • debugger: Root cause analysis, hypothesis verification, fix proposals

Collaboration Patterns

By documenting inter-agent collaboration, we achieve consistent quality.

For example, the new feature implementation flow:

  1. project-manager analyzes requirements and creates implementation plan
  2. Delegates implementation to implementer
  3. After completion, test-runner executes tests
  4. On failure, debugger analyzes root cause
  5. project-manager reports to user

Workflow Standardization with Commands

session-start / session-end

Session management commands enable context persistence.

/session-start: Generate session ID, restore previous session state, verify environment information, identify incomplete tasks

/session-end: Record work content, clarify incomplete tasks, organize next actions

This allows smooth resumption even after interrupting work.

Context Persistence with Serena Memory (Recommended)

For session context persistence, we strongly recommend using the Memory feature of Serena.

Why use Serena Memory?

  • Survives conversation resets: Unlike file-based storage, reliably persists via MCP server
  • Structured data: Saves session ID, incomplete tasks, and next actions in organized format
  • Seamless restoration: /session-start automatically restores previous state
# Example content saved to Serena Memory

## Last Session
- Session ID: 20260125_143052
- End Time: 2026-01-25 17:30:00

## Incomplete Tasks
- [ ] Implement feature A
- [ ] Add tests

## Next Actions
1. Complete feature A implementation
2. Address code review feedback

When Serena is available, the setup process automatically configures Serena Memory usage.

Adding Domain-Specific Agents

Beyond the core 4 agents, you can add project-specific specialists.

Example: Web Application

agents/
├── project-manager.md
├── frontend-specialist.md       # React/Vue implementation
├── backend-specialist.md        # API implementation
├── database-specialist.md       # Schema design
├── test-runner.md
└── debugger.md

Example: Optimization Project

agents/
├── project-manager.md
├── python-specialist.md
├── test-runner.md
├── debugger.md
├── optimization-specialist.md   # Problem formulation
├── data-validator.md            # Input data validation
└── result-analyzer.md           # Result analysis & visualization

Usage

Method 1: Automatic Setup with Claude Code

Simply instruct Claude Code:

Read this repository and set up a .claude/ environment for my project
https://github.com/manabelab/dotclaude-template

Claude Code will interview you about your project characteristics and generate appropriate agents and commands.

Interview Items:

  • Primary language (Python / TypeScript / Go, etc.)
  • Domain (Web / Data Analysis / Optimization, etc.)
  • Test framework
  • Package manager
  • Serena MCP server availability
  • Documentation language (English / Japanese / Chinese / Korean)

Method 2: Manual Copy

  1. Copy contents of templates/ directory to .claude/
  2. Customize according to your project

Multi-Language Support

By selecting a language during setup, you can generate agent and command definitions in your preferred language:

  • English
  • 日本語 (Japanese)
  • 中文 (Chinese)
  • 한국어 (Korean)

Conclusion

dotclaude-template is a template for structuring and streamlining development with Claude Code. Through agent separation and command definitions, it provides consistent development experience even in complex projects.

Documentation:

Please give it a try. Feedback and contributions are welcome.

Labels:

コメント

コメントを投稿

このブログの人気の投稿

Sourcetreeを使って、特定のブランチやタグをローカルに再現する方法 - フェッチ(fetch)を使おう -

今や、プログラミング開発に欠かせない存在となったGit。上司や同僚から「修正版をブランチ"devlop"にプッシュしたから、それを反映させてね」「安定版はタグ”v1.2”だから、よろしくね」と言われることもあるでしょう。その時に「どうやってブランチやタグって変えたらいいかわからない」「そもそも言われたブランチやタグが見当たらないんだけど…」となったら、とても困ってしまいます。そんなときにどうしたらいいか、本記事では Sourcetree を使用している環境を想定して、おすすめの手順を紹介します。環境によって具体的な操作は異なるものの、手順自体は一緒です。基本的には、 フェッチ(fetch)をしてリモートリポジトリをちゃんと確認 すればよいのです。 1. コミットしていないファイルをなくそう まず、Sourcetreeのコミット一覧に「コミットされていない変更があります」とあるかどうか確認します（下記図赤下線参照）。「コミット」の箇所に青マークでコミットされてないファイル数も表示されます（下記図赤枠参照）。その変更をコミットするか、破棄するかを行い、コミットされていない変更がない、きれいな状態にしましょう。そうしないと、後の作業中にエラー等が発生して進まなくなってしまいます。 2. フェッチしよう フェッチとは、 リモートリポジトリの最新の履歴の取得だけを行う 操作です。これによって、自分から見えていなかったブランチ・タグが見えるようになります。ブランチへのマージが伴うプッシュやプルと異なり、単に履歴を取得するだけなので、意図しないコミットが発生しません。安心して実施しましょう。Sourcetreeでは下記図赤枠部分をクリックすれば、フェッチを行うことができます。 その際出てくるポップアップで「すべてのリモートからフェッチ」「全てのタグを取得」をチェックしてください（下図赤下線参照）。 3. 目的のブランチ・タグを見つけよう 目的のブランチ・タグを見つけるのに便利なのが、Sourcetreeの左側領域にある「ブランチ」「タグ」「リモート」「スタッシュ」です。目的のブランチを探したい場合は「リモート」をクリックして現れる「origin」をさらにクリックしましょう。これでリモート上にあるブランチの一覧を見ることができます。タグの場合は「タグ」をクリック...
コメントを投稿
Read more »

SourcetreeでGitHubのプライベートリポジトリをクローンする

Sourcetree は、初心者でも操作しやすいgitのGUIツールです。基本無料のソフトなので、あらゆる人が導入・利用しやすいという利点を持ちます。ですが、GitHubで非公開、つまりプライベートのリポジトリを取り扱う場合には、初期設定に一工夫が必要です。 本記事で紹介する設定の流れは以下の通りです。前提として、1）GitHubのアカウントとプライベートリポジトリを既に所有しているが、2）Sourcetreeを自身のPCにまだインストールしていない状態を想定しています。 GitHubのPersonal access tokenを作成する Sourcetreeを自身のPCにインストールする SourcetreeにGitHubのアカウントを登録する プライベートリポジトリをクローンする 今回はPersonal access tokenという手法を用います。秘密鍵や公開鍵が必要なSSH接続とは異なり、アカウント名とパスワードのみで認証できます。そのため、アカウント管理がより重要となりますので、 2段階認証 でより強力なアカウント保護をおこなうことをお勧めします。また、本記事で紹介するのはWindowsでの利用です。Macでもほぼ同じ流れになるかと思いますが、試してはいませんのでご了承ください。 1. GitHubのPersonal access tokenを作成する GitHubのPersonal access tokenとは、GitHub API またはコマンドラインを使用するときに GitHub への認証でパスワードの代わりに使用できる機能です。このトークンを自身のGitHubアカウントで作成することで、Sourcetreeからプライベートリポジトリにアクセスすることができるようになります。具体的な作り方は下記のGitHub公式ページををご参考ください。 Personal access tokenの作成方法: https://docs.github.com/ja/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token ポイントは手順8に書かれているS ...
コメントを投稿
Read more »

GitHubのプライベートリポジトリからクローンできてもプッシュできないときの対処法　- Write権限の有無を確認しよう -

 以前、 SourceTreeを使って、GitHubのプライベートリポジトリにアクセスする方法 を記事にしました。その際、プライベートリポジトリからクローンできても、プッシュできない！という現象に遭遇するときがあります。下記のように、”そんなリポジトリは存在しないよ”というエラーが表示されます。 remote: Repository not found. もし、そのリポジトリがOrganaizationに属するものならば、 あなたのアカウントの権限が”Read”のみで、”Write”になっていない 可能性があります。権限に関してOrganaizationの管理者に確認してもらいましょう。 管理者がどういうルールで権限を決定しているのかによって、対応が変わるかと思います。一番手っ取り早い対応は、全てのメンバーのデフォルト権限を”Write”に変えてしまえばよいでしょう。Organaizationのページの右上にある「Settings」をクリックし、左に表示されるメニューから「Member privileges」を選択します。すると、左下のような画面が表示されますので、赤枠で囲っている「Base permissions」のプルダウン部分を"Write"に変更してください。 その他に、リポジトリ毎にアクセスできるメンバーを管理したい場合もあるかと思います。その際にはリポジトリの「Settings」→「Manage access」を選択し、設定等を変更してください。
コメントを投稿
Read more »