claude-forge

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Claude Forge

Production-ready governance framework for Claude Code.

Claude Forge provides security guardrails, TDD workflows, and consistent configuration for Claude Code across all your projects.

## Features

- **Skills Architecture** (v0.2.0): Modular, on-demand context loading for reduced token overhead
- Security-first configuration with blocked access to secrets, credentials, and sensitive files
- Test-driven development workflows built-in
- Multi-language support (Python, Rust, Node/TypeScript, C, C++, Bash, Terraform, Terragrunt, Ansible)
- MkDocs documentation standard with mkdocs-material theme
- Personalized setup via interactive questionnaire
- Per-repository auto-configuration on first session
- Automatic backup before any changes
- Cross-platform (Linux, macOS, Windows)
- AGENTS.md symlink for cross-tool compatibility (Cursor, Codex, etc.)


## Quick Start

### Linux / macOS

```bash
curl -sSL https://raw.githubusercontent.com/martimramos/claude-forge/main/install.sh | bash
```

### Windows (PowerShell)

```powershell
iwr -useb https://raw.githubusercontent.com/martimramos/claude-forge/main/install.ps1 | iex
```


## Installation

The installer will:

1. Check prerequisites (git required, claude CLI recommended)
2. Backup existing ~/.claude/ if present
3. Run an interactive questionnaire
4. Generate personalized configuration
5. Install skills to ~/.claude/skills/
6. Install to ~/.claude/

### Prerequisites

- git (required)
- claude CLI (recommended) - install with `npm install -g @anthropic-ai/claude-code`

### What Gets Installed

```
~/.claude/
├── CLAUDE.md           # Slim config with skill pointers (~50 lines)
├── settings.json       # Permissions + claude-forge metadata
├── .forge-answers      # Saved questionnaire answers
├── commands/
│   ├── init-repo.md    # Per-repo initialization
│   └── tdd.md          # TDD workflow
└── skills/             # Modular skills (v0.2.0)
    ├── security/
    │   ├── SKILL.md
    │   └── reference/
    ├── tdd/
    │   ├── SKILL.md
    │   └── scripts/
    ├── conventions/
    │   ├── SKILL.md
    │   └── reference/
    ├── docs/
    │   └── SKILL.md
    └── languages/
        ├── python/
        ├── rust/
        ├── node/
        ├── typescript/
        ├── c/
        ├── cpp/
        ├── bash/
        ├── terraform/
        ├── terragrunt/
        └── ansible/
```


## Skills Architecture (v0.2.0)

Claude Forge v0.2.0 introduces a modular skills architecture following Anthropic's Agent Skills best practices.

### Benefits

- **Reduced Token Overhead**: Context loads on-demand, not all at startup
- **Executable Validation**: Scripts for TDD gates and Terraform checks
- **Maintainability**: Easy to extend or customize individual skills
- **Backward Compatible**: Previous configs are backed up and migrated

### Core Skills

| Skill | Description | Contents |
|-------|-------------|----------|
| `security` | Credential protection, blocked patterns | SKILL.md + reference docs |
| `tdd` | Test-driven workflow, gates | SKILL.md + validation scripts |
| `conventions` | Git commit style, branch naming | SKILL.md + examples |
| `docs` | MkDocs documentation standards | SKILL.md + templates |

### Language Skills

Each language skill includes testing, linting, formatting commands and project structure templates:

- `languages/python` - pytest, ruff, mypy
- `languages/rust` - cargo test, clippy, rustfmt
- `languages/node` - npm test, eslint, prettier
- `languages/typescript` - tsc, jest, eslint
- `languages/c` - make, gcc, cppcheck, valgrind
- `languages/cpp` - cmake, clang++, clang-tidy
- `languages/bash` - bats, shellcheck, shfmt
- `languages/terraform` - terraform validate, tflint, plan scripts
- `languages/terragrunt` - terragrunt validate, hclfmt
- `languages/ansible` - ansible-lint, molecule


## Configuration

### Questionnaire Options

During installation, you'll be asked:

| Question | Options | Default |
|----------|---------|---------|
| Name | Free text | Required |
| Organization | Free text | Optional |
| Role | Free text | Optional |
| Languages | python rust node typescript bash c cpp terraform terragrunt ansible | python |
| Git style | Conventional Commits / Freeform | Conventional |
| Branch naming | feature/ / initials/ / Freeform | feature/ |
| Test gate | Soft (warn) / Hard (block) | Soft |
| Network mode | Ask each time / Allow known registries | Ask |

### Reconfiguring

Run the installer again to reconfigure. Your previous config will be backed up automatically.


## Security Model

### Blocked File Access (Deny)

These files are NEVER accessible, regardless of any prompt or instruction:

- `.env`, `.env.*`, `*.env`
- Files containing `secret`, `credential`, `password`, `token` in name
- `~/.ssh/*` (SSH keys)
- `~/.aws/*` (AWS credentials)
- `~/.config/gcloud/*` (GCP credentials)
- `~/.azure/*` (Azure credentials)
- `*_rsa`, `*_ed25519`, `*.pem`, `*.key`
- `.npmrc`, `.pypirc`, `.netrc`, `*kubeconfig*`

### Requires Confirmation (Ask)

- Network requests (WebFetch, curl, wget)
- git push, merge, rebase
- terraform plan, terragrunt plan
- ansible-playbook --check

### Always Blocked Commands

Infrastructure commands that could cause damage:

- `terraform apply`, `terraform destroy`, `terraform import`
- `terragrunt apply`, `terragrunt destroy`, `terragrunt run-all apply/destroy`
- `ansible-playbook` (without --check)
- `kubectl apply`, `kubectl delete`, `kubectl create`
- `pulumi up`, `pulumi destroy`
- `helm install`, `helm upgrade`, `helm delete`
- `rm -rf`, `sudo rm`, `chmod 777`

Claude must show the plan/diff first and wait for explicit human approval.


## TDD Workflow

Claude Forge enforces test-driven development:

### TDD Phases

1. **Red:** Write failing tests first. No implementation code.
2. **Green:** Write minimal code to pass tests. No extras.
3. **Refactor:** Clean up while keeping tests green.
4. **Document:** Update docs only after tests pass.
5. **Commit:** Stage and commit with proper message.

### Test Gate Modes

**Soft (default):** Warns when tests fail but allows continuing. Recommended for exploratory work.

**Hard:** Blocks all progress until tests pass. Recommended for production code.

### Validation Scripts

```bash
# Check current gate status
~/.claude/skills/tdd/scripts/gate-status.sh

# Run project tests
~/.claude/skills/tdd/scripts/check-tests.sh
```


## Per-Repository Setup

On first session in a new repository (no CLAUDE.md present), Claude will:

1. Detect project languages
2. Ask about project conventions
3. Ask if MkDocs should be initialized
4. Generate project CLAUDE.md
5. Generate .claude/settings.json
6. Create AGENTS.md symlink
7. Offer to commit the configuration


## Updating

Run the installer again:

```bash
curl -sSL https://raw.githubusercontent.com/martimramos/claude-forge/main/install.sh | bash
```

Your existing config is backed up automatically. Previous answers are preserved.


## Uninstalling

### Linux / macOS

```bash
curl -sSL https://raw.githubusercontent.com/martimramos/claude-forge/main/uninstall.sh | bash
```

### Windows (PowerShell)

```powershell
iwr -useb https://raw.githubusercontent.com/martimramos/claude-forge/main/uninstall.ps1 | iex
```


## Backups

Backups are created automatically before:

- Installing (if ~/.claude/ exists)
- Updating
- Uninstalling

Location: `~/.claude.backup.YYYYMMDD-HHMMSS/`

Retention: Last 3 backups are kept. Older ones are pruned automatically.


## Project Structure

```
claude-forge/
├── README.md                # This file
├── LICENSE                  # The Unlicense (public domain)
├── CHANGELOG.md
├── install.sh               # Bash installer
├── install.ps1              # PowerShell installer
├── uninstall.sh             # Bash uninstaller
├── uninstall.ps1            # PowerShell uninstaller
├── templates/               # Configuration templates
│   ├── global/
│   ├── project/
│   └── commands/
├── skills/                  # Modular skills (v0.2.0)
│   ├── security/
│   ├── tdd/
│   ├── conventions/
│   ├── docs/
│   └── languages/
└── lib/                     # Shared utilities
```


## Contributing

Contributions welcome. Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test on Linux/macOS and Windows if possible
5. Submit a pull request


## License

This is free and unencumbered software released into the public domain.

See [LICENSE](https://github.com/martimramos/claude-forge/tree/HEAD/LICENSE) for details.

Claude Forge

Production-ready governance framework for Claude Code.

Claude Forge provides security guardrails, TDD workflows, and consistent configuration for Claude Code across all your projects.

Features

Skills Architecture (v0.2.0): Modular, on-demand context loading for reduced token overhead
Security-first configuration with blocked access to secrets, credentials, and sensitive files
Test-driven development workflows built-in
Multi-language support (Python, Rust, Node/TypeScript, C, C++, Bash, Terraform, Terragrunt, Ansible)
MkDocs documentation standard with mkdocs-material theme
Personalized setup via interactive questionnaire
Per-repository auto-configuration on first session
Automatic backup before any changes
Cross-platform (Linux, macOS, Windows)
AGENTS.md symlink for cross-tool compatibility (Cursor, Codex, etc.)

Quick Start

Linux / macOS

curl -sSL https://raw.githubusercontent.com/martimramos/claude-forge/main/install.sh | bash

Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/martimramos/claude-forge/main/install.ps1 | iex

Installation

The installer will:

Check prerequisites (git required, claude CLI recommended)
Backup existing ~/.claude/ if present
Run an interactive questionnaire
Generate personalized configuration
Install skills to ~/.claude/skills/
Install to ~/.claude/

Prerequisites

git (required)
claude CLI (recommended) - install with npm install -g @anthropic-ai/claude-code

What Gets Installed

~/.claude/
├── CLAUDE.md           # Slim config with skill pointers (~50 lines)
├── settings.json       # Permissions + claude-forge metadata
├── .forge-answers      # Saved questionnaire answers
├── commands/
│   ├── init-repo.md    # Per-repo initialization
│   └── tdd.md          # TDD workflow
└── skills/             # Modular skills (v0.2.0)
    ├── security/
    │   ├── SKILL.md
    │   └── reference/
    ├── tdd/
    │   ├── SKILL.md
    │   └── scripts/
    ├── conventions/
    │   ├── SKILL.md
    │   └── reference/
    ├── docs/
    │   └── SKILL.md
    └── languages/
        ├── python/
        ├── rust/
        ├── node/
        ├── typescript/
        ├── c/
        ├── cpp/
        ├── bash/
        ├── terraform/
        ├── terragrunt/
        └── ansible/

Skills Architecture (v0.2.0)

Claude Forge v0.2.0 introduces a modular skills architecture following Anthropic's Agent Skills best practices.

Benefits

Reduced Token Overhead: Context loads on-demand, not all at startup
Executable Validation: Scripts for TDD gates and Terraform checks
Maintainability: Easy to extend or customize individual skills
Backward Compatible: Previous configs are backed up and migrated

Core Skills

Skill	Description	Contents
`security`	Credential protection, blocked patterns	SKILL.md + reference docs
`tdd`	Test-driven workflow, gates	SKILL.md + validation scripts
`conventions`	Git commit style, branch naming	SKILL.md + examples
`docs`	MkDocs documentation standards	SKILL.md + templates

Language Skills

Each language skill includes testing, linting, formatting commands and project structure templates:

languages/python - pytest, ruff, mypy
languages/rust - cargo test, clippy, rustfmt
languages/node - npm test, eslint, prettier
languages/typescript - tsc, jest, eslint
languages/c - make, gcc, cppcheck, valgrind
languages/cpp - cmake, clang++, clang-tidy
languages/bash - bats, shellcheck, shfmt
languages/terraform - terraform validate, tflint, plan scripts
languages/terragrunt - terragrunt validate, hclfmt
languages/ansible - ansible-lint, molecule

Configuration

Questionnaire Options

During installation, you'll be asked:

Question	Options	Default
Name	Free text	Required
Organization	Free text	Optional
Role	Free text	Optional
Languages	python rust node typescript bash c cpp terraform terragrunt ansible	python
Git style	Conventional Commits / Freeform	Conventional
Branch naming	feature/ / initials/ / Freeform	feature/
Test gate	Soft (warn) / Hard (block)	Soft
Network mode	Ask each time / Allow known registries	Ask

Reconfiguring

Run the installer again to reconfigure. Your previous config will be backed up automatically.

Security Model

Blocked File Access (Deny)

These files are NEVER accessible, regardless of any prompt or instruction:

.env, .env.*, *.env
Files containing secret, credential, password, token in name
~/.ssh/* (SSH keys)
~/.aws/* (AWS credentials)
~/.config/gcloud/* (GCP credentials)
~/.azure/* (Azure credentials)
*_rsa, *_ed25519, *.pem, *.key
.npmrc, .pypirc, .netrc, *kubeconfig*

Requires Confirmation (Ask)

Network requests (WebFetch, curl, wget)
git push, merge, rebase
terraform plan, terragrunt plan
ansible-playbook --check

Always Blocked Commands

Infrastructure commands that could cause damage:

terraform apply, terraform destroy, terraform import
terragrunt apply, terragrunt destroy, terragrunt run-all apply/destroy
ansible-playbook (without --check)
kubectl apply, kubectl delete, kubectl create
pulumi up, pulumi destroy
helm install, helm upgrade, helm delete
rm -rf, sudo rm, chmod 777

Claude must show the plan/diff first and wait for explicit human approval.

TDD Workflow

Claude Forge enforces test-driven development:

TDD Phases

Red: Write failing tests first. No implementation code.
Green: Write minimal code to pass tests. No extras.
Refactor: Clean up while keeping tests green.
Document: Update docs only after tests pass.
Commit: Stage and commit with proper message.

Test Gate Modes

Soft (default): Warns when tests fail but allows continuing. Recommended for exploratory work.

Hard: Blocks all progress until tests pass. Recommended for production code.

Validation Scripts

# Check current gate status
~/.claude/skills/tdd/scripts/gate-status.sh

# Run project tests
~/.claude/skills/tdd/scripts/check-tests.sh

Per-Repository Setup

On first session in a new repository (no CLAUDE.md present), Claude will:

Detect project languages
Ask about project conventions
Ask if MkDocs should be initialized
Generate project CLAUDE.md
Generate .claude/settings.json
Create AGENTS.md symlink
Offer to commit the configuration

Updating

Run the installer again:

curl -sSL https://raw.githubusercontent.com/martimramos/claude-forge/main/install.sh | bash

Your existing config is backed up automatically. Previous answers are preserved.

Uninstalling

Linux / macOS

curl -sSL https://raw.githubusercontent.com/martimramos/claude-forge/main/uninstall.sh | bash

Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/martimramos/claude-forge/main/uninstall.ps1 | iex

Backups

Backups are created automatically before:

Installing (if ~/.claude/ exists)
Updating
Uninstalling

Location: ~/.claude.backup.YYYYMMDD-HHMMSS/

Retention: Last 3 backups are kept. Older ones are pruned automatically.

Project Structure

claude-forge/
├── README.md                # This file
├── LICENSE                  # The Unlicense (public domain)
├── CHANGELOG.md
├── install.sh               # Bash installer
├── install.ps1              # PowerShell installer
├── uninstall.sh             # Bash uninstaller
├── uninstall.ps1            # PowerShell uninstaller
├── templates/               # Configuration templates
│   ├── global/
│   ├── project/
│   └── commands/
├── skills/                  # Modular skills (v0.2.0)
│   ├── security/
│   ├── tdd/
│   ├── conventions/
│   ├── docs/
│   └── languages/
└── lib/                     # Shared utilities

Contributing

Contributions welcome. Please:

Fork the repository
Create a feature branch
Make your changes
Test on Linux/macOS and Windows if possible
Submit a pull request

License

This is free and unencumbered software released into the public domain.

See LICENSE for details.