Skip to content

CLAUDE.md

Latest commit

 

History

History
256 lines (180 loc) · 9.96 KB

CLAUDE.md

File metadata and controls

256 lines (180 loc) · 9.96 KB

Context Engineering Kit

Claude Code plugin marketplace with advanced context engineering techniques focused on improving agent result quality.

See @README for project overview and @CONTRIBUTING.md for contributing guidelines.

Project Structure

context-engineering-kit/
├── .claude-plugin/
│   └── marketplace.json    # Main marketplace manifest with all plugins
├── plugins/                 # Plugin source code
│   └── <plugin-name>/
│       ├── .claude-plugin/
│       │   └── plugin.json  # Plugin manifest
│       ├── README.md
│       ├── commands/        # Slash commands (*.md)
│       └── skills/          # Skills (*.md)
├── docs/                    # Documentation (GitBook)
│   └── plugins/
│       └── <plugin-name>/   # Plugin documentation
│           └── README.md
├── specs/                   # Feature specifications
├── justfile                 # Development commands
└── CONTRIBUTING.md          # Contribution guidelines

Available Plugins

review, customaize-agent, ddd, docs, git, kaizen, mcp, reflexion, sadd, sdd, tdd, tech-stack

Development Commands

just help                                       # Show all commands
just list-plugins                               # List plugins with versions
just sync-docs-to-plugins                       # Copy docs/plugins/*/README.md → plugins/*/README.md
just sync-plugins-to-docs                       # Copy plugins/*/README.md → docs/plugins/*/README.md
just set-version <name> <x.y.z>                 # Update plugin version
just set-marketplace-version <x.y.z>            # Update marketplace version

Key Development Rules

Plugin Design Philosophy

  1. Commands over skills - Commands load on-demand; skill descriptions load into context by default
  2. Specialized agents - Use agents with focused context to reduce hallucinations
  3. Setup-commands - Use setup commands to update CLAUDE.md for persistent project context
  4. Minimal tokens - Every token counts; keep prompts concise

When Creating/Modifying Plugins

  • Use just set-version <name> <x.y.z> to update plugin versions consistently, do not modify manually.
  • Use just set-marketplace-version <x.y.z> to update the marketplace version, do not modify manually.
  • Keep README.md in sync between plugins/<name>/ and docs/plugins/<name>/ using just sync-docs-to-plugins and just sync-plugins-to-docs commands. Do not update both manually.
  • Test plugins with Claude Code before committing using plugins/customaize-agent:test-prompt and plugins/customaize-agent:test-skill commands.

When Adding New Skills or Commands

Documentation Checklist (all files must be updated):

  1. plugins/<name>/README.md - Add skill/command with "Use when..." trigger and structured tables
  2. README.md (root) - Add to Skills/Commands section under plugin listing
  3. docs/reference/skills.md or docs/reference/commands.md - Add to complete reference
  4. docs/plugins/README.md - Update Key Features for the plugin
  5. docs/resources/related-projects.md - Add source project attribution if based on external work
  6. docs/resources/papers.md - Add research papers if technique is based on academic research
  7. Run just sync-plugins-to-docs to sync plugin README to docs/
  8. Bump plugin version: just set-version <name> <x.y.z> (minor for features)
  9. Bump marketplace version: just set-marketplace-version <x.y.z>

Finding All References: Before declaring documentation complete, search for all files referencing the plugin:

grep -r "<plugin-name>" docs/ README.md --include="*.md" -l

Skill Documentation Pattern:

  • Start with "Use when..." trigger phrase
  • Use tables for structured information (not prose)
  • Include key concepts with one-line explanations
  • Keep YAML name: field matching folder name for consistency

When Creating/Refactoring Agents

Agent File Location: .claude/agents/<agent-name>.md or plugins/<plugin>/agents/<agent-name>.md

See plugins/customaize-agent/commands/create-agent.md command for detailed agent creation guidelines including frontmatter rules, required sections, process ordering, and decision table patterns.

Use Context7 MCP for Loading Documentation

Context7 MCP is available to fetch up-to-date documentation with code examples.

Recommended library IDs:

  • /anthropics/claude-code - Claude Code CLI tool documentation (1954 snippets)
  • /websites/platform_claude - Claude Developer Platform comprehensive docs (5916 snippets)
  • /anthropics/anthropic-cookbook - Code examples and guides for building with Claude (1226 snippets)
  • /anthropics/courses - Anthropic educational courses on SDK and prompt engineering (1173 snippets)
  • /websites/platform_claude_en_agent-sdk - Claude Agent SDK for Python/TypeScript (605 snippets)
  • /anthropics/claude-agent-sdk-python - Python SDK for Claude Agent (57 snippets)
  • /anthropics/claude-code-sdk-python - Python SDK for Claude Code (31 snippets)

Usage:

mcp__context7__query-docs libraryId: "/anthropics/claude-code" query: "how to configure hooks"

Use Paper Search MCP for Academic Research

Paper Search MCP is available via Docker MCP for searching and downloading academic papers.

Available tools:

  • search_arxiv - Search arXiv preprints (physics, math, CS, etc.)
  • search_pubmed - Search PubMed biomedical literature
  • search_biorxiv / search_medrxiv - Search biology/medicine preprints
  • search_semantic - Search Semantic Scholar with year filters
  • search_google_scholar - Broad academic search
  • search_iacr - Search cryptography papers
  • search_crossref - Search by DOI/citation

Download and read tools:

  • download_arxiv / read_arxiv_paper - Download/read arXiv PDFs
  • download_biorxiv / read_biorxiv_paper - Download/read bioRxiv PDFs
  • download_semantic / read_semantic_paper - Download/read via Semantic Scholar

Usage notes:

  • Use mcp-exec to call tools, e.g., mcp-exec name: "search_arxiv" arguments: {"query": "topic", "max_results": 10}
  • Downloaded papers are saved to ./downloads by default
  • For Semantic Scholar, supports multiple ID formats: DOI, ARXIV, PMID, etc.

Use Minibeads for Task Tracking

Minibeads is a task tracking tool that allow to create tasks as markdown files.

You MUST: Use "md create" for issues, TodoWrite for simple single-session execution

Essential Commands

Finding Work

  • mb ready - Show issues ready to work (no blockers)
  • mb list --status=open - All open issues
  • mb list --status=in_progress - Your active work
  • mb show <id> - Detailed issue view with dependencies

Creating & Updating

  • mb create "title" -t task|bug|feature -p 2 -d "description" - New issue
    • Priority: 0-4 or P0-P4 (0=critical, 2=medium, 4=backlog). NOT "high"/"medium"/"low"
  • mb update <id> --status=in_progress - Claim work
  • mb update <id> --assignee=username - Assign to someone
  • mb close <id> - Mark complete
  • mb close <id1> <id2> ... - Close multiple issues at once (more efficient)
  • mb close <id> --reason=\"explanation\" - Close with reason
  • Tip: When creating multiple issues/tasks/epics, use parallel subagents for efficiency

Modifying Task Descriptions

Use Write tool instead of mb update -d for description changes:

Tasks are stored as markdown files in .beads/issues/<id>.md with this format:

---
[task frontmatter]
---

# Description

[Task description content here]

Why Write tool for descriptions?

  • mb update -d replaces entire description (easy to lose content)
  • Write tool allows precise edits while preserving existing content
  • Better for large descriptions with multiple sections

Dependencies & Blocking

  • mb dep add <issue> <depends-on> - Add dependency (issue depends on depends-on)
  • mb blocked - Show all blocked issues
  • mb show <id> - See what's blocking/blocked by this issue

Common Workflows

Starting work:

mb ready           # Find available work
mb show <id>       # Review issue details
mb update <id> --status=in_progress  # Claim it
mb close <id1> <id2> ...    # Close all completed issues at once

Creating dependent work:

# Run mb create commands in parallel (use subagents for many items)
mb create "Implement feature X" -t feature
mb create "Write tests for X" -t task
mb dep add cek-yyy cek-xxx  # Tests depend on Feature (Feature blocks tests)

Examples

CREATING ISSUES

  • mb create "Fix login bug"
  • mb create "Add auth" -p 0 -t feature
  • mb create "Write tests" -d "Unit tests for auth" --assignee alice

VIEWING ISSUES

  • mb list List all issues
  • mb list --status open List by status
  • mb list --priority 0 List by priority (0-4, 0=highest)
  • mb show cek-1 Show issue details

Problems and Solutions

Memory of found issues and stategies to solve them.

When Claude sees code blocks with Thought:, Action:, Observation: patterns, it interprets them as output templates to mimic, not as instructions to execute

So instead of actually calling Write() tool, it generates text that says: Thought: Let me analyze... Action: Write(.specs/scratchpad/...)

This is just text output - not a real tool invocation.

Why This Happens

  1. Code blocks look like output format - Claude thinks "this is what my response should look like"
  2. Pattern mimicking - The agent copies the pattern structure as text instead of executing tools
  3. Pseudo-code confusion - Action: Write(...) looks like code to output, not a command to run

The Fix

Remove all Thought-Action-Observation code block examples and replace with imperative natural language instructions that tell the agent WHAT to do, trusting it knows HOW to use tools.

Instead of: Thought: I need to read the task file... Action: Read(.specs/tasks/task-example.md) Observation: [What I found...]

Write: First, use the Read tool to load the task file. Then analyze what the user is requesting and document your findings in the scratchpad using the Write tool.