# ForgeStack

**Repository Path**: Reol2022/forge-stack

## Basic Information

- **Project Name**: ForgeStack
- **Description**: ForgeStack 是一个面向软件工程与受控 AI Coding 的可复用工程实践库，沉淀真实项目中的架构模式、开发流程、调试经验、Skills、Playbooks 与工程规范。项目关注需求如何准确表达、AI 如何受控执行、代码如何验证，以及经验如何跨项目复用，逐步形成不依赖单一模型或工具的个人工程方法体系。

- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-11
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ForgeStack

ForgeStack 是一个面向软件工程与受控 AI Coding 的可复用工程实践库，沉淀真实项目中的架构模式、开发流程、调试经验、Skills、Playbooks 与工程规范。项目关注需求如何准确表达、AI 如何受控执行、代码如何验证，以及经验如何跨项目复用，逐步形成不依赖单一模型或工具的个人工程方法体系。

## 为什么做 ForgeStack

零散笔记难以复用，项目经验也容易随项目结束而流失。这里把已发生的问题与验证过的做法逐步抽象为原则、模式、可执行任务和流程；结论应能回溯到案例或证据，而不是依赖工具宣传或个人记忆。

## 核心理念

- Docs First：先把问题、范围与验收写清楚。
- Repository First：Markdown 是可审查、可版本化的 Canonical Source。
- Experience First：从真实经验抽象，保留适用边界。
- AI 的输出是提案；关键约束由确定性验证承担。

## 仓库结构

| 目录 | 内容 |
| --- | --- |
| [principles](principles/README.md) | 稳定工程原则 |
| [patterns](patterns/README.md) | 跨项目设计与工程模式 |
| [skills](skills/README.md) | 可重复执行的工程任务 |
| [playbooks](playbooks/README.md) | 跨 Skill 的完整流程 |
| [templates](templates/README.md) | 可直接复用的记录模板 |
| [cases](cases/README.md) | 脱敏案例与工程教训 |
| [adr](adr/README.md) | 架构决策记录 |
| [source-reading](source-reading/README.md) | 源码阅读入口与笔记 |
| [career](career/README.md) | 脱敏的学习与面试知识 |
| [docs](docs/roadmap.md) | 路线图、边界与术语 |

## 内容类型

| 类型 | 回答的问题 | 最小单位 |
| --- | --- | --- |
| Principle | 为什么这样做？ | 稳定的工程判断 |
| Pattern | 这类问题一般如何设计？ | 可跨项目复用的结构 |
| Skill | 这个任务具体怎么做？ | 输入、步骤、失败模式、验收 |
| Playbook | 如何完整解决一类问题？ | 多个 Skill 的有序流程 |
| Case | 真实问题带来了什么教训？ | 上下文、根因、修复与抽象 |
| ADR | 为什么选择此设计？ | 决策及其后果 |

## 当前内容

v0.1 包含稳定原则、跨项目模式、可执行 Skills、Playbooks、模板、脱敏案例与 ADR。内容只保留可公开、可复用的结论，不复制来源项目的业务代码、数据、配置或规则。

### From GaitLogic Planner

#### Principles

- [Validation Over Trust](principles/validation-over-trust.md)

#### Patterns

- [Read-only Capability Boundary](patterns/read-only-capability-boundary.md)
- [Server-side Identity Injection](patterns/server-side-identity-injection.md)
- [Proposal Before Mutation](patterns/proposal-before-mutation.md)
- [Canonical Source Boundary](patterns/canonical-source-boundary.md)
- [Safe Domain Tracing](patterns/safe-domain-tracing.md)

#### Skills

- [Structured Output Failure Boundary Debugging](skills/debugging/structured-output-failure-boundary-debugging.md)

#### Playbooks

- [Bounded Agent Evaluation](playbooks/bounded-agent-evaluation.md)

#### Cases

- [Successful Generation Misclassified as Model Unavailable](cases/gaitlogic/successful-generation-misclassified-as-model-unavailable.md)

#### ADRs

- [ADR-0002: Keep Canonical Knowledge Outside the Vector Store](adr/ADR-0002-keep-canonical-knowledge-outside-vector-store.md)

### From Framework Lab

Framework Lab 的经验补足的是 **AI-assisted Software Engineering Control**：规格、范围、可信上下文、受控修改、diff、确定性验证与验收。它为外部 Coding Agent 提供能力，不等同于 Coding Agent 本身。

#### Principles

- [Specification First](principles/specification-first.md)
- [Evidence First](principles/evidence-first.md)
- [Deterministic Acceptance](principles/deterministic-acceptance.md)

#### Patterns

- [TaskSpec Boundary](patterns/task-spec-boundary.md)
- [Task Scope Boundary](patterns/task-scope-boundary.md)
- [Context Budget](patterns/context-budget.md)
- [Task-aware Retrieval](patterns/task-aware-retrieval.md)
- [Evidence-backed Knowledge Unit](patterns/evidence-backed-knowledge-unit.md)
- [Tool Registry / Agent Tool Contract](patterns/tool-registry.md)

#### Skills

- [Task Specification](skills/ai-coding/task-specification.md)
- [Define Safe Task Scope](skills/ai-coding/define-safe-task-scope.md)
- [Controlled Code Change](skills/ai-coding/controlled-code-change.md)
- [Validate AI-modified Workspace](skills/ai-coding/validate-ai-modified-workspace.md)
- [Minimal Context Retrieval](skills/rag/minimal-context-retrieval.md)

#### Playbooks

- [Controlled AI Code Change](playbooks/controlled-ai-code-change.md)
- [Read Framework Source](playbooks/read-framework-source.md)
- [Framework Knowledge Refresh](playbooks/framework-knowledge-refresh.md)

#### Cases

- [Controlled AI Code Change](cases/framework-lab/controlled-ai-code-change.md)
- [Acceptance Metric Ambiguity](cases/framework-lab/acceptance-metric-ambiguity.md)
- [Tool Contract Schema Boundary](cases/framework-lab/tool-contract-schema-boundary.md)

## 使用方式

从一个 Case 或正在解决的问题开始：先查相应 Principle，选择 Pattern，再按 Skill 或 Playbook 执行。新经验先用模板记录证据与边界，确认可泛化后再提交。阅读 [roadmap](docs/roadmap.md) 了解版本范围，贡献前阅读 [开源边界](docs/contribution-boundary.md)。

## Roadmap

v0.1 仅建立 Markdown 知识库。后续候选方向为工程资产、机器可读 Skill 和工具 Adapter；具体范围见 [roadmap](docs/roadmap.md)。

## 开源边界

仅提交通用、脱敏、可公开的工程知识。绝不提交密钥、私人数据、生产信息、未公开代码或 NDA 内容。详见 [贡献边界](docs/contribution-boundary.md)。

## License

仓库内容以 [Apache-2.0](LICENSE) 发布。对于单纯文档的再分发，使用者仍应保留来源与许可；引用的第三方材料须遵循其原许可。